Technician guide

1. How it works, in brief

A Nixorium lab has three parts.

• The controller. One PC in the room, a spare one or the teacher’s. It keeps the lab configuration, builds the system of every PC and serves it over the local network from a signed package cache. It runs network installation and the classroom view, and it is the only machine that needs Internet for installation and updates.
• The lab configuration. A private Git repository in the administrator’s home on the controller, ~/nixorium-deployment. It describes the whole lab: how many PCs, the network, the accounts, the software and the student desktop. The menu writes it for you, after a review.
• The student PCs. Each one is installed once from the controller, then starts from its own disk and runs its applications locally: if the controller is switched off, the lesson goes on, and only updates and the classroom view wait.

What lives where:

• On the controller: the lab configuration and its history, the private keys, the password hashes, the signed cache.
• On every PC, controller included: its installed system, the previous system versions listed in the boot menu, the student home and its five snapshots.
• Away from the controller, if you make one: the backup (an encrypted file on a USB drive, or a private Git repository) and the passphrase that opens it.

You manage everything from a text menu, Nixorium: sign in to the controller as admin and open it from the dock, or type nixorium in a terminal. Its areas are Computers, Installation, Software and Maintenance, plus the optional Assistant. Every action that changes something shows a review and waits for your confirmation.

Why Git? Every save in the menu becomes a commit, and every system the controller builds carries the revision it came from. A PC is current when it runs the latest saved revision, so the menu knows which PCs are up to date. Git also keeps the history of every change and can be backed up to a private repository.

Full technical boundary: Architecture → System model.

2. Before you start

You need:

• two 64-bit PCs with UEFI that you can erase: the controller and a first student PC;
• a USB stick with the official NixOS 26.05 ISO, Minimal (text console) or Graphical (GNOME);
• Internet on the controller, which must also be allowed to reach Internet time servers, and a network where the PCs reach each other;
• for network installation, UEFI network boot on the student PCs.

What gets erased. Installation erases the whole disk you confirm, on the controller and on every PC. It does not resize Windows or keep partitions on that disk. Windows on a second disk can stay: the boot menu finds it (see dual boot). Copy anything you need elsewhere first.

Who must be present. Someone who keeps the administrator password, and someone at each PC while it is installed: the installer asks, at the PC’s own screen, which computer it is and which disk to erase.

Settle three things with whoever runs the school network:

• A static lab subnet. Besides the address the school DHCP gives them, the controller and the PCs carry a fixed lab address in a private IPv4 subnet you choose, for example 10.0.0.0/24. It must not contain the address the school DHCP gives the controller: the settings refuse an overlap. A /24 has 254 usable addresses.
• The network interface. The setup proposes the controller’s card; the student PCs usually need no setting (see section 4).
• Permission for network boot. Network installation runs a ProxyDHCP service on the controller beside the school DHCP server. The school server keeps assigning every address; the controller only tells PCs that ask to boot from the network where the installer is. VLAN isolation, a DHCP policy or another service on UDP 67/69 or TCP 8080 can stop it. Wi-Fi may not support network boot; installation from USB works without it.

3. Install the controller

Start the controller from the NixOS ISO in UEFI mode, with Internet. The Graphical ISO helps when the school network needs a browser login: unlock it in Firefox, then open Terminal (ignore “Install NixOS”). Run:

curl -fsSL https://nixorium.org/install.sh | bash

The website counts daily downloads of this script, date and count only (privacy). The script lets you pick the Nixorium version, with a default, then asks:

1. the keyboard layout, from a short list and applied at once so you type the passwords with it, then the time zone;
2. the teacher and student account names (the administrator is always admin);
3. three passwords, administrator, teacher and student, each typed twice;
4. the initial software profile, such as Essential or Programming;
5. the disk.

Nothing changes until the disk review, where you type ERASE; a mistyped answer is asked again, an empty one cancels. The script installs the controller and saves the lab configuration in ~/nixorium-deployment, already committed. Remove the USB stick, type reboot, sign in as admin and open Nixorium. The first time, it shows the operational disclaimer and asks about optional adoption statistics, off unless you accept.

Controller-only mode. A new controller starts in controller-only mode: no student PCs are configured, so the lab network, the cache and the remote control services are off, and the controller uses only its school DHCP address. The lab starts the first time you open Installation.

