Dotfiles

Managed with GNU Stow. There's a helper script at bin/dotfiles that wraps the common operations.

Track a new config

./bin/dotfiles add ~/.config/foo

This moves the file/directory into the repo and symlinks it back. Done.

It works for anything under $HOME:

./bin/dotfiles add ~/.config/nvim       # whole directory
./bin/dotfiles add ~/.config/foo/bar.toml  # single file
./bin/dotfiles add ~/.somerc            # dotfile in $HOME

Linux workspace setup

For provisioning apt-based x86_64 Linux workspaces:

git clone --recursive <repo-url> ~/dev/dotfiles
cd ~/dev/dotfiles
./install.sh

The installer fails if requested setup cannot complete. It installs the base shell and editor tools, Volta-managed Node 24.18.0, Bun, Pi 0.80.6, and TPM-managed tmux plugins before stowing the portable Linux configuration. The macOS-specific git package is deliberately not stowed on Linux; the git-linux package supplies aliases and settings without an identity, signing configuration, credential helper, or machine-specific paths.

Workspace workflow

After dotfiles have been installed, ~/.local/bin/workspace-dev creates and finalizes generic x86 workspaces:

workspace-dev create ~/src/owner/repository
workspace-dev sync repository-x86 [~/src/owner/repository]
workspace-dev verify repository-x86

create derives the repository and current branch from the checkout's GitHub origin, creates repository-x86 with aws:m5d.4xlarge in us-east-1, and uses zsh. It refuses a name already shown by workspaces list. Both create and sync require an SSH agent with an identity and verify that the generated workspace-<name> alias enables agent forwarding. The remote finalization clones or fast-forwards the configured private agent repositories using credential-free SSH remotes, then reruns the dotfiles and agent installers. Pass a repository path to sync when recovering a workspace that was provisioned but had not yet recorded its primary repository metadata.

verify checks the architecture, required tools, Docker Compose, both checkouts and remotes, Pi-managed links, and a configured Git identity. The installer can perform public provisioning before a forwarded agent is available, but private repository finalization is intentionally deferred until create or sync has forwarded authentication.

Generic Linux devbox workflow

~/.local/bin/devbox-dev applies the same configuration to an existing apt-based x86_64 Linux host that is reachable through SSH:

devbox-dev sync my-devbox
devbox-dev verify my-devbox

The SSH host must use public-key authentication, enable ForwardAgent, and provide passwordless sudo. sync is safe to rerun: it refuses dirty or unexpected checkouts, installs the public dotfiles first, exports the managed organization Git configuration, pipes short-lived GitHub App credentials directly into the remote GitHub CLI, and then installs the configured private agent repositories. It never copies laptop credential files or creates a personal access token.

The first run may present an organization authentication-code flow for model gateway access. Runtime credentials, sessions, and generated model state stay on the devbox and outside both repositories. verify checks the installed tools, repository identities, GitHub and AI Gateway authentication, managed links, commit-signing configuration, and a live Pi response.

sync also maintains a small block in the devbox's ignored ~/local.zsh. Every new interactive zsh asks ddtool for a current GitHub App token and exports it as GH_TOKEN; the token itself is never written to disk. Existing shells can renew after the token's eight-hour lifetime by running ddtool-github-refresh. The block preserves unrelated private shell settings and refuses malformed managed markers instead of replacing the file.

The devbox must also have DNS and routing to the configured model datacenter. The helper reports a clear private-network error when that route is absent; GitHub access can still be healthy independently.

When adopting an already-used host, sync recognizes only the Git configuration written by git config-tool/gh and the default generated GitHub CLI preferences. The latter are preserved under ~/.local/state/devbox-dev/gh-config.pre-adoption.yml before the repository version is linked. Unrecognized Git or GitHub CLI customization causes a hard failure instead of being overwritten.

Repository names, organization names, internal paths, and service endpoints are kept in .private/dev.env, which is ignored by Git. Create it from the public placeholder template before running either helper:

mkdir -p .private
cp config/private.env.example .private/dev.env
$EDITOR .private/dev.env
devbox-dev sync my-devbox

Set DOTFILES_PRIVATE_CONFIG to use a file elsewhere. The file contains metadata, not credentials: SSH keys remain in the agent, and GitHub access uses short-lived tokens. Each contributor supplies their own ignored file, so the public repository stays reusable without publishing personal or internal details.

macOS setup

brew install stow
git clone --recursive <repo-url> ~/dev/dotfiles
cd ~/dev/dotfiles
./bin/dotfiles stow          # symlink all configs into $HOME
./bin/dotfiles stow nvim git # or just specific ones

Install other tools with brew as needed (tmux, neovim, starship, fzf, etc.).

Agent configuration

Pi and shared coding-agent configuration are managed separately in a private ~/dev/pi-config repository. Agent credentials and runtime state are never stored here.

Other commands

./bin/dotfiles list            # show all packages
./bin/dotfiles unstow <pkg>    # remove symlinks for a package

Sensitive files

Private overrides, common credential files, private keys, and runtime auth state are excluded via .gitignore. Keep credentials out of .private/dev.env as well; it is intended only for repository names, paths, organizations, and service endpoints.