Installation

The private halves are gitignored, so staging them means reading the working tree — which pure evaluation forbids. bin/emanix-iso passes --impure for you, and the private keys are copied into /nix/store (world-readable) on the way into the image. Delete those store paths once the ISO is written; a reference script can do this for you, but then it must match every staged name (see the join-key note below).

A build whose keys directory holds only .pub halves fails at build time, on purpose. The alternative is an ISO that looks key-carrying, boots, and then dies at the installer's preflight on the target's console.

The ISO can also carry one more credential, a preauthkey, that lets the freshly installed machine join your tailnet without anyone typing a long key at its console.

How to stage it. Put one file named tailscale-preauthkey in the directory that emanix.installer.keysDir names, beside the host keys. If the file exists at build time, the ISO carries it at /etc/emanix/tailscale-authkey, and the login banner lists that path. There is no option for it; the file name is the convention. It is staged only when keysDir is set, so a keyless build (--no-keys) carries none.

Why it travels with the host keys. It is the one credential a fresh machine cannot get for itself. Your coordination server is unreachable until the join succeeds, and the machine has no key with which to ask another machine to mint one. It is the same kind of thing as a host key — a credential that lets a new machine identify itself — so it rides in the same place.

What kind of key to use. A reusable key with a long expiry. A short-lived key expires before you use the ISO, and then it fails at the moment of need and looks as if the staged key was ignored. How you mint the key depends on your coordination server; the distribution does not prescribe one.

What reads it. Nothing in the distribution. The installer (fresh-emanix-install) does not read the file and does not copy it onto the installed disk. The join itself is your flake's job, in the script you give emanix.firstboot.text (see Options) or in your own tooling. A script that runs after the first reboot finds the file only if your tooling put it on the installed system. The distribution ships no tailnet join of its own.

One build check treats the file with care: it does not count as a host key. A keys directory that holds only the preauthkey and public halves still fails the build, because the ISO would carry no identity.

Warning: the preauthkey is a credential, and building it into an ISO writes it to the Nix store. Anyone who can read the .iso file, or the store path, can join a machine to your network until the key expires. The build copies the key file into its own store path, whose name ends in tailscale-preauthkey, in addition to the copy inside the emanix-keys directory path. Delete both after the build, and keep the .iso as carefully as the key. A cleanup that matches only the emanix-keys name leaves the key file behind. Your build script is the place to do this; the distribution ships none.

Anything missing aborts before the disk is touched.

The fingerprint check is the one worth calling out. It compares the staged private key against keys/<host>_host_ed25519.pub — the actual recipient your secrets are encrypted to — and fails closed on a mismatch. That check exists because the alternative is discovering the wrong key after the disk is gone.

Disk auto-detection picks the largest non-removable, writable device with no mounted partitions, which skips the stick you booted from. The installer also cross-checks that against the device your disk layout declares and refuses to continue if they disagree — a disagreement usually means a VM, or the wrong pick.

The stages are numbered, so a long step is visibly a step and not a hang.

• Asks you to type yes to wipe the target — once. disko's own second confirmation is suppressed, because you have already answered it and it would block any unattended install
• Partitions and formats with disko (destroy,format,mount), prompting for a disk-encryption passphrase if the layout declares LUKS. This prints a wall of + ... shell tracing; that is normal output, not errors
• Installs a host key to /mnt/etc/ssh/ — the staged one for a known host, a freshly generated one for a new machine, which has no secrets to decrypt
• Runs nixos-install
• Prompts for the primary user's password, retrying rather than leaving a passwordless account behind
• Offers to reboot

Remove the stick on reboot.

The nixos-install step is the long one, and it is long for a reason worth understanding rather than waiting through.

Most of what a desktop host needs for its Emacs and compositor comes straight from cache.nixos.org, but some of it does not and is compiled on the machine you are installing: ewm-core (Rust, via Smithay), the Emacs itself on the base the host runs (the pwayl/Skia 31.1 fork under EWM, pgtk 31.1 otherwise — see Components), and the Emacs Lisp packages built against it. The exact counts change whenever the base or the package list does, so none is quoted here.

The Lisp is uncacheable for a structural reason. Every Emacs package is built against the host's own Emacs base, so even entirely ordinary packages — xref, project, eldoc — exist in the public cache only as builds against a different Emacs. Change the Emacs and all of them rebuild.

The output is small, so this costs CPU time rather than bandwidth and it scales with how many cores the machine has. Nothing is wrong while it runs.

A binary cache would remove the step entirely, and that is the intended fix. Until it exists, budget for it.

Six questions, in this order:

Network is not a question — it checks, and only involves you if there is no route, in which case it offers to open nmtui.

The graphics answer matters more than it looks. EWM launches from tty1 and loses the DRM-master race unless the driver is in the initrd, so a wrong answer here is a black screen on a machine whose owner has no other console. It is asked rather than assumed for exactly that reason.

A complete flake in /etc/nixos, whose only machine-specific file is host.nix:

{
  hostName   = "testbox";
  device     = "/dev/vda";
  luks       = false;
  filesystem = "btrfs";
  swapSize   = "2G";
  gpu        = null;              # "amd" or "intel" on a graphical host
  hardwareModule = null;          # a nixos-hardware module, if you know yours
}

Everything else in that flake reads from those values. The disk layout comes from emanix.lib.mkDisk, so the disk parameters above are the whole description of the machine's disk; gpu is the only other thing a graphical host must set.

Before anything is erased the installer prints your answers back — hostname, username, encryption, filesystem, swap, graphics — immediately above the wipe confirmation. The preflight proves the machine is ready; that block is how you check the installer understood you.

You land in Emacs. It is the desktop here, not an application inside one.

A welcome buffer opens on the first start with those keys and a pointer back here. Dismiss it with q for now, or n to never see it again.

Do not run emanix-firstboot on a machine installed this way. That command is the consuming flake's seam — it runs whatever your flake put in emanix.firstboot.text, and a generated host has set nothing, so it prints a message about configuring it and exits. It is for a fleet, not for a machine the installer just invented.

The installer leaves a working flake in /etc/nixos. That is enough to run and not enough to live in: root-owned, no git, nowhere to put a secret.

emanix-init

This copies it to ~/flake, initialises git, adds a keys/ directory whose .gitignore commits the public halves and never the private ones, records this machine's own public host key as a future secrets recipient, and runs nix flake check to prove the result still evaluates. It refuses rather than overwrites, and leaves /etc/nixos untouched, so a failed adoption costs nothing.

The welcome buffer offers this as [i] when it finds no config repo.

Rebuild from there afterwards:

sudo nixos-rebuild switch --flake ~/flake