4. The lab network

Two addresses on one card. Every machine keeps using the school DHCP for its address, default route and DNS, so students browse as usual. On the same card each machine also carries a fixed lab address: the subnet base plus its number. With 10.0.0.0/24, pc01 is 10.0.0.1, pc02 is 10.0.0.2, and the controller, pc99 by default, is 10.0.0.99. Management uses only these fixed addresses: the controller sends updates and opens the classroom view through them, and every student PC accepts SSH only from the controller’s lab address. On a student PC the lab address stays even when no DHCP server answers.

The lab settings. The first time you open Installation → Network boot (PXE) or Installation → USB over SSH, a form asks for the static lab network and its prefix length, the number of student PCs (numbered from pc01), the controller host number (above every PC number, 99 by default), the controller’s current DHCP address and the interfaces. The menu saves them, creates the keys and applies the configuration to the controller, which becomes a lab controller with its fixed address. Once student PCs are configured, Change settings no longer edits the subnet, the prefix or the controller number (code NETWORK-LOCKED): installed PCs would keep their old addresses and lose contact. The controller number stays fixed, so choose it once; the subnet and the prefix change only with the guided change below.

Network interface names. Three settings, under Maintenance → Change settings → Network:

• Controller network interface: the controller always uses this name. The setup proposes the card that carries its default route; change it only if the controller’s card changes.
• Client computers’ network interface: leave it empty, the default. Each student PC then puts the lab address on its wired Ethernet card whatever its name, so PCs of different models need nothing. Wireless cards, bridges and virtual devices are never chosen. Set a name only when every PC has the same card name.
• Shared fallback interface: used by the controller when its own name is empty. Student PCs ignore it unless a client name is set.

A PC with more than one wired card needs a per-computer override (hostIfaceNames in the lab configuration), otherwise the first card to come up gets the lab address, and that can change between boots. The same override names the card of a PC that must use Wi-Fi. Changing an interface can disconnect the PCs concerned when it is applied: the review warns, so check the cables and keep the local console within reach.

Wi-Fi. With a wireless card named, the lab address goes on that card, but the Wi-Fi network chosen in the USB session is not copied to the installed system: set up that connection separately. The student account cannot change connections, radios or DNS; the teacher and the administrator can.

Moving the lab to another network. Once PCs are configured, Maintenance → Change network addressing (or nixorium network migrate) moves the controller and every PC to a new subnet, for example from 10.0.0.0/24 to 10.1.0.0/24; each PC keeps its number. Switch the PCs on, save pending changes and stop network installation first. You type the new network as address and prefix, and the review lists the address of the controller and of every PC before and after and checks that every PC answers (a PC that is off holds it back until you switch it on or continue without it). Saving changes no PC. Then come the two usual steps, Apply to controller and Update computers: until you finish, the controller answers on both networks and each PC keeps its previous address beside the new one, so nothing loses contact. The Overview shows the change in progress (NETWORK-CHANGING) with its next step. Finish is offered once every PC runs the saved configuration and answers on its new address, and Undo works at any time before it. Prepare network installation again afterwards: the prepared files carry the controller’s address (details).

The time. The controller keeps the lab’s clock right from Internet time servers, so it must be allowed to reach them (outbound UDP 123), and gives the time to the lab network only, opening UDP 123 on the lab card and nowhere else. Each PC asks the controller and no Internet time server: a PC whose clock battery is drained starts with the right time although it has no Internet of its own, and certificates, file dates and logs stay correct. If the controller cannot reach the Internet, it keeps giving its own clock, starting five minutes after it boots. There is nothing to configure: the change reaches each PC at its next update and the controller when you apply it, and a controller-only installation keeps its previous time settings (details).

What network installation changes, and what it leaves. Preparing it builds the installer and the system of every PC and records the controller’s current DHCP address; the network does not change yet. When you start it (Enter on its review), the controller records the session, removes its fixed lab address from the card and serves the boot files and the signed cache on its DHCP address. A PC that boots from the network takes its address from the school DHCP, loads the installer from the controller and downloads its system from the cache, checked against the cache’s signing key. Stopping network installation puts the fixed address back; after a power cut the controller does the same at boot. While it is active, other operations such as updates and classroom controls are refused with the code PXE-ACTIVE, so stop it when the room is installed. If the school DHCP gives the controller a new address, just prepare again (details). Nothing temporary remains on the installed PC: it starts with its DHCP address plus its fixed lab address. Installation over USB never touches the controller’s address.

