Administration modules

Note

A administration module deals with system-specific functionalities for administrators.

👑 darkone.admin.fleet-update

Fleet update tool (fleet-update) and its unattended daily run.

enable installs the tool on a deployment host; just fleet-update then runs it. timer.enable adds a daily fleet-update --no-ui run: flake update, build, test by waves, switch.

Service identity

The run belongs to user, owner of workDir: git identity, sops age key, AI and Matrix credentials. It needs passwordless sudo (just clean permissions, nix deploy identity whose key lives in ~nix/.ssh).

AI tools

--ai-model launches claude or opencode from PATH. Declare what the unattended run may reach in aiPackages; without it the run warns once and carries on without AI.

AI context

aiContext (language, style) is written to /etc/fleet-update/ai-context: every run on the host reads it, just fleet-update as well as the timer.

Exit codes

4 (a run already holds the lock) counts as success: no alert. Any other failure fails the unit and raises the existing SystemdUnitFailed alert, as does a run still going after timer.timeout.

Enable on the admin host

darkone.admin.fleet-update = {
  enable = true;
  user = "admin";
  timer.enable = true;
};

• enable bool fleet-update, the fleet update and deployment tool

• package package The fleet-update package. Its nix-eval-jobs is matched to the system Nix: the tool evaluates the consumer flake with it.

• aiPackages listOf package AI tools reachable from the unattended run (--ai-model). Optional: the tool warns and goes on without AI when none is found.

  Not a dependency of the package, because pkgs.claude-code is unfree and would force allowUnfree on every consumer. pkgs.opencode is MIT.

• aiContext nullOr str Operator guidance (language, style) included in every AI prompt of a run on this host, just fleet-update and the timer alike. Written to /etc/fleet-update/ai-context, even without enable: in co-development the recipe runs the sources. --ai-context, on the command line or in timer.extraArgs, overrides it.

• user nullOr str Account running the unattended update: owner of workDir, holding the git identity, the sops age key and the AI and Matrix credentials.

• workDir str Consumer workspace on disk. Not the workDir module argument, which is its copy in the nix store.

• timer.enable bool the daily unattended run (fleet-update --no-ui)

• timer.onCalendar str When the run starts (systemd OnCalendar).

• timer.extraArgs listOf str Options passed after --no-ui, which the module always sets.

• timer.timeout str Longest run before systemd stops it (TimeoutStartSec). A hung run would otherwise hold the lock, and every later run would exit 4 without any alert.

darkone.admin.fleet-update = {
  enable = false;
  package = pkgs.fleet-update.override { nix-eval-jobs = nixEvalJobs; };
  aiPackages = [ ];
  aiContext = "Answer in French and keep the response concise.";
  user = "admin";
  workDir = "/etc/nixos";
  timer.enable = false;
  timer.onCalendar = "*-*-* 04:00";
  timer.extraArgs = [ ];
  timer.timeout = "6h";
};

---

👑 darkone.admin.locate

Fleet host locator (dnf-locate): ssh finds a host wherever it is plugged.

A fleet name resolves to the host’s home address. Once the host roams (another zone, or outside on the tailnet), every ssh nix@<host> — colmena, fleet-update, just enter — would aim at that dead address. Enabled on an admin host, a ProxyCommand routes these connections through dnf-locate.

Paths tried, all derived from the topology:

• <host>: home address, alone first — the usual case costs one lookup;
• <host>.<zone domain>: reservation each zone holds for visiting hosts;
• <host>.tailnet.internal: tailnet address (zone gateways resolve it).

The first path to answer on the port wins.

Fleet ranges only

An alternate path counts only when its address lies in its own range (zone subnet, tailnet). A wildcard record of the public domain resolves any name, and the nix account pins no host key: the deploy would land on a stranger.

Where is my host?

dnf-locate --print <host> prints the path that answers, or fails.

• enable bool Route ssh to fleet hosts through dnf-locate (home, zone reservations, tailnet).

darkone.admin.locate.enable = config.darkone.admin.nix.enable;

---

👑 darkone.admin.nix

NixOS configuration for the local LAN administrator computer.

Build farm (remote builders)

An admin host builds every node closure locally and pushes it (buildOnTarget empty, see just/project.just), so it is the machine that actually compiles. Any fleet host flagged build-farm in config.yaml becomes one of its nix.buildMachines, reached over SSH as the nix deploy user.

Delegation is deliberately narrow. mandatoryFeatures (default big-parallel) means the farm is offered only the derivations that declare requiredSystemFeatures = [ "big-parallel" ] — kernel, chromium, firefox, llvm, rustc… ie. the long builds a beefy host is wanted for. Anything else stays local, which matters when the farm sits behind a slow uplink: only the requested output travels back.

Never drop big-parallel from this host’s own nix.settings.system-features to force delegation: keeping it means an unreachable farm makes the build hook decline and the derivation is simply built locally instead of failing.

Deploy key required

sshKey points at the shared deploy key just configure-admin-host generates under the nix user’s home. Admin hosts hold it by construction; a host that enables this module without the key logs SSH failures on every delegated build.

Why not a binary cache

A harmonia on the farm would share its build results, but harmonia serves the whole /nix/store and cannot express “only what I compiled”: it captures traffic the public cache should answer. Offloading is a build-scheduling concern, not a substitution one — hence buildMachines here and a last-resort substituter priority in service/nix-cache.nix.

• enable bool Enable NIX configuration builder tools
• enableNh bool Enable nix helper (nh) management tool
• remoteBuilders.enable bool Offload builds to the fleet hosts flagged build-farm in config.yaml. Inert while no host carries the flag.
• remoteBuilders.maxJobs int Parallel build slots to use on each farm.
• remoteBuilders.speedFactor int Relative speed rating of a farm, compared to this host.
• remoteBuilders.mandatoryFeatures listOf str Features a derivation MUST require for a farm to be offered it. This is what keeps small derivations off a remote (possibly slow) link. An empty list sends every eligible derivation to the farm.
• remoteBuilders.supportedFeatures listOf str System features a farm can provide.
• remoteBuilders.systems listOf str Platforms a farm builds for. Explicit rather than derived: hosts.nix only carries an architecture when it differs from the default.

darkone.admin.nix = {
  enable = false;
  enableNh = false;
  remoteBuilders.enable = true;
  remoteBuilders.maxJobs = 8;
  remoteBuilders.speedFactor = 2;
  remoteBuilders.mandatoryFeatures = [ ];
  remoteBuilders.supportedFeatures = [ ];
  remoteBuilders.systems = [ ];
};

---

👑 darkone.admin.welcome

First-boot welcome page of the admin host installed by darkone new.

At the first GNOME session of each wheel member, the browser opens a local page: step 1 of 4 done (the admin host), the gateway next, then services and the coordination server, with links to the documentation. Shown once per user (~/.local/state/dnf/welcome-shown). The “Onboarding” launcher of the nix-admin reopens it (darkone.admin.welcome.page).

Set by the installer

darkone new writes darkone.admin.welcome.enable = true; in the configuration.nix of the admin host. Remove the line to stop the page for the users who have not seen it yet.

• enable bool the first-boot welcome page of the admin host
• page path The welcome page, an HTML file of the store

darkone.admin.welcome = {
  enable = false;
  page = page;
};

---