Behind the scenes
Two installation transports. One declared system.
Nixorium turns the lab configuration into complete NixOS systems on the controller. A blank machine uses PXE or the official NixOS ISO over reviewed USB/SSH; an installed machine receives an update from Nixorium’s own engine; normal desktop work runs locally.
Lab configurationYour lab configuration + pinned Nixoriumsettings · modules · public keys · assets
Controller
- 01Evaluate
- 02Build
- 03Serve
Client systemsinstalled locally · activated as NixOS generations
01 · Runtime paths
Install, update, or boot locally.
The controller prepares both delivery paths, but it is not a remote-desktop server for the room. Each installed workstation runs its own NixOS system and applications.
PXE or USB/SSH installation
PXE loads the deployment installer for many machines. USB/SSH verifies one official NixOS ISO when network boot is unavailable. Both converge on the signed closure and Disko review.
Trace both install paths ↓System deployment
Nixorium’s update engine copies the built system over SSH, clients take what they can from Harmonia, and a service on each client activates a new NixOS generation.
Trace the update path ↓Local boot and applications
The workstation boots from its own disk and runs the desktop locally. PXE, USB installation, the update engine and the classroom view are not part of ordinary application execution.
See the student desktop →02 · System model
Separate framework and lab configuration.
The bootstrap generates the lab configuration, a private repository that pins Nixorium. Lab settings and credentials have a different ownership boundary from the public framework.
- 01 · Live environment
Select the source and controller disk
The controller starts from the official NixOS ISO, Minimal or Graphical, in UEFI mode with Internet access. The bootstrap resolves the selected Nixorium source, applies the console keyboard, collects accounts and regional settings, and confirms the disk it will erase.
- 02 · Lab configuration
Create the lab’s private repository
The lab configuration is generated from the template and pins Nixorium as its upstream. The installed machine starts in controller-only mode with the real bootstrap account and regional settings, while laboratory networking remains inactive.
- 03 · Site ownership
Define the lab when its network is ready
After reboot, Installation → Network boot (PXE) collects the topology, creates missing controller keys, activates the controller, and prepares configured clients. Private keys remain on the controller.
Nixorium
Versioned modules, installers, defaults, and the function that generates the fleet.
Pinned by the lab configurationYour lab
Lab settings, host overrides, assets, password hashes, and public cache and SSH keys.
Private keys stay on the controllerNamed systems
The evaluated configurations and artifacts used by installation and deployment.
One source of desired stateThe lab configuration pins its Nixorium source and 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.
lab-settings.jsonManaged topology, local role names, password hashes, networking, locale, keyboard, homepage, and other typed site values.
lab-software.jsonManaged package declarations and their explicit shared, controller, client-group, or client scopes.
workspace-profile.jsonThe student workspace: dock, appearance and default browser, edited in the guided TUI editor, and VS Code extensions and settings, changed by Assistant; restored at every boot.
flake.lockThe exact Nixorium and NixOS package revisions. Update Nixorium and Update system and packages change it only after review.
modules/ + assets/Advanced workstation, development, home-profile, host, branding, editor, and desktop policy owned by the lab.
keys/ + controller secretsAuthorized public cache and SSH keys can be versioned. Matching private keys remain uncommitted on the controller and are installed through the managed workflow.
Controller bootstrap Deployment Flake Configuration schema Fleet generator
03 · Preparation
Evaluate, build, and publish.
- 01
Evaluate the lab
The lab configuration generates a NixOS configuration for every class of identical clients (one shared system, with each computer’s name and address coming from a small identity record), a separate controller configuration, a netboot environment, and a self-contained installer bundle.
- 02
Build on the controller
Pinned inputs and the shared configuration produce each client class system and its complete dependency set, plus PXE boot artifacts and the target-independent USB/SSH remote installer.
- 03
Publish inside the LAN
Harmonia exposes signed Nix store paths. PXE publishes its small boot chain; USB/SSH transfers a verified helper into the official NixOS ISO. Clients consume prepared outputs locally instead of resolving and building them from the Internet.
04 · Network install
Two paths to a local installation.
PXE is recommended for many machines. USB/SSH supports one physically identified machine without network boot. Neither is ordinary deployment, and both replace the explicitly reviewed target disk.
The laboratory network is wired: network boot, Switch on and each PC's laboratory address need an Ethernet cable. A USB/SSH installation can also start over Wi-Fi: the controller must reach the live client over SSH, the client must reach the signed cache, and the installed PC needs its cable before the restart.
Trace the PXE transport
- 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.
Trace the official NixOS ISO over SSH
- 01Official NixOS ISO
Boot locally and expose one live session
The operator boots NixOS 26.05 (Minimal or Graphical) in UEFI mode, connects it to the network (the laboratory cable, or Wi-Fi for the installation only), sets a temporary password, and reads the live IP and Ed25519 fingerprint from the physical console.
- 02Pinned SSH identity
Bind physical and logical identity
The controller checks that exact fingerprint before password authentication, installs an operation-specific key, and binds one configured client identity to the live boot.
- 03Signed Harmonia cache
Prepare one exact system
The controller builds the selected closure. The live client accepts only signed paths from that controller and does not use an Internet fallback.
- 04Disko + NixOS
Review and replace one disk
The boot medium is excluded. The operator explicitly selects an eligible disk and confirms a review bound to the physical session, logical host, revision, and disk.
- 05Separate reboot + verify
Boot the installed system
After installation completes, the operator separately authorizes the restart with the USB still in; the installer has made the next start use the new disk, and the operator removes the USB after that restart and verifies the installed host and exact system revision. Live Wi-Fi credentials are not copied: the installed PC takes its laboratory address on its wired card, so connect the cable before the restart.
The client does not contact the Internet during either path.
PXE artifacts or the remote helper and all signed Nix store paths come from the controller over permitted local traffic. The controller still needs Internet for initial setup and new inputs; Nixorium neither authenticates to captive portals nor bypasses network policy.
PXE service source Client installer source Disk layout source
05 · System updates
Deploy with Nixorium’s own engine.
Once a workstation is installed, normal system deployment follows its static lab address over SSH. It does not repeat either PXE or USB/SSH disk installation.
- 01ChangeEdit or update the lab configuration
- 02BuildProduce the selected systems on the controller
- 03ServeExpose signed store paths through Harmonia
- 04DeployCopy the system over SSH to one client or the lab group
- 05ActivateNixOS records the new system generation
The controller’s own configuration is applied separately. The operator then chooses one or more configured clients; testing a representative workstation first is recommended.
Computer and class definitions Client cache configuration NixOS generations and rollback
06 · Components
Components and responsibilities.
Nixorium installs and configures these components as part of the lab workflow.
On narrow screens, scroll sideways to read all columns. You can also focus the table and use the arrow keys.
| Component | Job in Nixorium | Phase |
|---|---|---|
| Nix + NixOS | Pin inputs, validate modules, build complete systems, and retain activated system generations. | Definition + build |
| NixOS module system + mkLab | Validate the lab configuration 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 |
| OpenSSH + remote installer | Verify one official NixOS ISO, bind its physical fingerprint to a configured client, and dispatch a reviewed installation with restart-safe receipts. | Install |
| Disko | Apply the declared partition and filesystem layout to the operator-confirmed installation disk. | Install |
| Update engine + OpenSSH | Build the selected systems once, copy them to 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. Free disk space keeps the newest ten on each computer, and the boot menu lists at most ten. | Activation |
| age | Encrypt the controller backup (configuration with its Git history, private keys, and trusted computer keys) with a passphrase. | Backup |
| Classroom view | Show student screens to the teacher and carry lock, screen sharing and file hand-out over the existing SSH access; it does not install or deploy NixOS systems. | Classroom operation |
07 · Boundaries
Network and trust boundaries.
- 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.
- USB/SSH identity
- The operator must be present to boot the official NixOS ISO, read its IP and Ed25519 fingerprint locally, choose the disk, and manage the installation medium.
- Routine deployment
- The update engine 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, physical fingerprint comparison, SSH keys, the lab configuration, target selection, disk review, and rollout remain operator responsibilities.
- Credential boundary
- Clients receive authorized public material. Private cache and SSH credentials stay on the controller and outside committed public source.
- Controller backup
- The encrypted backup holds everything needed to replace the controller without reinstalling clients. Keep it and its passphrase apart; anyone with both can manage the lab.
- Classroom monitoring
- The classroom view agent runs in the student’s session on a private socket and opens no network port. The controller reaches it only through its existing SSH access, and GNOME shows its sharing notice while the screen is captured.