Full technical boundary: Architecture → Network install.

5. The first student PC

Install one PC and check it before the others.

Network boot. Installation → Network boot (PXE) shows one next step at a time: prepare the files, start, install, recover the network if needed. Start the PC from the network, with UEFI network boot ahead of the disk. The installer opens by itself on its screen, shows the hardware and disks and asks which configured computer this is. It refuses an identity whose lab address already answers, but silence is not a reservation: keep your own list of which PC is which. It offers only disks with room for the system plus 2 GiB. On the review of identity and disk, type ERASE. It installs from the controller’s cache, checks the result, then asks “Reboot now? [y/N]”: answer y, or press Enter to stay in the installer. Put network boot after the disk in the PC’s boot order, so it starts from its disk. If network installation was interrupted, that screen becomes Recover the controller network: it says in plain words what it found, and Enter puts the controller’s network back to normal without touching any student PC.

USB over SSH. Use it when the PC cannot boot from the network or has only Wi-Fi. Start the PC from the NixOS ISO (Minimal with 4 GB of RAM or less), connect Wi-Fi with nmtui if needed, and at its console run:

passwd
systemctl is-active sshd
ip -4 -br address
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

Keep that screen visible. On the controller choose Installation → USB over SSH, select the computer and enter only the live IPv4 address. The controller reads the PC’s SSH key without sending any password and shows its SHA256: fingerprint. Compare it with the one on the PC’s screen and type MATCH; only then does it ask for the temporary password, so the password goes only to the PC in front of you. Choose the disk and confirm its review. Remove the USB stick only when the screen says so, then confirm the restart; the controller then checks the installed PC at its lab address. If the installation stops halfway, the screen opens as Resume or close the USB installation: it says whether the PC still answers from the USB stick and whether its disk was touched, and offers only the safe ways out, such as Resume the installation or Cancel safely. Closing the record after the disk was written asks you to type CLOSE.

Check before going on:

• the PC starts from its disk into the student desktop, and the applications, keyboard, display and peripherals of your lessons work;
• signed in to the controller as the teacher, Classroom view shows the PC’s screen;
• Computers → Computer inventory shows the PC as current;
• a test file saved by the student is gone after a restart and can be found in the snapshots (see section 7);
• an update from Computers → Update computers completes.

6. The rest of the room, and the first backup

With network installation active, start the other PCs from the network one after another, choosing each identity and typing ERASE at each one. Then stop network installation, which gives the controller back its fixed address. To add PCs later, raise the number of computers in Maintenance → Change settings → Computers, apply it and prepare network installation again.

Then make a backup with Maintenance → Back up lab: it lets a new controller take over the room without reinstalling the PCs. Two kinds:

• Encrypted file: the whole lab configuration, its history, the private keys and the password hashes in one file encrypted with your passphrase. For a USB drive, mount it and enter its folder.
• Private Git repository: a private GitHub or GitLab repository reached over SSH. Keys and password hashes travel encrypted in one recovery file; the configuration stays readable to the repository’s members. After the first verified backup, every saved change is pushed while Nixorium is open.

Use a passphrase of at least 12 characters and keep it away from the controller: Nixorium never saves it. The Overview reminds you when a backup is due (code BACKUP-DUE): for a file, when the configuration, keys or passwords changed since the last one, or after 30 days; for Git, when keys, passwords or trusted computers changed, for example after you install a PC. A reminder never blocks anything.

Full technical boundary: Architecture → Network and trust boundaries.

7. Every day

The teacher signs in to the controller and opens Classroom view from the dock: every student screen at once, one screen in its own window with Take control, plus Lock (“Eyes on the teacher”), Share screen, Share files, Block/Allow Internet, Restart and Shut down. Internet comes back when a PC restarts; a PC that is off shows Off or not reachable. None of these controls changes the lab configuration. They keep working while the administrator updates the computers: only a PC that is being updated, or whose last update was interrupted, is left alone, and the review says so.

