Installation and recovery

Installing a machine is not a special mode. It is a lifecycle composed into the same reviewed action graph as everything else, with the same digest-bound approval and the same risk classification.

The division of ownership is deliberate: your topology selects the target and its provisioning, the infrastructure provider (Proxmox, VMware, DigitalOcean) establishes the guest, and the Nix provider owns realization, transport, Disko, kexec, first boot, and convergence.

Three install modes

--install-mode selects the policy for an existing guest:

These have distinct approval requirements, because they have distinct consequences. Before any destructive transition, NXD validates required secrets, disks, storage, network, cache, builder, source and target identity, and replacement preflight. A destructive install that cannot satisfy its preconditions refuses before it touches anything.

Conversion

--intent convert takes over an existing machine via kexec, managing the declared source transition only.

If a destination guest is involved, it is reconciled by its owning provider as normal work — a conversion never silently creates or deletes a guest as a side effect.

Bootstrap trust is temporary

Installing a machine requires trust that the finished machine must not keep.

Bootstrap services are bounded, scoped to one operation, authenticated, and removed or disabled at handback. Operation-private trust never becomes ambient steady-state trust. A key that existed to install a machine does not survive into its running configuration.

A bootstrap server serves only the reviewed operation and its allow-listed artifacts, on its configured interface and port, with connection, request, and size limits. It re-attests file descriptors before serving and cleans up on success, failure, cancellation, and timeout.

SSH-agent access during an operation is a typed binding. Its socket is never copied into desired state or inherited indiscriminately.

Takeover, reconnect, DHCP re-observation, first boot, and stable-trust handback each have explicit bounded timeouts and postconditions, so a stalled install fails cleanly instead of hanging.

Installing on low-memory machines

Low-memory installation uses the reviewed takeover and build strategy rather than a separate code path. Disko and bootstrap work may use a bounded tmpfs, while large system realization uses the configured cache or a compatible builder — so the constrained machine never has to hold work it cannot finish.

See build placement for choosing where a build happens.

Artifacts are immutable and attested

Installer, PXE, WSL, and recovery artifacts are immutable outputs carrying a manifest, checksum, provenance, a non-empty SBOM, and a source revision.

Providers consume reviewed artifacts. Consumers declare source identity, answer and first-boot content, output identity, and site values — they do not maintain derived store paths by hand.

Two rules protect secrets in installer media:

1. Any answer file or media containing a secret is materialized only inside the reviewed action, from an action-scoped confidential input. It is excluded from the Nix store and from the public manifest, and removed on success, failure, cancellation, or timeout.
2. Public handoff evidence binds artifact role, product, version, source digest, prepared digest, storage identity, and run-created ownership. It never contains artifact bytes, secret bytes, or rendered secret fields.

Capture and recovery

Capture and recovery operate on the selected producer and bounded artifacts only — never the whole site.

Capture refuses to write through a symlink, refuses an existing destination, and refuses an unsafe directory, so a capture cannot be redirected into overwriting something it should not.

For full details, see docs/architecture-design/installation-and-recovery.md in the repository.