macOS system configuration managed with nix-darwin and Nix flakes.
A flakes-only nix-darwin configuration for M4 Max MacBook Pro. Manages macOS system-level settings: system packages, Dock, Finder, keyboard, security, Homebrew, and LaunchDaemons -- all declaratively. User-level configuration (dotfiles, dev tools, LaunchAgents) is managed by nix-home and nix-ai, imported as flake inputs.
Part of a trio:
| Repo | Scope | Installs via |
|---|---|---|
| nix-darwin (this repo) | macOS system config (Dock, Finder, Homebrew, security) | nix-darwin |
| nix-ai | AI CLI ecosystem (Claude, Gemini, Copilot, MCP) | home-manager |
| nix-home | User environment (dotfiles, dev tools, LaunchAgents) | home-manager |
- macOS on Apple Silicon (aarch64-darwin only -- x86 Mac is not supported)
- Determinate Nix installer: https://install.determinate.systems
- git
# 1. Clone as a bare repo (worktree convention used throughout ${GIT_HOME})
git clone --bare https://github.com/JacobPEvans/nix-darwin.git ${GIT_HOME_PUBLIC}/nix-darwin
cd ${GIT_HOME_PUBLIC}/nix-darwin
# 2. Create the main worktree
git worktree add main main
# 3. Build and activate for the first time
cd ${GIT_HOME_PUBLIC}/nix-darwin/main
sudo darwin-rebuild switch --flake .# Rebuild after config changes
d-r
# Search for a package
nix search nixpkgs <name>
# Rollback if something breaks
sudo darwin-rebuild --rollbackThe d-r alias (defined in nix-home) expands to sudo darwin-rebuild switch --flake .
and handles full system + home-manager activation in one step.
See RUNBOOK.md for detailed operational procedures.
aarch64-darwin only. This configuration targets Apple Silicon Macs.
The quality checks (nix flake check) run cross-platform (Linux/x86 too),
but the Darwin configuration itself only builds and activates on aarch64-darwin.
Formatting and linting run automatically on every commit via pre-commit hooks
(nixfmt, statix, deadnix, shellcheck). BATS shell tests run via nix flake check
and CI -- not on each commit.
To install the hooks locally:
nix shell nixpkgs#pre-commit -c pre-commit install- Nix packages via nixpkgs (preferred over Homebrew)
- macOS system defaults (Dock, Finder, keyboard, trackpad, energy)
- Homebrew (fallback for casks not in nixpkgs)
- Security settings (firewall, Gatekeeper, stealth mode)
- LaunchAgents via nix-darwin launchd modules
- Activation scripts with error tracking and recovery
See MANIFEST.md for the complete package inventory.
.
├── flake.nix # Main entry point
├── hosts/ # Host-specific configurations
│ └── macbook-m4/ # Active M4 Max MacBook Pro
├── modules/ # Reusable configuration modules
│ └── darwin/ # macOS system settings
├── overlays/ # Nixpkgs overlays
├── scripts/ # Build and CI scripts
├── lib/ # Shared configuration variables
└── tests/ # Shell and integration tests
Full details in ARCHITECTURE.md.
| Component | What It Does |
|---|---|
| Determinate Nix | Manages Nix itself -- daemon, updates, core config |
| nix-darwin | macOS packages, system settings, Homebrew integration |
| home-manager | Activation recovery, config symlinks, and Raycast scripts |
| mac-app-util | Stable app trampolines to preserve TCC permissions |
| nix-ai | Shared home-manager modules for AI tools (Claude, Gemini, Copilot, MCP) |
| nix-home | Shared home-manager modules for dev environment (git, zsh, VS Code, tmux) |
| sops-nix | Decrypts age-encrypted secrets to /run/secrets/ for system services |
System-level secrets (used by LaunchDaemons and activation scripts) are managed via
sops-nix. Encrypted YAML files live in secrets/
and are safe to commit. The age private key (~/.config/sops/age/keys.txt) is generated
once per machine and never committed.
Doppler is used for developer credentials accessed in the user session (Terraform state, API tokens, etc.). Doppler CLI requires Keychain and cannot be called from activation scripts (which run as root). sops-nix handles that boundary.
This repo is the orchestrator: it pulls in nix-ai and nix-home as flake inputs
and wires their homeManagerModules.default into the shared home-manager configuration.
Changes to AI tools or dev environment settings belong in those repos, not here.
Key Rule: Use nixpkgs for everything. Homebrew is fallback only.
| File | Purpose |
|---|---|
| RUNBOOK.md | Step-by-step operational procedures |
| ARCHITECTURE.md | Detailed structure and module relationships |
| MANIFEST.md | Complete inventory of packages and settings |
| TROUBLESHOOTING.md | Common issues and solutions |
| SETUP.md | Initial setup guide |
| CLAUDE.md | AI agent instructions |
Contributions welcome. See CONTRIBUTING.md for details.
Built by a human, refined by AI, used by both.