Save screenshot, Collect from students’ desktops and Switch on extend those controls. Save screenshot, in the window of one computer, keeps a picture of its screen in Nixorium/Screenshots, in the home of whoever uses the classroom view; it works only while the screen is live, so a computer that is off, behind its own lock screen or with nobody signed in has nothing to save. Collect from students’ desktops, in the Share files menu beside Send a folder… and Send a file…, copies the files on the desktops of the selected computers into Nixorium/Collected in that home, one folder per computer, after a review: hidden files and links are left out, nothing changes on the students’ computers, and a computer with more than 2000 items or 500 MB is reported and nothing of it is kept. Update the computers first: one that is not updated is listed as not able to collect yet. Switch on, under Power in the classroom view and in Computers → Power controls, sends a Wake-on-LAN packet to the selected computers that are off. A packet sent does not prove that a computer starts: its firmware (BIOS/UEFI) must allow waking from the network, it must have been restarted once after the client update that enables Wake-on-LAN, and it must stay plugged in. Nobody types an address: the controller learns each computer’s network card address by itself while the computer is on and the classroom view is open or Computer inventory runs, and a computer whose address it does not know yet is skipped (details).

Message → Send a message… shows a text of up to 300 characters over the screens of the selected computers, in front of everything, a lock or a shared screen included. It stays until the student closes it (Close appears after 10 seconds), for 30 seconds or 2 minutes, or until you unlock the computer; Remove message takes it off. The students keep their keyboard and mouse unless the computer is locked, and signing out removes the message. Update the computers first and have the students sign in again: one that is not updated is listed as unable to show messages yet (details).

To prepare a room for a test, use Internet → Block Internet, Lock and Message one by one, then Share files → Collect from students’ desktops.

Schedule switches the student computers on and off by themselves. Open Power → Schedule… in the classroom view (Save and Clear), or use nixorium schedule set --on 07:50 --off 18:00 in a terminal, as the teacher or the administrator. It has at most one switch-on time and one shut-down time, for the weekdays you choose (Monday to Friday unless --days says otherwise), in the controller’s time zone. The switch-on is the ordinary Switch on, so the conditions above apply and a computer without a known network address is skipped. The shut-down never interrupts a person: a computer that someone is using, or whose session cannot be read, stays on. When a network or USB installation keeps it from starting, it tries again every minute for ten minutes and then gives up for that day. An update of the computers does not hold it back: the shut-down only leaves on the PCs being updated, and says why. The schedule lives on the controller only, outside the configuration and the backup: set it again after replacing the controller (details).

At every boot of a PC, before the login screen, the home reset runs. The previous student home becomes one of five rotating snapshots, read-only and without runtime data such as global npm packages, Docker images and saved logins. A clean home is then restored from the prepared student workspace, and the student session starts automatically. The teacher finds the snapshots under Snapshots in the Files sidebar, signed in on that PC. Snapshots are on the same disk, so they are not backups: a broken disk loses them, and a session disappears after five more boots. Work that must last belongs on a USB stick or the school’s cloud storage. If a reset cannot finish, the PC blocks the login: do not retry it, have the administrator read the journal first (details).

Accounts.

• admin, the administrator: owns the lab configuration on the controller, with sudo and SSH.
• The teacher: a home that is kept, the classroom view and its controls, and read access to the snapshots.
• The student: one shared account on every PC, signed in automatically, with no administrator rights and a home reset at every boot. Its password is the same everywhere.

Accounts are part of the configuration, so passwd does not change them. Use Maintenance → Change settings → Accounts, with Change account names and Change account passwords. A new password takes effect on the controller when you apply the configuration, and on each PC when you update it. A renamed account starts with a new, empty home.

8. Change something

Every change takes the same path: edit in the menu, review, save (one commit in the lab configuration), then apply. Saving alone changes no running PC.

