Clan Network Runbook #

Topology #

Machine	Mycelium IPv6	Management
chi	5ec:6edc:7495:220e:6f58:1bae:13be:cbf5	Local activation
halo	517:1053:3359:7f4a:8994:c16:4241:e900	Iroh, then Mycelium
misty	45a:adb:d00f:1128:b131:a28:551b:c1da	Iroh, then Mycelium

Mycelium carries normal host-to-host traffic without a controller. Iroh is an independent SSH transport used by Clan when the machines are behind NAT.

Operations #

nix develop -c clan network list
nix develop -c clan network ping halo
nix develop -c clan network ping misty
nix develop -c clan ssh halo
nix develop -c clan ssh misty

nix develop -c clan machines update halo
nix develop -c clan machines update misty
sudo nixos-rebuild switch --flake .#chi

chi uses misty as its remote Nix builder and binary cache over Mycelium. Generated addresses and encrypted keys live under vars/per-machine/; Nix configuration reads the addresses directly from those generated values.

Adding A Machine #

1. Add the machine to inventory.nix and assign the Mycelium peer role.
2. Register a SOPS machine recipient under sops/machines/<name>/key.json.
3. Run nix develop -c clan vars generate <name>.
4. Deploy once through an existing bootstrap route.
5. Verify with clan network ping <name> --network mycelium.

Use an Iroh server role only for machines that need remote administration. Iroh forwards SSH and relies on SSH key authentication; passwords stay disabled.

Recovery #

• halo LAN: molly@192.168.0.169
• misty LAN: molly@192.168.1.174
• Clan emergency override: clan ssh <machine> --target-host user@address
• Both servers retain normal OpenSSH and bootable previous NixOS generations.

Never store private age keys, Iroh secrets, provider tokens, or temporary bootstrap credentials in this file.