dotfiles

Acquiring good taste comes through using various things, discarding the ones you don't like and keeping the ones you do. if you never try various things, you will not acquire good taste.

And what I mean by taste here is simply the honed ability to distinguish mediocrity from excellence. This will be highly subjective, and not everyone's taste will be the same, but that is the point, you should NOT have the same taste as someone else.

Question the status quo, experiment, break things, do this several times, do this everyday and keep doing it.

— If you don't tinker, you don't have taste

My nix-darwin and NixOS configuration.

My daily driver is macOS because I prefer the Apple desktop environment. There are also a NixOS homelab server (running as a Proxmox VM) and NixOS VM setups mainly for experiments.

Overview

• Nix flakes provide a reproducible, pin-exact configuration shared across all machines.
• On macOS, nix-darwin manages system-level settings and packages declaratively.
• home-manager manages the user environment (dotfiles, packages, shell) across both macOS and NixOS hosts.

Highlights

• Terminal: Ghostty, using its built-in splits and tabs instead of a multiplexer
• Font: Berkeley Mono™ Typeface
• General zsh configuration:
  • Prompt: Starship with a customized Pure prompt
  • Theme: Catppuccin Macchiato (Blue accent wherever available)
  • A number of handy aliases and functions and shell scripts
  • Automatic shell proxy propagation from macOS settings
• CLI apps of choice:
  • Editor: Helix
  • Shell History: Atuin
  • Git TUI: lazygit (a quick starter video)
  • File Manager: Yazi (invoke with y for shell integration)
  • Directory Navigation: zoxide
  • fzf shell integration
    • CTRL-T - Paste the path of selected files and directories
    • ALT-C - cd into the selected directory
  • fzf-tab for fuzzy-searching zsh completion results, including a smart preview window

Custom Shell Shortcuts & Functions

Keybindings

Custom Zsh keybindings are configured in home/modules/shell/keys.zsh.

This is designed to work with default Ghostty macOS keybindings, or the iTerm2 Natural Text Editing keymappings preset.

Keybinding Reference

Key Combo	Description
Ctrl+U	Delete everything to the left of the cursor
Ctrl+X then Delete	Delete entire line to the left of cursor
Ctrl+B	Jump to beginning of line
Alt+Q	Push aside current command line to type a new one (re-inserted on next prompt)
Ctrl+X then Ctrl+_	Redo last undone edit
Ctrl+X then Ctrl+E	Edit current command line in $EDITOR
Alt+V	Show next key combo's terminal code and description
Alt+Shift+S	Prefix current/previous command with sudo

Custom Functions

Shell functions are defined in home/modules/shell/functions.zsh.

A non-exhaustive list:

Video & Media

• burnsrt <input.mp4> <input.srt> <output.mp4> - Burn SRT subtitles into MP4 video
• shrinkvid <input> <output> [bitrate] - Compress video (uses hardware acceleration on macOS)
• impaste > file.png - Output clipboard image data to stdout
• favicon <input.png> - Generate multi-size favicon.ico from an image
• dirtypdf <input.pdf> <output.pdf> - Apply scanner effect to a PDF

Development & Git

• gg <repo-url> - Clone repo and cd into it
• aic - Generate conventional commit message using LLMs from staged changes
• e [file] - Edit file with $VISUAL, or open current directory if no argument
• s <pattern> - Search in files and visualize with Delta

Directory & File Management

• take <dir> - Create directory and cd into it (equivalent to mkdir -p && cd)
• tt - Create and cd into a temporary directory
• cdls <dir> - Change to directory and list its contents
• decrypt_pdfs <password> - Decrypt all PDFs in current directory

Network & Diagnostics

• t <host> - Traceroute with Trippy (auto-updates GeoIP database)
• tu <host> - UDP traceroute with Trippy
• https <domain> [port] - Show TLS certificate details (default port: 443)
• ttfb <url> - Measure Time To First Byte with curl
• listening [pattern] - List all processes listening on TCP ports
• pingu <host> - Ping until success or cancelled
• lip <ip> - Lookup IP address details
• dns <domain> - Lookup IP address of domain's A record

Nix Utilities

• nix-pkgdir <package> - Get the Nix store path for a package
• nr <package> [args...] - Run a package from nixpkgs-unstable without installing
• ns <pkg1> [pkg2...] - Start a shell with packages from nixpkgs-unstable

Usage Instructions

Commonly used commands in justfile

# Switch darwin configuration
just switch

# Updates all flake inputs
just update

# Updates one flake input
just update-input <flake-input-name>

# For more, run `just` to get all recipes.

Installation instructions on a new macOS machine without Nix installed