• Software. In Software, search the package set pinned by the lab, or pick a suggestion or a whole profile (p). Choose where it goes: shared (the controller and every PC, present and future), the controller only, every student PC, a group, or selected PCs. Enter on a configured package lets you change its destination (c) or remove it (x).
• The student desktop. In Maintenance → Change settings → Student workspace you edit the dock, favourites and desktop, the default browser, the VS Code settings and extensions, and the initial files of the student home. Managed extensions from the profile stay the recommended route. If the profile has the Java extension and the software includes a JDK, its settings point at that JDK. A program downloaded outside Nix, such as a Marketplace extension that brings its own binaries, also runs for staff, who keep their homes; student homes lose such installs at the reset.
• Settings. In Maintenance → Change settings you find the network, the computers, the accounts, the regional settings, the browser and Git.

Nothing is written until you confirm the review. Most reviews are confirmed with Enter (in a terminal, nixorium asks Continue? [y/N]); Esc cancels. A word is typed only before something that cannot be undone: erasing a disk, resetting the configuration template, discarding unsaved changes, trusting a new computer key, removing old versions and, in a terminal, shutting down or restarting PCs that someone is using. Then come two separate steps:

• Apply to controller. After a save the menu offers Apply to this controller; it is also under Maintenance → Advanced. The controller builds the saved configuration and switches to it, after a review that shows what changes. Every settings change needs it. Software saved as shared or controller-only does it by itself right after the save.
• Update computers. In Computers → Update computers, or with Update affected computers after a software save, select the PCs (n picks those that need it; PCs whose queued update is out of date are already selected) and press Enter on the review. The controller builds first, then each PC switches to its new system, received from the controller, and the menu checks which PCs now run the reviewed revision. The update log shows when each step started and how long it took, with the total time at the end.

Nothing reaches a student PC until you update it. A PC that is off goes into a queue (on by default in the review). A PC switched off while the update is being built is left unchanged and reported as not updated, or queued too if you chose that; it never holds back the other PCs. The controller tries every minute and updates the waiting PCs that answer, all together, as soon as they do; while another operation is running it waits for the next minute. Computers → Queued updates lists them. An entry is not applied if the configuration changed meanwhile: the next Update computers selects those PCs for you, so its review includes them. While you update computers, the classroom controls keep working for the other PCs. After an update the PC shows a notification: it asks for a restart when the kernel or systemd changed; otherwise it says the update is in place and suggests a restart only if something does not work as expected. A PC never restarts on its own. Student workspace changes appear at the next normal boot, when the home is reset.

Undo the last saved change. When the change you saved last (settings, software or the student workspace) causes trouble, go back to the configuration saved before it: in Maintenance → Review Git changes press u (Undo the last saved change), or run nixorium git undo plan as admin. The review shows the description, date and files of that change. Confirming it with Enter (y in a terminal) saves one new change, “Undo: …”, and puts the files back; the undone change stays in the history and nothing is pushed. No computer changes yet: run Apply to controller and then Update computers, as for any change. Save or discard other unsaved changes first. Only the last change can be undone, once, and only an ordinary saved change: it refuses, and names the next step, when that change is the first saved version, a merge or already an undo, when it updated Nixorium or the package base (see the update recovery), when it recorded keys, when it belongs to a change of the lab network, or when its files cannot go back safely (details).

Full technical boundary: Architecture → System updates.

9. Update

Two separate updates, both in Maintenance:

• Update Nixorium changes the framework: menus, modules and the management program. It lists the published releases, stable ones by default, and hides versions older than the one configured: the menu never offers a downgrade. It changes only flake.nix and flake.lock.
• Update system and packages moves NixOS and every package to a newer revision of the same channel. Moving to another NixOS release is a separate, explicit choice (m), with an acknowledgement that its compatibility is not verified.

Both build the candidate for real and show the change; Enter saves it, then rebuilds and verifies the controller. After Update Nixorium the interface reopens by itself on the new version after a few seconds (Enter at once, Esc to keep the running one). The PCs keep their system until you update them: update one PC, check it, then the others. Before installing more PCs, prepare network installation again. If Update computers then says PIN-OUTDATED, open Maintenance → Update Nixorium, select the configured version, marked “Current · select to repair”, and confirm.

