NixOS Configuration

Multi-host NixOS flake for Electra, Lena, Vega, Lyra, and Chaos. flake.nix and the imported modules are the executable source of truth. The repository wiki is the curated reference, operating manual, engineering handbook, ADR register, and small NixOS learning path. Active plans and acceptance evidence belong in Forgejo issues.

Licence

Copyright © 2026 Nimmo. Original material in this repository is licensed under the European Union Public Licence v. 1.2. Referenced, fetched, and built third-party software retains its own licences.

Quick start

Run just or just --list for the current recipe names and parameters. The most common commands are:

Task	Command
Validate Nix configuration and flake checks	just check
Build and compare the current host without activation	just build-diff
Test the current host without adding a boot generation	just test
Deploy the reviewed configuration on the current host	just deploy
Inspect evaluated host metadata	just fleet-status
Inspect recent system generations	just generations
Inspect the latest automatic update	just auto-update-last-run
Check backup service state and recent snapshots	just backup-status, just backup-snapshots

Stage new .nix and encrypted secret files before flake evaluation: a Git-backed flake does not see untracked files. Review every diagnostic warning. For configuration changes, read AGENTS.md and the wiki's Testing and CI Contracts.

Electra has one flake target with battery base, igpu, and dgpu boot variants. The latter two describe physical NVIDIA expansion-bay presence, not a workload preference. just test and just deploy preserve the current specialisation unless a deliberate mode change is requested. Use the wiki's Safe Testing and Deployment procedure, including an auto-update hold before remote testing.

Both commands use the host's declared build policy by default. Append local or remote to override build placement for one operation; the mode follows an optional Electra specialisation, such as just test dgpu remote.

For an explicitly selected remote target without giving that target the source tree, use just test-remote vega. It captures the controller's working tree, including untracked files. Add test, boot, or switch as a second argument to choose the activation action; test is the default.

Do not use just backup-restore as a general whole-root restore. Its current privilege/overwrite behaviour is unsafe for live recovery and is tracked by issue #226. Follow Full-Host Recovery or Backup Verification and Partial Restore instead. Disko/provisioning, boot-trust recovery, and secret rotation also have dedicated safety-gated runbooks; do not infer their commands from old Git history.

Repository entry points

Path	Role
flake.nix, flake.lock	Pinned inputs, shared makeNixosSystem builder, registered hosts, checks, and packages
hosts/<host>/	Selected host composition, hardware, storage layout, and local policy
modules/common/, modules/server/, modules/desktop/	Shared baseline and class-specific foundations
modules/profiles/, modules/services/, modules/containers/, modules/databases/	Opt-in capabilities and workload integration
users/	System account declarations
home/users/nimmo/, home/common/	Primary-user Home Manager entry point and shared user modules
potential/	Unregistered host drafts and legacy reference, excluded from normal host builds
justfiles/, scripts/, tests/, .forgejo/workflows/	Operator commands, implementation helpers, regressions, and Forgejo CI
secrets/, .sops.yaml	Encrypted scoped secret files and age recipient policy; never plaintext values
.agents/skills/update-wiki/	Agent checklist for per-page source verification and independent wiki publication

The complete import chain and ownership rules are in the wiki's Engineering Handbook. modules/common/default-config.nix defines portable nixosConfig defaults for the primary user, email, repository path, and SSH key path. Host entries override them only when the host actually differs. New root flake inputs must also be classified by real consumers in lib/auto-update-policy.nix.

Fleet at a glance

Host	Form	Main package set	Role
electra	Framework 16 laptop	Unstable	Mobile desktop, hardware-presence specialisations
lena	Lenovo 2-in-1 laptop	Unstable	Mobile desktop
vega	Physical Intel server	Unstable	Storage-backed services, cache, AI integrations
lyra	Physical Intel/NVIDIA server	Unstable	GPU compute and media workloads
chaos	Proxmox VM	Stable 26.05	Container-oriented workloads

Nova has an unregistered draft under potential/nova/. Do not treat it as a NixOS flake target or assume NixOS commands work on that machine until installation is confirmed. The Host Inventory and Service Catalogue separate declared placement from dated deployment evidence and live health.

Where to go next

• System Atlas: hosts, services, access, storage, and automation.
• Operations and Runbooks: routine work, incident response, and recovery.
• Engineering Handbook: how to place, validate, review, and publish changes.
• Architecture Decisions: rationale and accepted constraints.
• NixOS Learning Path: repository-oriented lessons.
• Documentation Map and Scope: ownership of repository, README, wiki, issues, BookStack, and KiwiFS.

Implementation-adjacent details of the automatic-update remediation controller remain in docs/auto-update-remediation.md. The live source and tests override any prose description if they diverge.