Make sure the username aligns to the one specified in flake.nix (ale).

Full Disk Access has to be enabled for the terminal app via System Settings > Privacy & Security > Full Disk Access to overcome Could not write domain com.apple.universalaccess; exiting when applying user defaults.

xcode-select --install

# Install Homebrew (manages GUI apps)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install 1Password and login manually so credentials are present
brew install --cask 1password

# Clone the dotfiles
mkdir $HOME/.config
git clone https://github.com/birkhofflee/dotfiles $HOME/.config/dotfiles

Install Determinate Nix using the macOS package, then:

# Temporarily mitigate 'too many open files' issue
# @see https://github.com/NixOS/nix/issues/6557
ulimit -n 4096

# Pre-seed GitHub's SSH host key so the private secrets input doesn't stall
mkdir ~/.ssh
ssh-keyscan -H github.com >> ~/.ssh/known_hosts

# Add the current user to trusted-users so --accept-flake-config is honoured,
# allowing Nix to use the binary caches declared in the flake's nixConfig.
echo "trusted-users = $USER" | sudo tee -a /etc/nix/nix.custom.conf

# Activate the configuration
nix run nixpkgs#nh -- darwin switch $HOME/.config/dotfiles --hostname AlexMBP --accept-flake-config

nixos-server-01 (moved out of this repo)

nixos-server-01 — the Proxmox VM on the homelab-nuc PVE host — is configured from ~/Documents/Infrastructure/Homelab, including its provisioning docs. It is no longer defined here, and just switch-nixos-server / just deploy-server are gone with it.

This repo still depends on that host in two places, deliberately: hosts/nixos-desktop-01/remote-builder.nix forwards every desktop build to it, and just cache-determinate / just build-desktop-image both build there.

The nixos-anywhere and nixos-facter plumbing is still wired into mkSystem (and the low-RAM patch is still applied) for future hosts, but no host in this repo currently uses it.

Provisioning nixos-desktop-01 (NixOS desktop VM)

nixos-desktop-01 is a Proxmox KVM VM with GNOME DE. Remote desktop is provided by Gnome Remote Desktop on port 3389 (RDP).

List of RDP clients available on macOS

1. Build the VMA image

# Syncs working tree to nixos-server-01 and builds there (x86_64-linux).
just build-desktop-image

2. Upload to PVE (run on nixos-server-01)

rsync -avz /tmp/dotfiles-build/result/vzdump-qemu-nixos-desktop-01.vma.zst root@homelab-nuc:/var/lib/vz/dump/

3. Restore as VM on PVE

# SSH into homelab-nuc
# Assuming VM ID 201

# Stop the current VM
qm stop 201

# This creates (or replaces) VM 201 with our image.
# QEMU config is baked in. Starts the VM afterwards.
qmrestore /var/lib/vz/dump/vzdump-qemu-nixos-desktop-01.vma.zst 201 \
  --unique true \
  --storage local-lvm \
  --force \
  --start

--unique true is required — the image has a zeroed MAC address by default.

4. Connect via RDP

Once the VM is up, it should be connected to Tailscale automatically (if the authkey given was valid).

If RDP fails somehow:

• RDP client-side config use redirection server name:i:1 may be required to connect.
• On macOS, try to use Thincast Remote Desktop Client instead.
• SSH to the VM and check status using sudo grdctl --system, ss -tlnp | grep 3389, sudo systemctl status gnome-rdp-setup gnome-remote-desktop

6. Apply config changes after provisioning

just switch-nixos-desktop

Other Notes

• Development Environments should be managed using nix-shell.
• While I'd like Nix to handle every app on my Mac, most GUI apps are better managed by Homebrew due to the conflicting nature of Nix and the self-updating capabilities of those apps.

Articles

Here are some reads you might find interesting:

• Faster and enjoyable ZSH (maybe)
• Comparison of ZSH frameworks and plugin managers
• fzf examples (fzf wiki)
• A simple dotfiles template to kick-start/bootstrap your zsh config

Some completions setups:

• https://github.com/mashehu/dotfiles/blob/236af8d7d71989f9755a6ea29ee66e33cbbce1f8/zshrc#L89-L105
• https://github.com/finnurtorfa/zsh/blob/master/completion.zsh

Acknowledgements

This project was heavily inspired by other open-source dotfiles. A non-exhaustive list:

• mitchellh/nixos-config
• malob/nixpkgs
• ahmedelgabri/dotfiles
• kornicameister/dotfiles
• Aloxaf/dotfiles
• paulmillr/dotfiles
• mashehu/dotfiles
• finnurtorfa/zsh

Credits are given in the source code where applicable.

License

This project is released under the MIT License.