System versions and the boot menu. Every apply to the controller and every PC update adds a new system version, a generation, on that machine; the old ones stay, and the boot menu (GRUB) lists up to ten. If a PC, or the controller, no longer boots or loses its network after an update, restart it and choose the previous version in the boot menu, PC by PC, then fix the configuration before applying again; a PC without network cannot be repaired from the controller. Going back changes the system, not data such as a migrated database. Old versions use disk space: the menu warns when the controller’s disk is low, and Maintenance → Advanced → Free disk space keeps the newest ten, the running one and the one the PC started with; you type CLEAN to confirm it.

10. When something goes wrong

When something blocks an operation, the menu says in one plain sentence what stopped, why and what to do next. Press Enter on that notice to open the screen that solves it; Esc closes it, and d shows the technical message. The Overview lists anything interrupted in the same words, and every refusal names a code. Do not delete files, keys or addresses as a first move.

Symptom	What to do
A PC does not boot from the network	Check that network installation is active, that network boot comes before the disk and that the PC is on the lab network. Guide
The installer loads but fails	Stop network installation, prepare it again, then start it. Guide
A PC is installed but not visible	Check power, cable and lab address; two wired cards need an interface override. Guide
A PC shows Off or not reachable	It is off, or the network does not reach it: Computer inventory tells which. Guide
An update was left pending (DEPLOY-PENDING)	Open Review the interrupted update (Enter on the notice, or from the Overview). It shows for each PC whether it finished, is still updating or does not answer: press c to continue without the PCs that do not answer, then Enter to mark the update as reviewed. Nothing changes on the PCs; then update again. Maintenance waits, and the classroom controls (Internet, shut down, restart, the schedule) still work: they leave alone only the PCs the update named. Update Nixorium and Apply to controller keep working, and if an older version still refuses to activate the controller, see the last resort. Guide
Apply to controller failed	Read the reported error, fix it, then make a new review. Guide
A PC no longer boots after an update	Choose the previous version in the boot menu, then fix the configuration. Guide
Backup older than 30 days (BACKUP-DUE)	Make a new one with Maintenance → Back up lab. Guide
A student lost a file	As the teacher on that PC, open Snapshots in Files. Guide
The controller is broken or replaced	Install a new one with the same number and network, then Maintenance → Restore lab; the PCs need no reinstall. Guide
A save or template reset was interrupted	Open the pending item in the Overview, Finish or undo the reset, and read what it found. If no file changes, Enter confirms; only for mixed old and new files do you type RESTORE. Delete nothing. Guide
A USB or network installation was interrupted	Open Resume or close the USB installation or Recover the controller network from the Overview or the Installation screens and follow what it offers. During an unfinished USB installation Update Nixorium and Apply to controller stay available, except while the PC’s disk is being written; an open network installation still stops them. Guide
The teacher sees a code such as OP-BUSY	Wait for the running operation, or follow that code’s row. Guide

11. Assistant

Assistant is an optional paid service in the administrator menu. Describe a change in your own words; you review its proposal before saving, then apply and update as usual. For a program distributed as a download (AppImage, deb or tarball), it fetches the file once on the controller and pins its hash itself, so you do no hash step. When nothing changed since Assistant’s own evaluation, the review reuses it and says how long ago it was verified instead of evaluating the lab again. If the service cuts an answer short, Assistant says so and asks you to send the message again. A resumed chat that is read-only scrolls with the arrow keys; Tab chooses between continuing in a new chat and going back. Nixorium works fully without it (plans and free trial).

12. Limits and cautions

• Installation erases the whole confirmed disk, Windows included if it is on that disk.
• Snapshots stay on the same disk and rotate after five boots: they are not backups.
• Accounts are local and fixed: one administrator, one teacher and one shared student account, with the same password on every PC. There are no per-student logins and no school directory.
• There is no unattended installation: someone confirms each PC at its screen, or its fingerprint over SSH.
• Network boot may not work over Wi-Fi, or on every firmware and school network; USB over SSH is the alternative.
• “Monitoring stopped on this PC” is a classroom aid, not a security boundary. A student cannot stop the classroom view from the terminal of the session: it restarts within seconds, and the card says so meanwhile. A student who masks its unit gets it back only at the next restart, when the home is reset.
• Releases are validated on virtual machines; start with one controller and one PC of your own.

Full guides

In English, at the Nixorium revision this page describes:

• Administrator guide
• System reference
• Troubleshooting and recovery