Hooks

Run commands at fixed points during the bootstrap process.

Hook commands are shell script strings: each runs as sh -c on the target (as the SSH user, unprivileged; elevate explicitly with sudo where needed (passwordless, since Panix cannot answer prompts)). Use POSIX syntax: on Debian-family targets sh is dash, so bash-isms like [[ or arrays will fail.

The Nix installer bootstrap runs only post_bootstrap_hooks, after the installer. The post_bootstrap_install_hooks and post_bootstrap_provisioned_hooks stages are NixOS-bootstrap-only and never run in the Nix installer bootstrap.

Hooks run as part of a bootstrap that actually runs; they do not trigger one, so on a machine that is already bootstrapped (or already has Nix) they are skipped unless force_bootstrap is set.

Hook	When it runs	SSH used
post_bootstrap_hooks	After disko partitioning, or after the Nix installer (Nix installer bootstrap)	Bootstrap SSH for the NixOS bootstrap (regular SSH when force-bootstrapping without bootstrap SSH configured); regular SSH for the Nix installer bootstrap
post_bootstrap_install_hooks	After nixos-install, before reboot	Bootstrap SSH (regular SSH when force-bootstrapping without bootstrap SSH configured)
post_bootstrap_provisioned_hooks	After reboot into new system (immediately in the installer when automatic reboot is disabled, over bootstrap SSH)	Regular SSH

Special Hook Commands

• waitForOnline: Wait for machine to become reachable (useful after reboot)
• waitForOffline: Wait for machine to become unreachable (useful during reboot)

These two are exact-match keywords, not shell commands: anything else, including waitForOnline && echo up, runs as a shell script via sh -c.

Example

Fragment: nest under fleet.flakes.<flake>.installables.<type>.<name>.machines.

machines:
  server:
    bootstrap:
      post_bootstrap_hooks:
        - systemd-cryptenroll --tpm2-device=auto /dev/sda2
      post_bootstrap_install_hooks:
        - echo "Installation complete, preparing for reboot"
      post_bootstrap_provisioned_hooks:
        - reboot # second reboot
        - waitForOffline
        - waitForOnline
        - systemctl enable --now my-service

Disable Automatic Reboot

To prevent automatic reboot after nixos-install (useful for manual inspection or custom reboot handling):

Fragment: nest under fleet.flakes.<flake>.installables.<type>.<name>.machines.

machines:
  server:
    bootstrap:
      disable_automatic_reboot: true

When automatic reboot is disabled, post_bootstrap_provisioned_hooks still runs immediately after nixos-install, inside the installer environment over bootstrap SSH, before any reboot.