Onboarding a new macOS machine with nix-darwin

onboarding-macos.md

Onboarding a new macOS machine (nix-darwin)

1. Install Nix

curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

2. Install Homebrew

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

3. Clone the config

mkdir -p ~/.config
git clone https://github.com/svnlto/nix-config.git ~/.config/nix

4. Add a new host entry

Find the hostname and username:

scutil --get LocalHostName
whoami

Add it to darwinConfigurations in flake.nix:

darwinConfigurations = {
  # Personal Mac — includes personal casks (proton, discord, zwift, etc.)
  "rick" = mkDarwinSystem {
    hostname = "rick";
    username = defaultUsername;
    extraModules =
      [ ./systems/aarch64-darwin/homebrew/personal.nix ];
  };

  # Work Mac — only shared casks, add work-specific ones via work.nix
  "<work-hostname>" = mkDarwinSystem {
    hostname = "<work-hostname>";
    username = "<work-username>";
    extraModules =
      [ ./systems/aarch64-darwin/homebrew/work.nix ];
  };
};

Homebrew cask structure

Casks are split per host type:

• systems/aarch64-darwin/homebrew/common.nix — shared across all Macs (dev tools, productivity, browsers)
• systems/aarch64-darwin/homebrew/personal.nix — personal-only (proton, discord, signal, zwift, utm, etc.)
• systems/aarch64-darwin/homebrew/work.nix — work-specific (empty placeholder, add as needed)

All hosts get common.nix via the base darwin import. Use extraModules in flake.nix to layer on host-specific casks.

5. First build

cd ~/.config/nix
darwin-rebuild switch --flake .#$(scutil --get LocalHostName)

The first run installs nix-darwin, Home Manager, and all packages. Subsequent runs use nixswitch.

6. Post-setup

• 1Password: Install manually for SSH key integration
• Shell: Restart your terminal to pick up the new zsh config

The nixswitch alias auto-detects hostname, so both machines use the same command going forward.