Remote unlock

A host with an encrypted root cannot finish booting on its own. It comes up into a minimal initrd, joins the network, and waits for someone to supply the passphrase before the real system can start. Navi drives that unlock remotely, so an encrypted machine rejoins the fleet without a console or a person in the room.

This is the disk-decryption step of the lifecycle: the node is provisioned and installed, but each boot pauses until its volumes are unlocked.

The NixOS side

Encrypted hosts run an SSH server in initrd so Navi can reach them before the disk is open. On the NixOS side this is the usual boot.initrd.network and boot.initrd.network.ssh configuration that brings up networking and an early-boot SSH daemon with its own host key and authorized keys.

Declaring unlock on a node

Navi's side is deployment.unlock. It tells Navi how to connect to the initrd and what to run there. The defaults assume a ZFS root on the standard initrd SSH port:

rack-01 = { ... }: {
  deployment.unlock = {
    enable = true;
    passwordCommand = "pass show hosts/rack-01/zfs";
    remoteCommand = "zfs load-key -a && killall zfs";
  };
};

The important fields are:

• enable turns on unlock support for the node.
• passwordCommand is a local command whose output is the passphrase. Keeping it a command means the passphrase is never written into the Hive.
• remoteCommand is what runs in the initrd to load the keys. The default imports the pool and loads ZFS keys; override it for other setups.
• port, host, and user override the initrd SSH endpoint when it differs from the running system's. port defaults to 2222.
• forceHwLink routes the unlock connection through a physical interface, bypassing an overlay network such as Tailscale, for hosts reached on a LAN.

Unlocking a host

With unlock declared, navi disk-unlock connects to the initrd and runs the unlock for you:

navi disk-unlock rack-01

The passphrase is fetched by the node's passwordCommand, and the remoteCommand loads the keys. Once they are loaded, initrd proceeds and the host finishes booting.

Recovering a host after reboot

When a host reboots and stalls waiting for its passphrase, the same command brings it back. The command-line flags override the declared settings for a single run, which is useful during recovery when the address or credentials differ from the norm:

navi disk-unlock rack-01 \
  --password-cmd "pass show hosts/rack-01/zfs" \
  --remote-cmd "zfs load-key -a && killall zfs" \
  --address 10.0.0.10 \
  --user root

The same shape drives lower-level recovery — inspect the pool, mount a dataset, or force a reboot — by changing only the remote command:

navi disk-unlock rack-01 --address 10.0.0.10 --user root \
  --remote-cmd "zpool status; echo '-----'; mount"

navi disk-unlock rack-01 --address 10.0.0.10 --user root \
  --remote-cmd "reboot -f"