Behind the scenes
From one lab definition to running PCs.
Nixorium turns the lab configuration into complete NixOS systems on the controller. It then uses one LAN path to install an empty machine and another to update a machine that is already managed.
Lab definitionPrivate deployment + pinned Nixoriumsettings · modules · public keys · assets
Controller
- 01Evaluate
- 02Build
- 03Serve
Client systemsinstalled locally · activated as NixOS generations
01 · System model
Bootstrap the controller, then define the lab.
The first installation creates the machine that will build and deliver every other system. From that point, the reusable project and the private site definition have different owners.
- 01 · Live environment
Select the source and controller disk
The controller starts from an official NixOS live USB with temporary Internet access. The bootstrap resolves the selected Nixorium version and confirms the disk it will erase.
- 02 · Generated deployment
Create the private site repository
A deployment is generated from the versioned template and pins Nixorium as its upstream. The controller is installed from that deployment using initial placeholder settings.
- 03 · Site ownership
Replace placeholders and establish trust
After reboot, the operator records the real topology and users, adds public cache, SSH, and Veyon keys, keeps private keys on the controller, and rebuilds it as the lab authority.
Nixorium
Versioned modules, installers, defaults, and the function that generates the fleet.
Pinned by the deploymentYour lab
Site settings, host overrides, assets, password hashes, and public cache, SSH, and Veyon keys.
Private keys stay on the controllerNamed systems
A controller, each client, the netboot environment, deployment metadata, and the installer bundle.
One source of desired stateThe deployment pins a Nixorium release and its dependencies. Changing a value does not edit a running machine in place; it changes the input from which the relevant system is evaluated and built.
Controller bootstrap Deployment Flake Configuration schema Fleet generator
02 · Preparation
The controller prepares complete systems.
The clients are delivery targets. Evaluation, builds, boot artifacts, and the local cache are prepared at the controller boundary.
- 01
Evaluate the lab
The typed site settings generate a named NixOS configuration for every client, a separate controller configuration, a netboot environment, Colmena deployment metadata, and a self-contained installer bundle.
- 02
Build on the controller
Pinned inputs and the shared configuration produce each client system and its complete dependency set, plus the kernel, initial ramdisk, and iPXE instructions needed for network installation.
- 03
Publish inside the LAN
Harmonia exposes signed Nix store paths. The PXE helper exposes the small boot chain. Clients consume prepared outputs locally instead of resolving and building them from the Internet.
03 · Network install
PXE starts a short chain into a complete local install.
The boot protocol only gets the workstation into the installer environment. The final NixOS system is installed on the workstation’s disk and normally boots from there.
- 01DHCP + ProxyDHCP
Discover the boot service
The institutional DHCP server continues to assign the lease. Nixorium’s dnsmasq process answers only the network-boot discovery request and points UEFI firmware at the controller.
- 02TFTP
Chain into iPXE
The firmware receives a small UEFI iPXE binary. iPXE then receives the generated boot script from the same controller.
- 03HTTP
Load the installer environment
The boot script downloads the prepared NixOS kernel and initial ramdisk over HTTP. The ramdisk contains the deployment-specific installer source.
- 04Disko + NixOS
Realize the selected workstation
The operator identifies the PC and confirms the target disk. Disko applies the declared UEFI and Btrfs layout; NixOS installs that PC’s configuration using signed paths served by Harmonia.
- 05Local disk
Leave the network installer
After installation, the workstation boots from its own disk. PXE is the entry path for installation and recreation, not a dependency for every normal boot.
The client does not contact the Internet during this path.
Its boot artifacts and prepared Nix store paths come from the controller. This works behind a captive portal or under a policy that denies direct client Internet, provided the required local boot, HTTP, cache, and SSH traffic is allowed.
The controller still needs Internet for initial setup and for new inputs that are not already available. Nixorium does not authenticate to a captive portal or bypass network policy.
PXE helper source Client installer source Disk layout source
04 · System updates
Colmena coordinates activation on managed clients.
Once a workstation is installed, normal system deployment follows its static lab address over SSH. It does not repeat the PXE and disk-installation path.
- 01ChangeEdit or update the pinned lab definition
- 02BuildProduce the selected systems on the controller
- 03ServeExpose signed store paths through Harmonia
- 04DeployColmena reaches one client or the lab group over SSH
- 05ActivateNixOS records the new system generation
The controller’s own configuration is applied separately before client rollout. The operator can target a pilot workstation first, review it, and then extend the same evaluated change to the lab group. Deployment is an explicit operator action.
Colmena host definitions Client cache configuration NixOS generations and rollback
05 · Components
Each tool has one bounded job.
Nixorium composes these tools into the lab workflow. Their names matter here because this page explains the implementation boundary.
| Component | Job in Nixorium | Phase |
|---|---|---|
| Nix Flakes | Pin the Nixorium framework and its inputs, then expose the evaluated lab outputs. | Definition |
| NixOS module system + mkLab | Validate site settings and generate controller, client, netboot, installer, and deployment configurations. | Evaluation |
| Nix builder and store | Build the system closures and boot artifacts from the pinned definition on the controller. | Build |
| Harmonia | Serve signed Nix store paths from the controller to clients on the local network. | Install + update |
| dnsmasq, TFTP, HTTP, and iPXE | Direct UEFI clients into the prepared kernel and ramdisk without replacing institutional DHCP. | Install |
| Disko | Apply the declared partition and filesystem layout to the operator-confirmed installation disk. | Install |
| Colmena + OpenSSH | Address one client or the lab group and coordinate remote activation from the controller. | Update |
| NixOS generations | Record activated system configurations so a previous system generation remains available for rollback. | Activation |
06 · Boundaries
What the architecture assumes.
The local-first path removes direct client Internet as an installation and update dependency. It does not remove the need for a planned network, a trusted controller, or operator review.
- Controller connectivity
- Internet is required for bootstrap and new software inputs that are not already available.
- Client connectivity
- Direct Internet is not required for prepared installation or system updates; access to the controller over the permitted LAN is required.
- PXE addressing
- Generated boot artifacts refer to the controller’s DHCP address. If it changes before a netboot session, those artifacts must be rebuilt.
- Routine deployment
- Colmena reaches installed clients at their static lab addresses over SSH.
- Boot and disk
- The current standard installer requires x86_64 UEFI and erases the operator-confirmed target disk.
- Trust and control
- Cache signatures, SSH keys, private deployment data, target selection, and rollout remain operator responsibilities.