Dotfiles

Managed with GNU Stow.

Restore on a new machine

git clone <your-dotfiles-repo-url> ~/dotfiles
cd ~/dotfiles
./bootstrap
./scripts/install-tools.sh
./scripts/doctor.sh

bootstrap will:

• install Linux prerequisites for Homebrew (Linux only)
• install Homebrew if needed
• install stow if needed
• run ./install to create all symlinks

Tooling bootstrap (macOS + Linux)

Use these scripts to install package managers, runtimes, and cargo CLI tools:

cd ~/dotfiles
./scripts/install-tools.sh

This uses:

• Brewfile for cross-platform Homebrew packages
• Brewfile.macos for macOS-only packages/casks
• Brewfile.linux for Linux-only Homebrew packages
• mise.toml for language runtimes
• cargo-tools.txt for cargo-installed binaries

PHP is intentionally not managed by mise right now because Herd is in use. Current mise runtimes: Rust, Bun, Python, Node.js, Java, Gradle, and Ruby.

Validate the setup:

cd ~/dotfiles
./scripts/doctor.sh

Linux quickstart (Ubuntu/Debian)

cd ~/dotfiles
./bootstrap
./scripts/install-tools.sh
./scripts/doctor.sh
./scripts/audit-tools.sh

bootstrap/install-tools.sh will call scripts/install-linux-prereqs.sh when running on Linux.

VPS bootstrap (minimal)

Use these scripts for a locked-down Linux VPS flow:

cd ~/dotfiles
TAILSCALE_AUTHKEY=tskey-auth-... ./scripts/bootstrap-vps.sh
./scripts/install-tools-vps.sh
./scripts/doctor-vps.sh

Defaults:

• admin user: christian
• SSH keys: copies /root/.ssh/authorized_keys into christian on first run

Important flags:

• VPS_USER=... sets the admin username (default christian)
• VPS_USER_SSH_PUBKEY='ssh-ed25519 ...' appends a key for the admin user
• VPS_PASSWORDLESS_SUDO=1 (default) configures NOPASSWD sudo for the admin user
• DOTFILES_REPO=https://... clones the dotfiles repo into ~/dotfiles on the VPS
• ALLOW_PUBLIC_SSH=1 keeps port 22 open in UFW (useful for first bootstraps)
• SKIP_UFW=1 skips firewall setup
• INSTALL_VPS_CARGO_TOOLS=1 installs cargo-tools.vps.txt
• TAILSCALE_REQUIRED=0 lets doctor-vps.sh pass when Tailscale is intentionally not connected yet

Note: if Tailscale is not connected when the firewall is configured, ALLOW_PUBLIC_SSH is automatically promoted to 1 with a warning to prevent SSH lockout. Rerun the bootstrap after Tailscale is connected to close port 22.

Tooling audit

Generate a snapshot of what is currently installed:

cd ~/dotfiles
./scripts/audit-tools.sh

By default this writes files to audit/latest/.

Manual install

If you already have stow:

cd ~/dotfiles
./install

Managed packages

• aerospace -> ~/.aerospace.toml (macOS only)
• git -> ~/.gitconfig
• kitty -> ~/.config/kitty
• nu -> ~/.config/nushell
• nvim -> ~/.config/nvim
• opencode -> ~/.config/opencode/*
• pi -> ~/.pi/*
• starship -> ~/.config/starship.toml
• zellij -> ~/.config/zellij

Daily stow commands

# preview changes
stow -nv -t ~ <package>

# (re)link package
stow -R -t ~ <package>

# unlink package
stow -D -t ~ <package>

Add a new config

1. Create a package folder in this repo.
2. Mirror the target path under that package (for example foo/.config/foo/config.toml).
3. Run stow -R -t ~ foo.

Pi customizations

The pi/ package is linked into ~/.pi and is laid out for Pi's global config:

• pi/.pi/agent/settings.json — global Pi settings
• pi/.pi/agent/keybindings.json — custom Pi shortcuts
• pi/.pi/agent/extensions/ — TypeScript extensions
• pi/.pi/agent/prompts/ — Markdown prompt templates
• pi/.pi/agent/skills/ — skills with SKILL.md
• pi/.pi/agent/themes/ — theme JSON files

Runtime state like ~/.pi/agent/auth.json and ~/.pi/agent/sessions/ stays local and is not tracked in git.

See pi/README.md for a quick guide to what belongs in each folder.