Skip to content

Adding a host by hand

The installer is the normal path (see the quickstart), but a host is just files — nothing about it requires the wizard.

hosts/example/ is the reference shape. Copy it:

cp -r hosts/example hosts/myhost

Then edit, in order:

  1. config.nix — the bundle list (uncomment what you want; every bundle is listed, see the reference), locale, and bootTheme.
  2. default.nix — usually just networking.hostName needs to change; the imports (locale module, core profiles) stay as-is unless you're changing locale.
  3. hardware.nix — real hardware needs real detection. The shipped version is a generic virtio/UEFI profile for VM testing; for bare metal, replace it with what nixos-generate-config produces on the target (or adapt from a real host's hardware.nix if you're migrating one). Either way, replace networking.hostId with a fresh value (head -c 8 /etc/machine-id on the target) — the example's own value is exactly that, an example, and ZFS needs every host to have a different one.
  4. disks.nix — pick a storage template (see Storage modes and Architecture) and set the real device path(s).
  5. users/<name>.nix — copy users/example.nix, set a real username and your own SSH public key(s).
  6. hosts/fleet.nix — add an entry if you want this host known to others (see Administration); skip this entirely for a single standalone machine.

Then build it:

nix run .#myhost-vm      # QEMU, headless — fast config check
gisnix update myhost     # on the real machine

gisnix update resolves hosts through hosts/fleet.nix, so give the host an entry there (step 6) even for a standalone machine; sudo nixos-rebuild switch --flake .#myhost works without one.

Registering a test

tests/test-example.nix is the pattern for a NixOS integration test — copy it, point _module.args.hostname and the imported user file at your host, and add an entry to tests.nix so nix flake check picks it up.