macOS and Ubuntu setup for one Unix user: packages, shell and Git defaults, runtimes, coding agents, and maintenance. Private identities and secrets stay outside Git.
| Task | Guide |
|---|---|
| Choose packages and a user role | Profiles |
| Set up age, Git, SSH, and recovery | Identities |
| Configure shared-host services | Devbox |
| Update software or clean old worktrees | Maintenance |
| Configure coding agents | Agents |
| Edit managed files | Chezmoi |
| Change runtime pins or find tasks | Mise |
| Audit a repository or host | Security audits |
| Install mobile and TV tooling | Mobile and TV development |
| Change this repository | Contributing |
Edit tracked files under chezmoi/, then preview and apply with the intended profile:
mise trust
mise run dotfiles:diff workstation
mise run dotfiles:apply workstation./dotfiles apply <profile>also runs the remaining bootstrap steps.- Apply backs up conflicting files, keeping the newest backup per target. Generated agent rule files get no backup.
- Use
private_for owner-only files.exact_at home-directory scope deletes unmanaged files; keep live app and auth state out ofchezmoi add.
| Path | Use |
|---|---|
~/.ssh/config.local |
Host-specific SSH directives |
~/.ssh/config.d/*.conf |
Fragments written by other tools |
~/.config/dotfiles/zshenv.local |
Machine-specific, non-secret shell exports |
| Agent rule fragments | Private agent rules |
~/.config/dotfiles/devbox.env |
Per-user devbox settings |
- Point tools that write SSH config at their own
config.dfragment, not~/.ssh/config. - Create
zshenv.localby hand with mode0600. The shell ignores it when it or its directory is a symlink. - Apply replaces
~/.zshenvand~/.zshrcexcept blocks between# >>> NAME (managed) >>>and# <<< NAME (managed) <<<. A start line without its end fails apply and leaves the file untouched. - To stop Teleport adding keys to an incompatible SSH agent, export
TELEPORT_ADD_KEYS_TO_AGENT=noinzshenv.local.
mise.toml owns repository tasks; keep them as command delegations to domain code. Trust each checkout first, or task discovery fails:
mise trust
mise tasksLive checks inspect the current user's machine; run them only for the installed profile:
mise run verify:bootstrap workstation # the installed profile
mise run verify:devbox-services # macOS only
mise run bootstrap:trust-agent-worktrees # re-trust existing agent worktreesEdit the profile template or the
darwin or
linux sibling that owns the pin,
preview with mise run dotfiles:diff <profile>, and run mise run verify.
mise-tasks.toml owns packages
installed inside runtimes.
- Keep the templates plain TOML with exact versions so Renovate can parse them. renovate.json owns holds and pins that move together.
- Package-only pin changes converge through
./dotfiles apply; a plainmise installskips thedotfiles:runtime-packagestask. - A checkout's
rust-toolchain.tomloverrides the rust pin; a project'spackageManagerordevEnginesoverrides the pnpm pin.