fleet-dotfiles-template/docs/add-machine.md

Onboarding an additional fleet machine

Once your first machine is set up (see setup-new-fleet.md), each subsequent machine joins via this much shorter flow.

On the existing fleet (any one machine)

Add the new machine's eventual hostname + user to .chezmoidata/fleet.yaml. The pubkey can be a placeholder for now — you'll fill in the real one after the new machine generates its identity key.

fleet:
  # ... existing entries ...
  newmachine:
    user: alice
    pubkey: "PLACEHOLDER_WILL_FILL_IN_AFTER_NEW_MACHINE_RUNS_KEYGEN"

Save. The watcher commits + pushes within ~10 seconds.

On the new machine

1. Prerequisites

brew install chezmoi age duckdb

2. Get the age private key

The new machine needs the SAME age private key as every other fleet machine. Copy it from an existing machine via:

• Encrypted USB drive
• Password manager attachment
• 1Password Secure Notes
• Encrypted message (Signal, iMessage, etc.)

Place at ~/.config/chezmoi/key.txt and chmod 600 it.

Do NOT use plain email, Slack, or any cloud sync that decrypts at rest.

3. Initialize chezmoi from the fleet's forge

chezmoi init https://<forge>/<you>/fleet-dotfiles.git
chezmoi apply

chezmoi apply will:

• Decrypt secrets.env and write it to ~/.config/fleet-dotfiles/.
• Render the launchd plists with this machine's $HOME, write them to ~/Library/LaunchAgents/.
• Run the run_onchange script which loads the watcher, puller, and pull-fleet daemons.
• Run the modify_authorized_keys script which appends every existing fleet machine's pubkey to ~/.ssh/authorized_keys.

4. Generate this machine's identity SSH key

[ -f ~/.ssh/id_ed25519 ] || ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ""
cat ~/.ssh/id_ed25519.pub

Copy that pubkey.

5. Update fleet.yaml with the real pubkey

chezmoi edit .chezmoidata/fleet.yaml

Replace the placeholder you set in step 0 with the real pubkey.

chezmoi apply

The watcher fires, commits the change, pushes it. Within ~7 minutes, every existing fleet machine pulls the update and adds the new pubkey to its authorized_keys.

6. Verify mesh SSH

From the new machine, try SSHing into one of the existing peers:

ssh <existing-peer-hostname> 'echo OK from $(hostname -s)'

If it returns OK from <peer>, mesh is working. If it prompts for a password or rejects, wait a few minutes (the puller hasn't fanned out the new pubkey yet) or run chezmoi update --force on the peer manually.

7. Install task-durations (optional)

git clone https://gitea.tojo.team/cardinale/task-durations.git ~/.claude/scripts/task-durations
chmod +x ~/.claude/scripts/task-durations/*.{py,sh}
python3 ~/.claude/scripts/task-durations/extract.py

The pull-fleet launchd job (already registered by step 3) will start mesh-rsyncing peers' parquets on the next 5-minute tick.

8. Confirm

launchctl list | grep -E "chezmoi|taskdurations"
chezmoi diff   # should be empty (everything in sync)

You're done.

Removing a machine

If a machine is decommissioned or lost:

1. On any remaining machine, edit .chezmoidata/fleet.yaml to delete the entry.
2. chezmoi apply (or just save — watcher will fire).
3. Every remaining peer will, on next apply, NOT re-add that pubkey to its authorized_keys. Note: existing entries are NOT removed by the modify_ script — you'll need to manually ssh-keygen -R or hand-edit ~/.ssh/authorized_keys to remove the line.
4. Rotate any secrets the lost machine had access to (since it could have copied the unencrypted ~/.config/fleet-dotfiles/secrets.env to disk).