Stop tracking deployment status in the Hosts table

Same problem as the deployedTargets removal, just in markdown instead of
Nix: which variant of a buildtype is actually deployed is live
infrastructure state, and a committed table can't stay accurate as that
changes -- it already required a manual edit on every migration and had
drifted before. Keep only what doesn't rot: what each target is for, and
stable naming history. Point at the live node / /etc/flake-target instead
for actual deployment status.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

.gitea/workflows/check-nixos.yml

@@ -17,13 +17,5 @@ jobs:
       - name: Install Nix
         uses: DeterminateSystems/nix-installer-action@v19
 
-      - name: Evaluate all NixOS hosts
+      - name: Run maintenance checks (secrets, fmt, lint, eval)
-        run: |
+        run: bash scripts/codex-maintenance.sh
-          set -euo pipefail
-          hosts="$(nix --extra-experimental-features 'nix-command flakes' eval --json \
-            .#nixosConfigurations --apply builtins.attrNames | jq -r '.[]')"
-          for host in $hosts; do
-            echo "Evaluating ${host}"
-            nix --extra-experimental-features 'nix-command flakes' eval \
-              ".#nixosConfigurations.${host}.config.system.build.toplevel.drvPath" --raw
-          done

.github/workflows/check-nixos.yml

@@ -17,13 +17,5 @@ jobs:
       - name: Install Nix
         uses: DeterminateSystems/nix-installer-action@v19
 
-      - name: Evaluate all NixOS hosts
+      - name: Run maintenance checks (secrets, fmt, lint, eval)
-        run: |
+        run: bash scripts/codex-maintenance.sh
-          set -euo pipefail
-          hosts="$(nix --extra-experimental-features 'nix-command flakes' eval --json \
-            .#nixosConfigurations --apply builtins.attrNames | jq -r '.[]')"
-          for host in $hosts; do
-            echo "Evaluating ${host}"
-            nix --extra-experimental-features 'nix-command flakes' eval \
-              ".#nixosConfigurations.${host}.config.system.build.toplevel.drvPath" --raw
-          done

.gitignore

@@ -3,12 +3,22 @@
 result
 result-*
 
+# Disko's proxmox-* image-builder writes the finished .raw disk image
+# directly into the current directory, not into a result-* symlink (see
+# docs/proxmox-images.md, scripts/create-proxmox-resource.sh) — several GB
+# each, never meant to be committed.
+*.raw
+
 # Ignore automatically generated direnv output
 .direnv
 
-auto-installer/flake.lock
+# Python bytecode cache (scripts/lib/*.py)
-auto-installer/result
+__pycache__/
-auto-installer/nixos-auto.iso
+*.pyc
+
+# Locally-generated SSH host keys staged for transfer to a new machine
+# during install (see scripts/prepare-host-key.sh) — never commit these.
+host-keys/
 
 # Temporary Milestone 1 audit checklist (remove-sensetive-info-refactor.md)
 # - working notes only, never committed, deleted once every row is rotated.

.sops.yaml

@@ -3,6 +3,10 @@ keys:
   - &docker age19gfn2yedg76dmztm4hncr7vf3r3c9j0qpt4rap7y7gersjk4m3ks2lhd0e
   - &server age1ll6hj5ggruetgjwjfnplpn5xtq35uhlcdflksx3xmnjm6s3uad9sz70jkf
   - &nix-cache age120le4a5l8dh3lyfgvmj3d9ksmej6ajs5mer5y7r0vfg3x9fn69dqf8xgzu
+  - &lxc-minimal age1qz9d4ka4xgexujyd247s7lp737sulp5fhxl5d65fj2ykvc4j4edqrsdks8
+  - &nix-minimal age120whqj96g26lsgy4udvgsn8dc9lumh8jeu3a564fx79rjr5lxffqmrljuu
+  - &lxc-nix-cache age164px2a8e48ptsf9ngtan38aa6jls4jdl26mzrgzf6sn3vcvt49hqjrgr8w
+  - &proxmox-minimal age10at8862478urh0eeuwh8hzln6ck78jgwtztgxatwqlzwagg77y5snm4xzg
 
 creation_rules:
   # Shared across every currently-deployed host: root/nixos password hash,
@@ -16,12 +20,17 @@ creation_rules:
           - *docker
           - *server
           - *nix-cache
+          - *lxc-minimal
+          - *nix-minimal
+          - *lxc-nix-cache
+          - *proxmox-minimal
 
   - path_regex: secrets/nix-cache\.yaml$
     key_groups:
       - age:
           - *admin
           - *nix-cache
+          - *lxc-nix-cache
 
   - path_regex: secrets/server\.yaml$
     key_groups:

CLAUDE.md

@@ -17,11 +17,19 @@ machines when deployed.
 - Validation is limited to evaluation, linting, formatting checks, and
   `nix build --dry-run --no-link`.
 - Do not add secrets, tokens, private keys, or new password hashes to the repo.
-- This repo currently contains **committed password hashes** (e.g.
+- This repo currently contains **committed password hashes** in
-  `prepare.sh`, `hosts/nixos/configuration.nix`) and SSH public keys (e.g.
+  `modules/installer/common.nix` (the auto-installer's own root/nixos login —
-  `modules/nix-cache/server.nix`). The hashes are known tech debt — do not use
+  a deliberate, documented choice, see `docs/auto-installer.md`, not
-  them as a template for new hosts, and flag any *new* secret-like string you
+  accidental tech debt) and **SSH public keys** in `variables.nix`
-  encounter instead of committing it.
+  (`vars.adminSshKey`, `vars.remoteBuilderAuthorizedKeys`) plus a couple of
+  per-host `KEY` values for beszel-agent auth (`hosts/server/host.nix`,
+  `hosts/nix-cache/host.nix`). Don't use the installer's hardcoded hash as a
+  template for a *real* host — every other host uses sops-nix
+  (`hashedPasswordFile`, see "Security Notes" in `README.md`). Flag any *new*
+  secret-like string you encounter instead of committing it.
+- `host-keys/` is gitignored — locally-generated *private* SSH host keys for
+  the auto-installer (see `docs/auto-installer.md`). Never commit its
+  contents; if `git status` ever shows it as trackable, something is wrong.
 
 ## Commands
 
@@ -50,58 +58,156 @@ maintenance script pulls them via `nix run github:NixOS/nixpkgs/nixos-25.11#<too
 There is no test suite — "correctness" here means the flake evaluates and
 `nixpkgs-fmt`/`statix` are clean.
 
+**In an interactive agent session**, prefer targeted checks over full-repo
+sweeps: after editing one or two hosts/modules, evaluate just the
+`nixosConfigurations.<host>` you touched (plus any `config.system.build.tarball`
+/`diskoImagesScript`/package output affected) rather than looping over every
+host — `codex-maintenance.sh` evaluates 18 hosts plus every package/tarball/
+image variant now and is slow to run after each small change. Reserve a full
+`codex-maintenance.sh` run for changes that plausibly affect every host
+(`modules/common/*`, `flake.nix`, `variables.nix`) or as a final check before
+committing. This is a session-workflow preference only — it does not apply to
+CI, which should keep running the full script on every push/PR regardless of
+diff size; that's the point of it.
+
+## Scripts
+
+Beyond `codex-setup.sh`/`codex-maintenance.sh` above, `scripts/` also has:
+
+- `scripts/sync-host-keys.sh` — generates/registers SSH host keys and their
+  `.sops.yaml`/`secrets/*.yaml` recipients for flake targets, idempotently
+  (`--all`, `<target>`, `--remove`, `--regenerate-all-keys`, all with
+  `--dry-run`). The primary tool for provisioning a new host's secrets
+  access — see "Creating a new machine" in `docs/auto-installer.md`.
+- `scripts/prepare-host-key.sh` — narrower predecessor: generates a key by
+  an arbitrary name without touching `.sops.yaml`. Still useful to
+  pre-generate a key before its flake target exists yet, since
+  `sync-host-keys.sh` can only act on targets `nixosConfigurations` already
+  has.
+- `scripts/create-proxmox-resource.sh` — builds a `lxc-*`/`proxmox-*`
+  target's tarball/disk image and creates it on a real Proxmox node
+  (`pct create` against the tarball as a CT template / `qm create`+
+  `importdisk`), or reconfigures an existing resource's cores/memory/disk
+  size (`--modify`, always requires typing the VMID back to confirm).
+  Checks for an already-uploaded image on the node before building
+  (`--force-rebuild` to skip that and always rebuild), and probes
+  nix-cache's substituter/remote-builder reachability once up front rather
+  than letting every `nix build` call retry against it individually.
+  Refuses to create a target whose host identity already exists live on
+  the node (checked directly via `qm`/`pct`, not any file in this repo)
+  unless `--allow-duplicate-host` is passed. `--dry-run` throughout both
+  modes.
+- `scripts/env.sh` — shared config (`PROXMOX_HOST`, storage pool, bridge,
+  default cores/memory) sourced by `create-proxmox-resource.sh`. Add new
+  cross-script config here instead of duplicating it per-script.
+- `scripts/bump-nixpkgs-release.sh` — bumps `flake.nix`'s `nixpkgs.url`/
+  `home-manager.url` in place. Exists because flake input URLs can't
+  reference `variables.nix` (confirmed empirically — `nix flake metadata`
+  errors on it), so this is the closest equivalent to a single source of
+  truth for the tracked release.
+
+`sync-host-keys.sh` and `create-proxmox-resource.sh` genuinely mutate real
+state when run for real (not `--dry-run`): real `secrets/*.yaml`
+recipients, real Proxmox VMs/containers. They require the operator's own
+SSH/sops access, which an agent session doesn't have — but don't suggest
+running either non-dry-run without the operator's explicit go-ahead even
+if it becomes technically reachable.
+
 ## Architecture
 
-`flake.nix` is the single entry point. It defines one `nixosConfigurations.<host>`
+`flake.nix` is the single entry point. It generates one
-attribute per machine, each built the same way:
+`nixosConfigurations.<platform>-<buildtype>` attribute per target via the
+`mkTarget` function, composed from:
 
 ```
 nixosSystem {
   modules = [
     disko.nixosModules.disko
-    ./hosts/<host>/configuration.nix        # host-specific config
+    sops-nix.nixosModules.sops
-    ./modules/hardware-configuration/vm/<proxmox|linode>.nix
+    ./modules/common/configuration.nix
+    ./modules/platforms/${platform}.nix        # what it runs on
+    ./modules/build-types/${buildType}.nix     # what it's for
+    hostPath                                   # hosts/<name>/host.nix — per-machine identity
     home-manager.nixosModules.home-manager { ... }
-  ];
+  ] ++ (client-only modules, for every buildType except "nix-cache" itself)
 }
 ```
 
-Hosts currently defined in `flake.nix`: `nixos`, `docker`, `server`,
+Platforms: `linode`, `proxmox`, `lxc`. Build types: `minimal`, `nix-cache`,
-`nix-cache`, `nix-minimal`, `pxe-boot`, `linode-minimal`. Treat `flake.nix` as
+`server`, `docker`, `gui`, `pxe-boot`, `tailscale-exit-node`. Not every
-the source of truth for which hosts exist — `README.md`, `AGENTS.md`,
+combination is built — e.g. `pxe-boot` has no `linode` variant (PXE/DHCP/TFTP
+need LAN L2 adjacency a Linode VPS doesn't have). Treat `flake.nix`'s
+`generatedTargets` as the source
+of truth for which hosts exist — `README.md`, `AGENTS.md`,
 `docs/flake-lock-automation.md`, and the CI eval workflows
 (`.github/workflows/check-nixos.yml`, `.gitea/workflows/check-nixos.yml`) list
-hosts by hand and can drift from it, so re-check them against `flake.nix` when
+hosts by hand (or, for the CI workflows, evaluate the flake dynamically) and
-adding or removing a host.
+can drift from it, so re-check them against `flake.nix` when adding or
+removing a host.
 
 ### Composition pattern
 
-Every host's real configuration lives in `hosts/<host>/configuration.nix`,
+- `hosts/<name>/host.nix` — per-machine identity **only**: hostname, hostId,
-which is a thin list of `imports` pulling in reusable pieces from `modules/`:
+  per-machine secrets, `system.stateVersion`. These files carry no `imports`
-
+  of their own beyond narrow parameterized helpers (see
-- `modules/common/configuration.nix` — base NixOS config imported by (almost)
+  `modules/beszel/host-token.nix` below) — all shared behavior comes from the
-  every host: locale, users, nix settings, git. Nearly always the first import.
+  platform/build-type modules composed in `flake.nix`, not from the host file.
-- `modules/common/home.nix` / `hosts/<host>/home.nix` — Home Manager config for
+- `modules/platforms/{linode,proxmox,lxc}.nix` — platform-specific config:
-  the `nixos` user; the `nixos` workstation has its own, other hosts share
+  boot method, guest tooling, and (for linode/proxmox) the hypervisor-specific
-  `modules/common/home.nix`.
+  hardware config, imported directly by the platform module itself
+  (`../hardware-configuration/vm/{proxmox,linode}.nix`) — **not** wired in
+  from `flake.nix`. `lxc.nix` has no hardware-configuration counterpart since
+  containers share the host kernel; instead it imports nixpkgs' own
+  `virtualisation/proxmox-lxc.nix`, which gives every `lxc-*` host a
+  `config.system.build.tarball` output — a plain rootfs tarball, used as a
+  `pct create ... vztmpl` CT template (**not** `pct restore`, which expects
+  `vzdump` backup-archive metadata this doesn't have), no install step —
+  see `docs/auto-installer.md`.
+- `modules/build-types/*.nix` — what a system is for:
+  minimal/server/docker/gui/pxe-boot/nix-cache.
+- `modules/common/configuration.nix` — base NixOS config imported by every
+  host: locale, users, nix settings, git.
+- `modules/common/home.nix` / `hosts/nixos/home.nix` — Home Manager config for
+  the `nixos` user; the `nixos` workstation (`gui` build type) has its own,
+  other hosts share `modules/common/home.nix`.
 - `modules/disko/proxmox.nix` — declarative disk layout (GPT: ESP + swap +
-  ext4 root) via disko, used by all Proxmox-VM hosts.
+  ext4 root) via disko, used by all Proxmox-VM hosts (`proxmox-*`, not
+  `lxc-*`). Also carries `imageSize`/`imageName`, letting every `proxmox-*`
+  host be built as a standalone, `qm importdisk`-ready `.raw` image with no
+  install step — see `docs/proxmox-images.md`.
+- `modules/disko/linode.nix` — `linode-*`'s disko config, deliberately
+  different in kind from the Proxmox one: Linode provisions and sizes
+  `/dev/sda`/`/dev/sdb` itself as whole, unpartitioned devices before the OS
+  boots, so this declares them with `destroy = false` (disko never wipes
+  them) and a bare `filesystem`/`swap` content type instead of a partition
+  table — idempotent against an already-provisioned disk, never destructive.
 - `modules/boot/efi.nix` — systemd-boot + EFI vars, paired with the disko module.
-- `modules/hardware-configuration/vm/{proxmox,linode}.nix` — hypervisor-specific
+- `modules/installer/` — the auto-installer environment (ISO, also served as
-  hardware config, wired in from `flake.nix` (not from the host file).
+  PXE netboot): `common.nix` (shared config + the generated
-- `modules/nix-cache/{client,server}.nix` + `modules/remote-builder-client.nix` —
+  `auto-install.sh`), `iso.nix`, `host-keys.nix` (optionally bakes
-  binary cache substituter + SSH remote-builder wiring; see `docs/nix-cache.md`
+  `host-keys/` into the image under `--impure`). See
-  for the full design (per-host local stores, no shared `/nix/store`, and how
+  `docs/auto-installer.md`.
-  the `nixremote` signing/SSH keys fit together).
+- `modules/pxe-boot/stage-installer-artifacts.nix` — builds the installer's
-- `modules/tailscale/`, `modules/docker/`, `modules/beszel/`,
+  netboot image and stages it on the `pxe-boot` host so its iPXE menu can
-  `modules/services/*` — single-purpose, single-host feature modules (e.g.
+  chain straight to it. See `docs/pxe-boot.md`.
-  `docker/enable-service.nix`, `services/zfs/enable-service.nix`,
+- `modules/nix-cache/{client,server,remote-builder-client}.nix` — binary cache
-  `beszel/enable-agent.nix` for monitoring). Grep `hosts/*/configuration.nix`
+  substituter + SSH remote-builder wiring; see `docs/nix-cache.md` for the
-  for the `imports` list to see which modules apply to a given host.
+  full design (per-host local stores, no shared `/nix/store`, and how the
+  `nixremote` signing/SSH keys fit together).
+- `modules/beszel/host-token.nix` — parameterized helper module
+  (`{ name, sopsFile }`) that wires a host's beszel-agent sops secret/template
+  and `environmentFile`; used by `hosts/server/host.nix` and
+  `hosts/nix-cache/host.nix` to avoid duplicating that boilerplate.
+- `modules/tailscale/`, `modules/docker/`, `modules/networking/`,
+  `modules/traefik/`, `modules/services/*` — single-purpose, single-host
+  feature modules (e.g. `docker/enable-service.nix`,
+  `services/zfs/enable-service.nix`). Grep `modules/build-types/*.nix` for
+  each build type's `imports` list to see which modules apply where.
 
-New host = new `hosts/<name>/configuration.nix` + a matching block added to
+New host = new `hosts/<name>/host.nix` + a matching
-`flake.nix`'s `nixosConfigurations`, composed from existing `modules/*` pieces
+`mkTarget { platform; buildType; hostPath; }` entry added to `flake.nix`'s
-rather than duplicating config.
+`generatedTargets`, composed from existing `modules/*` pieces rather than
+duplicating config.
 
 ### Other docs worth reading before touching these areas
 
@@ -109,6 +215,12 @@ rather than duplicating config.
   handling.
 - `docs/pxe-boot.md` — the `pxe-boot` host's iPXE/TFTP/HTTP boot chain and
   directory layout under `/srv/pxe`.
+- `docs/auto-installer.md` — the installer environment (ISO/netboot/Proxmox
+  LXC), `host-keys/` and the sops-nix pre-seeding problem it solves, and why
+  `lxc-*` hosts are deliberately excluded from its menu.
+- `docs/proxmox-images.md` — building `proxmox-*` hosts as standalone `.raw`
+  disk images (disko's image builder) instead of installing, and deploying
+  the result to Proxmox.
 - `docs/flake-lock-automation.md` — how `flake.lock` updates flow through CI
   (scheduled `nix flake update` PR + host-eval-on-PR workflow) and why hosts
   should track the committed lock file rather than `nixos-rebuild --upgrade-all`.

README.md

@@ -10,7 +10,7 @@ pieces composed in `flake.nix`:
 
 - **Platforms** (what it runs on): `linode`, `proxmox`, `lxc`
 - **Build types** (what it's for): `minimal`, `nix-cache`, `server`, `docker`,
-  `gui`, `pxe-boot`
+  `gui`, `pxe-boot`, `tailscale-exit-node`
 
 Not every combination exists — `pxe-boot` has no `linode` variant, since
 PXE/DHCP/TFTP need LAN L2 adjacency that a Linode VPS doesn't have. The full
@@ -18,14 +18,23 @@ list:
 
 | Target | Purpose |
 | --- | --- |
-| `linode-minimal` | Minimal NixOS host profile on a Linode VPS (real, deployed) |
+| `linode-minimal` | Minimal NixOS host profile on a Linode VPS |
-| `proxmox-minimal` | Minimal NixOS host profile on Proxmox (real, deployed — previously the flat `nix-minimal` target) |
+| `proxmox-minimal` | Minimal NixOS host profile on Proxmox — previously the flat `nix-minimal` target |
 | `lxc-minimal` | Minimal NixOS host profile in a Proxmox LXC container |
-| `linode-nix-cache` / `proxmox-nix-cache` / `lxc-nix-cache` | Local Nix binary cache and remote builder (`proxmox-nix-cache` is the real, deployed one — previously the flat `nix-cache` target) |
+| `linode-nix-cache` / `proxmox-nix-cache` / `lxc-nix-cache` | Local Nix binary cache and remote builder — previously the flat `nix-cache` target |
-| `linode-server` / `proxmox-server` / `lxc-server` | Storage, NFS, backup, and monitoring exporter host (`proxmox-server` is the real, deployed one — previously the flat `server` target) |
+| `linode-server` / `proxmox-server` / `lxc-server` | Storage, NFS, backup, and monitoring exporter host — previously the flat `server` target |
-| `linode-docker` / `proxmox-docker` / `lxc-docker` | Docker host for the main container stack (`proxmox-docker` is the real, deployed one — previously the flat `docker` target) |
+| `linode-docker` / `proxmox-docker` / `lxc-docker` | Docker host for the main container stack — previously the flat `docker` target |
-| `linode-gui` / `proxmox-gui` / `lxc-gui` | Cinnamon desktop workstation (`proxmox-gui` is the real, deployed one — previously the flat `nixos` target) |
+| `linode-gui` / `proxmox-gui` / `lxc-gui` | Cinnamon desktop workstation — previously the flat `nixos` target |
-| `proxmox-pxe-boot` / `lxc-pxe-boot` | HTTP/iPXE boot asset host (`proxmox-pxe-boot` is the real, deployed one — previously the flat `pxe-boot` target) |
+| `proxmox-pxe-boot` / `lxc-pxe-boot` | HTTP/iPXE boot asset host — previously the flat `pxe-boot` target |
+| `linode-tailscale-exit-node` / `proxmox-tailscale-exit-node` / `lxc-tailscale-exit-node` | Tailscale exit node |
+
+Which variant of a given buildtype is actually deployed isn't tracked
+anywhere in this repo — that's live infrastructure state, not something a
+committed file can keep accurate, and it changes independently of the code.
+Check the Proxmox node itself, or `/etc/flake-target` on a running host (see
+below), if you need to know what's really out there right now.
+`scripts/create-proxmox-resource.sh`'s duplicate-host guard works the same
+way: it checks the Proxmox node directly rather than any file here.
 
 Each buildtype's `hosts/<name>/host.nix` carries the per-machine identity
 (hostname, hostId, per-machine secrets, `system.stateVersion`) that must stay
@@ -46,14 +55,17 @@ nix eval --json .#nixosConfigurations --apply builtins.attrNames | jq -r '.[]'
 | Path | Purpose |
 | --- | --- |
 | `flake.nix` | Flake inputs, the `mkTarget` platform × build-type generator, and `nixosConfigurations` outputs |
+| `variables.nix` | Single source of truth for shared values (LAN domain/CIDR, hostnames, timezone, primary username, storage root, NFS share subpaths/mountpoints, service ports, ...) — passed to every module and Home Manager config as the `vars` argument via `specialArgs`/`extraSpecialArgs` |
 | `hosts/<name>/host.nix` | Per-machine identity: hostname, hostId, per-machine secrets, `system.stateVersion` |
 | `hosts/nixos/home.nix` | Workstation-specific Home Manager config (used by the `gui` build type) |
 | `modules/platforms/` | Platform-specific config: virtualisation guest tools, boot method, hardware config (`linode.nix`, `proxmox.nix`, `lxc.nix`) |
 | `modules/build-types/` | Build-type-specific config: what makes a system minimal/server/docker/gui/pxe-boot/nix-cache |
 | `modules/common/` | Shared NixOS config, Home Manager, aliases imported by every host |
 | `modules/nix-cache/` | Binary cache and remote builder client/server modules |
-| `docs/` | Operational notes for cache, builders, lock updates, and boot services |
+| `modules/installer/` | Auto-installer environment (ISO, also served as PXE netboot) — see `docs/auto-installer.md` |
-| `scripts/` | Codex setup and validation helpers |
+| `host-keys/` | Gitignored, locally-generated SSH host keys for the auto-installer — see `docs/auto-installer.md` |
+| `docs/` | Operational notes for cache, builders, lock updates, boot services, the auto-installer, and Proxmox image builds |
+| `scripts/` | Codex setup, validation, host-key, release-bump, and Proxmox resource helpers |
 
 ## Validation
 
@@ -84,6 +96,28 @@ review sessions.
   client hosts.
 - `pxe-boot` serves iPXE boot files over HTTP from `/srv/pxe`.
 
+### Deploying a new host
+
+Three different paths depending on target, none of them involving a manual
+`nixos-rebuild switch` from this repo:
+
+- Most hosts: boot the auto-installer, pick the target from its menu — see
+  `docs/auto-installer.md`. Every menu target has a Disko config the
+  installer formats unconditionally (`docs/auto-installer.md`'s "Storage"
+  section covers how this stays non-destructive for `linode-*`, whose disks
+  Linode itself provisions ahead of time).
+- `lxc-*` targets: not installed at all — build a ready-to-run container
+  tarball and `pct create` it as a CT template directly. `docs/auto-installer.md`
+  covers why (and the installer's menu excludes them for the same reason).
+- `proxmox-*` targets: can alternatively be built as a standalone `.raw`
+  disk image and attached to a new VM with no install step — see
+  `docs/proxmox-images.md`.
+
+`scripts/create-proxmox-resource.sh --type lxc|vm --host <name>` automates
+either of the last two end to end (build, host-key registration, upload,
+`pct create`/`qm create`), with `--dry-run` and a guard against duplicating
+an already-deployed host's identity. See its `--help`.
+
 ## Security Notes
 
 Do not commit tokens, private keys, live credentials, or new password hashes
@@ -104,6 +138,13 @@ enabled via `git config core.hooksPath .githooks`, done automatically by
 `scripts/codex-setup.sh`) runs `gitleaks protect --staged` to catch mistakes
 before they're committed.
 
+The auto-installer environment is the one deliberate exception to
+sops-nix-everywhere: it has a hardcoded login password instead (no stable
+per-boot host key for sops-nix to derive from on ephemeral media) — see
+"Host keys" in `docs/auto-installer.md` for why, and how the private keys it
+*does* pre-seed for target hosts stay out of git via the gitignored
+`host-keys/` directory.
+
 This repository's git *history* still contains secrets committed before this
 migration (see `remove-sensetive-info-refactor.md`) — those are being
 scrubbed and rotated separately; don't treat the repo as safe to make public

docs/auto-installer.md

@@ -0,0 +1,286 @@
+# Auto-installer
+
+This flake builds a self-contained NixOS installer environment that can
+install any host exposed by its own `nixosConfigurations`. It was migrated
+from a formerly-separate `nix-auto-installer` repo — everything it did now
+lives here.
+
+The installer provides a small NixOS install environment (ISO, or the same
+image netbooted via PXE) with SSH access, Git support, and an interactive
+installation script.
+Logging in as any user (root or `nixos`) runs `/etc/auto-install.sh`,
+discovers available hosts from this same flake, lets the operator choose a
+target, applies that host's Disko storage configuration, installs NixOS, and
+reboots.
+
+**This applies to every `nixosConfigurations` target except `lxc-*` hosts —
+see "LXC hosts" immediately below for why those are different.**
+
+## LXC hosts
+
+`lxc-*` targets (`lxc-minimal`, `lxc-nix-cache`, `lxc-server`, `lxc-docker`,
+`lxc-gui`, `lxc-pxe-boot`) are **not** installed via `auto-install.sh` — the
+interactive menu deliberately excludes them. Don't try to select one there;
+`nixos-install` would bind-mount `/` onto `/mnt` (LXC containers have no raw
+disk to partition) and then refuse to touch the filesystem it's currently
+running on — it's designed to protect exactly this case, so it just fails.
+
+`modules/platforms/lxc.nix` imports nixpkgs' own
+`virtualisation/proxmox-lxc.nix` module, which gives every `lxc-*` host a
+`config.system.build.tarball` output — a complete, directly Proxmox-importable
+container image, no install step at all:
+
+```sh
+nix build .#nixosConfigurations.lxc-minimal.config.system.build.tarball
+```
+
+This is a plain rootfs tarball, not a `vzdump` backup archive — restoring it
+with `pct restore` fails ("archive contains no configuration file"), since
+that command expects backup-archive metadata this tarball doesn't have. Use
+it as a CT *template* instead: drop it under Proxmox's template storage
+(conventionally `/var/lib/vz/template/cache/` for the `local` storage, or
+the GUI's "Create CT" → upload-as-template flow) and create a container
+from it, supplying all config on the command line since a template has none
+of its own:
+
+```sh
+pct create <vmid> local:vztmpl/<file>.tar.xz \
+  --unprivileged 1 --features nesting=1,keyctl=1 \
+  --rootfs local-lvm:8 --hostname <name> --cores 2 --memory 2048 --swap 2048 \
+  --net0 name=eth0,bridge=vmbr0,ip=dhcp
+pct start <vmid>
+```
+
+Every one of those extra flags is load-bearing, confirmed by actually
+booting one:
+
+- `--unprivileged 1` — `modules/platforms/lxc.nix` sets
+  `proxmoxLXC.privileged = false`, so the image assumes it's running
+  unprivileged. `pct create`'s own CLI default for this flag is
+  privileged (unlike the web UI, whose checkbox defaults the other way)
+  — omit it and you get a privileged container running a NixOS config
+  that assumes unprivileged, a real mismatch.
+- `--features nesting=1,keyctl=1` — required for a modern (v247+)
+  systemd guest to boot unprivileged at all. Without it, AppArmor denies
+  the nested user namespaces and credential mounts systemd routinely
+  uses (even plain getty units) — every getty crash-loops on a denied
+  `/run/credentials/*` mount every ~3s (this is what garbage on the
+  console turns out to be) while core services like `nsncd` fail the
+  same way, and the system never finishes activating.
+- `--swap 2048` — `--memory` doesn't touch swap; it silently stays at
+  Proxmox's own 512M default otherwise. Match it to `--memory` unless
+  you deliberately want otherwise.
+
+First boot runs `boot.postBootCommands` (registers the Nix store DB and
+system profile) — there's no separate activation step to run yourself.
+`scripts/create-proxmox-resource.sh --type lxc --host <name>` automates all
+of this (build, host-key handling, upload, `pct create` with the flags
+above) — see its `--help`.
+
+Host keys still need pre-seeding the same way as any other host — the
+sops-nix activation-vs-first-boot race is identical regardless of how the
+image reaches the machine. Unlike the ISO/PXE installer (where
+`modules/installer/host-keys.nix` bakes *every* `host-keys/` entry into
+`/etc/host-keys/` for `auto-install.sh` to pick from and copy at install
+time — see "Host keys" below), an `lxc-*` tarball has no install step to
+copy anything during, so `modules/platforms/lxc.nix` bakes this *one*
+target's key straight into `/etc/ssh/ssh_host_ed25519_key(.pub)` directly,
+keyed by its own exact flake target name (`config.environment.etc` can't
+be read back from within a module still contributing to it, so this comes
+in via `specialArgs.flakeTarget`, set by `flake.nix`'s `mkTarget`):
+
+```sh
+NIXOS_HOST_KEYS_DIR="$(pwd)/host-keys" \
+  nix build .#nixosConfigurations.lxc-nix-cache.config.system.build.tarball --impure
+```
+
+Confirmed the hard way: without this, the tarball's own built-in system
+just generates a fresh host key at first boot like any host would, which
+can never match whatever `.sops.yaml` actually trusts for that target —
+`sops-install-secrets` fails with `Error getting data key: 0 successful
+groups required, got 0`, and *every* secret (including this host's own
+login) permanently fails to decrypt, silently — no error in the boot log
+at all, since the activation step that would install secrets only runs on
+a from-scratch first activation and skips silently once `/run/current-system`
+already exists. `scripts/create-proxmox-resource.sh` always builds with
+`NIXOS_HOST_KEYS_DIR` set for this reason.
+
+## Layout
+
+- `modules/installer/common.nix` — shared by every installer target: SSH
+  access, users, the generated `/etc/auto-install.sh` script, and the
+  `programs.bash.loginShellInit` hook that runs it on login.
+- `modules/installer/iso.nix` — ISO/netboot-specific: imports the stock
+  `installation-cd-minimal.nix` module plus `common.nix`. Also used, paired
+  with `netboot-minimal.nix`, to build the PXE netboot variant (see
+  `docs/pxe-boot.md`).
+- `modules/installer/host-keys.nix` — optionally bakes pre-generated SSH
+  host keys into the image; see "Host keys" below.
+- `scripts/sync-host-keys.sh` — admin-workstation tool that generates,
+  registers, and (via `--remove`/`--regenerate-all-keys`) retires host
+  keys; see "Creating a New Machine" below.
+- `scripts/prepare-host-key.sh` — narrower predecessor: generates a single
+  key by an arbitrary name without touching `.sops.yaml`. Still useful for
+  pre-generating a key *before* its flake target exists (`sync-host-keys.sh`
+  can only act on targets `nixosConfigurations` already has); otherwise
+  `sync-host-keys.sh` does the same thing and more.
+
+Flake outputs:
+
+```nix
+nixosConfigurations.installer   # ISO/netboot installer image
+
+packages.x86_64-linux.iso   # installer ISO/netboot image
+packages.x86_64-linux.pxe   # netboot-ipxe + netboot-initrd + netboot-kernel, bundled
+```
+
+```sh
+nix build .#iso
+nix build .#pxe
+```
+
+There's no `nixosConfigurations.proxmox-lxc` (installer-boots-as-an-LXC-
+container) or `packages.x86_64-linux.lxc`/`.all` anymore. Both existed only
+to let the installer itself run as an LXC container so you could
+`nixos-install` some *other* host from within it — but LXC targets are
+excluded from the install menu (same bind-mount problem as any LXC
+`nixos-install`), and now have their own direct tarball path anyway (see
+"LXC hosts" above), which left the installer's own LXC form with no real
+use case.
+
+The `pxe` variant is also built automatically as part of the `pxe-boot` host
+itself (`modules/pxe-boot/stage-installer-artifacts.nix`) and served over
+iPXE — see `docs/pxe-boot.md`.
+
+## Host keys
+
+`sops-nix` derives each host's decryption key from its own
+`/etc/ssh/ssh_host_ed25519_key`, generated at **activation** time — before
+systemd would otherwise generate one on first boot. Without pre-seeding this
+key, secrets (including the root/nixos login password) fail to decrypt on a
+genuinely fresh install.
+
+Generated host keys live in `host-keys/` at the repo root (`ssh_host_ed25519_key`
++ `.pub` pairs per hostname). This directory is **gitignored on purpose** —
+private key material must never be committed — which also means flakes can't
+see it through a normal relative path. `modules/installer/host-keys.nix`
+reads it through `builtins.getEnv`, which Nix silently returns as an empty
+string under normal (non-`--impure`) evaluation, so the module is a no-op —
+safe by default, including in CI — unless explicitly opted into:
+
+```sh
+NIXOS_HOST_KEYS_DIR="$(pwd)/host-keys" nix build .#iso --impure
+```
+
+When built this way, every key currently in `host-keys/` is baked into the
+image at `/etc/host-keys/<hostname>_ssh_host_ed25519_key(.pub)`, and
+`auto-install.sh` automatically installs whichever one matches the flake
+target selected at install time — no manual per-host scp step needed.
+
+**Trade-off, accepted deliberately for this LAN-only setup:** baking keys in
+means every key present in `host-keys/` at build time becomes readable by
+anyone who can reach the built image — including, for the PXE variant, anyone
+who can reach the `pxe-boot` host's unauthenticated HTTP server. This is
+considered acceptable here because `pxe-boot` sits behind LAN-only network
+infrastructure, not the open internet. If that ever changes, reconsider this
+default.
+
+`auto-install.sh` still supports the older manual path as a fallback: if a
+host's key isn't baked in (`/etc/host-keys`), it checks `/root/host-keys`
+next, where you can `scp` a key in after boot, same as before this migration.
+
+## Storage
+
+Disk partitioning is handled by Disko — the installer has no hardcoded
+`parted`/`mkfs`/`mkswap`/`mount` commands, and `auto-install.sh` runs
+`disko --mode destroy,format,mount` unconditionally, no branching on whether
+the target has a Disko config. Every host reachable through this menu has
+one:
+
+- `proxmox-*` (`modules/disko/proxmox.nix`): a real GPT partition table
+  (ESP + swap + root) on `/dev/sda`.
+- `linode-*` (`modules/disko/linode.nix`): Linode provisions and sizes
+  `/dev/sda`/`/dev/sdb` itself as whole, unpartitioned block devices before
+  the OS ever boots, so this declares them with `destroy = false` (skips
+  disko's wipe stage for these disks entirely — see the option's own docs)
+  and a bare `filesystem`/`swap` content type with no partition table, and
+  the format step it does run only calls `mkfs`/`mkswap` if `blkid` shows
+  the device isn't already formatted — a re-run against an
+  already-provisioned Linode disk is a no-op, not a wipe.
+
+`lxc-*` is the only category without one — it's excluded from this menu
+entirely (see "LXC hosts" above), so it never reaches this code path.
+
+## Installer process
+
+`/etc/auto-install.sh`:
+
+1. Queries `nixosConfigurations` from this flake over the network (`git+https://<lanDomain>/beatzaplenty/nixos.git`) — this happens at *install* time, not build time, so a generic installer image always sees whatever hosts are currently committed, without needing a rebuild.
+2. Presents them as a menu; confirms the choice.
+3. Skips the `nix-cache` substituter when installing a `nix-cache` host itself (consistent with that host's own runtime config).
+4. Runs `disko --mode destroy,format,mount` (see "Storage" above — every host reachable through this menu has a Disko config, so this is unconditional).
+5. Installs the target's SSH host key from `/etc/host-keys` or `/root/host-keys` (see "Host keys" above).
+6. Runs `nixos-install --flake <url>#<choice> --no-root-password`.
+7. Cleans up and reboots.
+
+## Creating a new machine
+
+Do this instead of jumping straight to a plain install whenever the target
+host consumes any sops-nix secret — as of this writing, that's every host
+(`modules/common/configuration.nix` puts the root/nixos password hash and the
+GitHub token behind sops-nix for all of them).
+
+1. **Add the flake target** — `hosts/<name>/host.nix` plus the matching
+   `mkTarget { ... }` entry in `flake.nix`'s `generatedTargets` (see
+   "Composition pattern" in `CLAUDE.md`). No secrets involved yet, so this
+   is safe to commit on its own if you want a clean history.
+
+2. **On your admin workstation, generate and register its host key:**
+
+   ```sh
+   ./scripts/sync-host-keys.sh <flake-target>
+   ```
+
+   This generates `host-keys/<flake-target>_ssh_host_ed25519_key(.pub)`,
+   adds it as a new `.sops.yaml` anchor, works out which `secrets/*.yaml`
+   files this specific host actually references (from its own
+   `config.sops.secrets`, not guessed), adds it to each one's
+   `key_groups`, and re-encrypts them with `sops updatekeys` — no manual
+   YAML editing. Safe to re-run; it only fills in what's missing.
+
+   Doing this for every host that needs one at once — after adding several
+   new targets, or just to catch up any that were missed — is
+   `./scripts/sync-host-keys.sh --all`. See `scripts/sync-host-keys.sh --help`
+   for its other modes (`--remove`, `--regenerate-all-keys`).
+
+3. **Commit and push.** The flake build the installer uses has to see the
+   new recipient before you install, or decryption fails on first boot
+   regardless of the next step.
+
+4. **Build the installer image with keys baked in** (or reuse an already-serving `pxe-boot` host, which does this automatically once redeployed):
+
+   ```sh
+   NIXOS_HOST_KEYS_DIR="$(pwd)/host-keys" nix build .#iso --impure
+   ```
+
+5. **Boot it on the target machine**, log in, select the new host's flake
+   target from the menu, confirm. `auto-install.sh` finds the baked-in key,
+   runs Disko + `nixos-install`, and reboots.
+
+6. **Verify after reboot:**
+
+   ```sh
+   ssh <new-host> ls /run/secrets/
+   ```
+
+   If that's empty or login fails, the host's age key most likely wasn't in
+   `.sops.yaml` (or wasn't re-encrypted into the secrets file it needs) when
+   `nixos-install` ran — fix `.sops.yaml`/`secrets/*.yaml`, push, then re-run
+   `nixos-install --flake .#<hostname> --no-root-password` from a rescue
+   environment against the existing `/mnt`, or just redo the install.
+
+## Safety
+
+This installer is destructive: `disko --mode destroy,format,mount` erases
+any disk defined by the selected host's Disko configuration. Always verify
+the selected host profile and target machine before confirming.

docs/nix-cache.md

@@ -8,22 +8,41 @@ This repository configures `nix-cache` as a **binary cache server** and a **remo
 - Every machine still keeps and uses its own local `/nix/store`.
 - Clients prefer `http://nix-cache` for substitutes and keep `https://cache.nixos.org/` as fallback.
 - Clients can offload builds to `nix-cache` through SSH (`nix.distributedBuilds`).
-- Client hosts import `modules/nix/cache-client.nix` and, when remote building is enabled, `modules/nix/remote-builder-client.nix`.
+- Client hosts import `modules/nix-cache/client.nix` and, when remote building is enabled, `modules/nix-cache/remote-builder-client.nix`.
-- The `nix-cache` host imports `modules/nix/cache-server.nix`.
+- The `nix-cache` host imports `modules/nix-cache/server.nix`.
 
-## Binary cache signing keys (on nix-cache)
+## Binary cache signing key
+
+`modules/nix-cache/client.nix` hardcodes every client's trust in one
+specific public key (`cache.local-1:usoWYanY3Kpq2+kDIS2nhWoLZiRxanmdysdzqCFBHW4=`).
+That means whichever host is currently playing the `nix-cache` role has to
+use that *exact* keypair — not a freshly generated one — or no client will
+accept substitutes from it (they'd just silently fall back to building
+from source). So unlike most per-host secrets, this one can't be
+self-generated on first boot; it's managed via sops-nix like every other
+secret in this repo, sourced from `secrets/nix-cache.yaml`'s
+`cache-priv-key` entry (`modules/nix-cache/server.nix`).
+
+**Adding or rotating the value:**
 
 ```bash
-sudo install -d -m 0700 /etc/nix
+nix-shell -p sops --run 'sops secrets/nix-cache.yaml'
-sudo nix-store --generate-binary-cache-key nix-cache-1   /etc/nix/cache-priv.pem   /etc/nix/cache-pub.pem
-sudo chmod 0600 /etc/nix/cache-priv.pem
-sudo chmod 0644 /etc/nix/cache-pub.pem
-cat /etc/nix/cache-pub.pem
 ```
 
-Do not commit private keys.
+Add (or replace) a `cache-priv-key` entry with the private key file's exact
-Do not commit new password hashes or live credentials. Existing committed hashes
+contents. If you don't have it yet, generate a keypair once:
-should be rotated and moved to host-local secret management.
+
+```bash
+nix-store --generate-binary-cache-key nix-cache-1 cache-priv.pem cache-pub.pem
+```
+
+— paste `cache-priv.pem`'s contents into the `cache-priv-key` entry above,
+delete both local files afterward, and update
+`trusted-public-keys` in `modules/nix-cache/client.nix` (and every already-built
+client) to match `cache-pub.pem` if this is a genuine rotation rather than
+a first-time bootstrap. Any `nixos-configurations.*-nix-cache` host picks
+the new key up automatically on next activation — no more manual
+`/etc/nix/cache-priv.pem` install step.
 
 ## Remote builder SSH keys
 
@@ -40,6 +59,15 @@ On `nix-cache`, install the matching public key used by `nixremote` authorized k
 The committed `nixremote` authorized keys are public SSH keys only. Keep the
 matching private keys on client hosts and out of the repository.
 
+nix-cache's own SSH *host* key is trusted declaratively via
+`programs.ssh.knownHosts` in `modules/nix-cache/remote-builder-client.nix`,
+sourced from `vars.nixCacheHostKey` (`variables.nix`) — every client rebuild
+picks it up automatically, so distributed builds don't fail with "Host key
+verification failed" on a client that has never manually SSH'd to nix-cache
+before. If nix-cache's host key is ever rotated or the host rebuilt from
+scratch, update `vars.nixCacheHostKey` to match its new
+`/etc/ssh/ssh_host_ed25519_key.pub`.
+
 ## Manual verification
 
 After deployment:

docs/proxmox-images.md

@@ -0,0 +1,114 @@
+# Proxmox VM disk images
+
+`proxmox-*` hosts (VM platform, not `lxc-*`) can be built as standalone,
+ready-to-attach `.raw` disk images via disko's own image-builder — no
+`nixos-install`, no live installer boot. This uses the same `disko.devices`
+config (`modules/disko/proxmox.nix`) already used to format a real disk on
+install, so there's nothing host-specific to write; it's available for every
+`proxmox-*` target automatically.
+
+`scripts/create-proxmox-resource.sh --type vm --host <name>` automates the
+whole walkthrough below (and the equivalent LXC one) end to end, including
+host-key handling and upload — see its `--help`. The steps here are what it
+runs under the hood, useful for doing any of it by hand or understanding
+what it does before you trust it against real infrastructure.
+
+## Building
+
+```sh
+nix build .#nixosConfigurations.proxmox-server.config.system.build.diskoImagesScript
+sudo ./result --build-memory 2048
+```
+
+This produces `<hostname>.raw` in the current directory (e.g. `server.raw`
+for `proxmox-server`, matching `networking.hostName`, not the flake attribute
+name — every `proxmox-*` host gets a distinctly named image instead of all
+of them producing an identical `main.raw`). The script builds inside a
+temporary QEMU VM and moves the finished image out to the working directory
+when done; `--build-memory` controls how much RAM that build VM gets.
+
+`disko.devices.disk.main.imageSize` (currently `20G`, in
+`modules/disko/proxmox.nix`) sets the image's total size — disko doesn't
+support auto-resizing, so this needs to comfortably fit ESP + swap + root at
+build time. Grow the virtual disk (and resize the filesystem) in Proxmox
+after attaching if a host needs more than that; this is the normal way to
+size these images, not a one-time decision to get exactly right up front.
+
+## Host keys
+
+The disko image script runs a real activation pass inside its temporary
+build VM while constructing the image — the same sops-nix
+activation-before-first-boot problem the installer and LXC tarball workflows
+have (see `docs/auto-installer.md`) applies here too, unmodified. Disko has
+a native mechanism for it:
+
+```sh
+sudo ./result \
+  --pre-format-files host-keys/server_ssh_host_ed25519_key /etc/ssh/ssh_host_ed25519_key \
+  --pre-format-files host-keys/server_ssh_host_ed25519_key.pub /etc/ssh/ssh_host_ed25519_key.pub \
+  --build-memory 2048
+```
+
+Generate the key first with `scripts/sync-host-keys.sh <hostname>`, same
+as any other host — see `docs/auto-installer.md` for the full walkthrough
+(it registers the new key in `.sops.yaml` and re-encrypts the affected
+`secrets/*.yaml` files too, no manual editing needed).
+
+## Deploying to Proxmox
+
+The image needs **UEFI (OVMF)**, not Proxmox's default SeaBIOS —
+`modules/boot/efi.nix` uses `systemd-boot`, which only works with UEFI
+firmware. `virtio-scsi` is safe to use as the disk bus:
+`hardware-configuration/vm/proxmox.nix` already includes `virtio_scsi` in
+its initrd kernel modules.
+
+1. Copy the image to the Proxmox host:
+
+   ```sh
+   scp server.raw root@<proxmox-host>:/var/lib/vz/import/
+   ```
+
+2. Create an empty VM shell (no disk yet) — replace `<vmid>` with a free ID
+   and `<storage>` with your storage pool's name (`pvesm status` or
+   Datacenter → Storage in the web UI):
+
+   ```sh
+   qm create <vmid> --name proxmox-server --memory 2048 --cores 2 \
+     --net0 virtio,bridge=vmbr0 \
+     --bios ovmf --machine q35 \
+     --scsihw virtio-scsi-pci \
+     --efidisk0 <storage>:1,efitype=4m,pre-enrolled-keys=0
+   ```
+
+   (`--efidisk0` is required for UEFI — it's where OVMF persists boot-entry
+   NVRAM; without it, systemd-boot's boot entry may not survive a reboot.)
+
+3. Import the raw disk into storage:
+
+   ```sh
+   qm importdisk <vmid> /var/lib/vz/import/server.raw <storage>
+   ```
+
+   This prints the resulting disk identifier (e.g. `vm-<vmid>-disk-1`).
+
+4. Attach it and set it as the boot disk:
+
+   ```sh
+   qm set <vmid> --scsi0 <storage>:vm-<vmid>-disk-1
+   qm set <vmid> --boot order=scsi0
+   ```
+
+5. Boot it:
+
+   ```sh
+   qm start <vmid>
+   ```
+
+No install step — it boots straight into the already-activated system.
+
+## Why not `nix build .#nixosConfigurations.<host>.config.system.build.vm`?
+
+That's a different, unrelated feature — `system.build.vm` (`nixos-rebuild
+build-vm`) produces an ephemeral QEMU script for locally testing a
+configuration, not a distributable disk image. It's not part of this
+workflow.

docs/pxe-boot.md

@@ -1,6 +1,9 @@
 # pxe-boot
 
-The `pxe-boot` host serves HTTP boot assets for iPXE clients.
+The `pxe-boot` host serves HTTP boot assets for iPXE clients — including a
+self-staged copy of this flake's own auto-installer netboot image, see
+`docs/auto-installer.md` for what that image actually is and does once
+booted.
 
 ## Host Role
 
@@ -52,8 +55,15 @@ The generated menu currently exposes entries for:
 - iPXE shell
 - Reboot
 
-Kernel and initrd artifacts for the NixOS installer entry must be placed under
+The NixOS installer entry chain-loads `/srv/pxe/http/nixos/netboot.ipxe`,
-`/srv/pxe/http/nixos` by an operator or a separate build process.
+which is nixpkgs' own generated netboot iPXE script (correct `init=`/`initrd=`
+kernel parameters included) rather than a hand-rolled boot line — that script
+in turn expects its kernel/initrd siblings in the same directory. All three
+files (`bzImage`, `initrd`, `netboot.ipxe`) are built from this flake's own
+`modules/installer/iso.nix` netboot image (the same one `nix build .#pxe`
+produces) and staged automatically by
+`modules/pxe-boot/stage-installer-artifacts.nix` via `systemd.tmpfiles.rules`
+— no manual operator step required.
 
 The SystemRescue entry expects the source ISO at:
 
@@ -76,7 +86,7 @@ uses `archiso_http_srv` to fetch the squashfs payload over HTTP.
 Safe evaluation check:
 
 ```bash
-nix eval .#nixosConfigurations.pxe-boot.config.system.build.toplevel.drvPath --raw
+nix eval .#nixosConfigurations.proxmox-pxe-boot.config.system.build.toplevel.drvPath --raw
 ```
 
 After deployment by an operator, basic service checks are:

flake.nix

@@ -23,6 +23,8 @@
     let
       system = "x86_64-linux";
       inherit (nixpkgs) lib;
+      pkgs = nixpkgs.legacyPackages.${system};
+      vars = import ./variables.nix;
 
       # Generates a nixosConfiguration from a platform (what it runs on) and
       # a build type (what it's for), plus the per-identity host.nix that
@@ -31,6 +33,9 @@
       # nix-cache itself consumes the nix-cache substituter and remote
       # builder.
       mkTarget = { platform, buildType, hostPath, homeFile ? ./modules/common/home.nix }:
+        let
+          flakeTarget = "${platform}-${buildType}";
+        in
         nixpkgs.lib.nixosSystem {
           inherit system;
           modules = [
@@ -40,29 +45,36 @@
             ./modules/platforms/${platform}.nix
             ./modules/build-types/${buildType}.nix
             hostPath
-            { environment.etc."flake-target".text = "${platform}-${buildType}"; }
+            { environment.etc."flake-target".text = flakeTarget; }
             home-manager.nixosModules.home-manager
             {
               home-manager = {
                 useGlobalPkgs = true;
                 useUserPackages = true;
+                extraSpecialArgs = { inherit vars; };
                 users.nixos = import homeFile;
               };
             }
           ] ++ lib.optionals (buildType != "nix-cache") [
             ./modules/nix-cache/client.nix
-            ./modules/remote-builder-client.nix
+            ./modules/nix-cache/remote-builder-client.nix
           ];
-          specialArgs = { inherit inputs; };
+          # flakeTarget is passed via specialArgs (not read back from
+          # config.environment.etc."flake-target" above) specifically so
+          # modules/platforms/lxc.nix can use it to select its own host key
+          # file without a same-option circular dependency (a module
+          # contributing to environment.etc can't read the merged
+          # environment.etc it's itself contributing to).
+          specialArgs = { inherit inputs vars netbootSystem flakeTarget; };
         };
 
       # Generated platform x build-type matrix. pxe-boot has no linode
       # variant (PXE/DHCP/TFTP need LAN L2 adjacency, which a Linode VPS
       # doesn't have).
       generatedTargets = {
-        linode-minimal = mkTarget { platform = "linode"; buildType = "minimal"; hostPath = ./hosts/linode-minimal/host.nix; };
+        linode-minimal = mkTarget { platform = "linode"; buildType = "minimal"; hostPath = ./hosts/nix-minimal/host.nix; };
-        proxmox-minimal = mkTarget { platform = "proxmox"; buildType = "minimal"; hostPath = ./hosts/proxmox-minimal/host.nix; };
+        proxmox-minimal = mkTarget { platform = "proxmox"; buildType = "minimal"; hostPath = ./hosts/nix-minimal/host.nix; };
-        lxc-minimal = mkTarget { platform = "lxc"; buildType = "minimal"; hostPath = ./hosts/lxc-minimal/host.nix; };
+        lxc-minimal = mkTarget { platform = "lxc"; buildType = "minimal"; hostPath = ./hosts/nix-minimal/host.nix; };
 
         linode-nix-cache = mkTarget { platform = "linode"; buildType = "nix-cache"; hostPath = ./hosts/nix-cache/host.nix; };
         proxmox-nix-cache = mkTarget { platform = "proxmox"; buildType = "nix-cache"; hostPath = ./hosts/nix-cache/host.nix; };
@@ -82,11 +94,63 @@
 
         proxmox-pxe-boot = mkTarget { platform = "proxmox"; buildType = "pxe-boot"; hostPath = ./hosts/pxe-boot/host.nix; };
         lxc-pxe-boot = mkTarget { platform = "lxc"; buildType = "pxe-boot"; hostPath = ./hosts/pxe-boot/host.nix; };
+
+        linode-tailscale-exit-node = mkTarget { platform = "linode"; buildType = "tailscale-exit-node"; hostPath = ./hosts/tailscale-exit-node/host.nix; };
+        proxmox-tailscale-exit-node = mkTarget { platform = "proxmox"; buildType = "tailscale-exit-node"; hostPath = ./hosts/tailscale-exit-node/host.nix; };
+        lxc-tailscale-exit-node = mkTarget { platform = "lxc"; buildType = "tailscale-exit-node"; hostPath = ./hosts/tailscale-exit-node/host.nix; };
+      };
+
+      # Auto-install environments (migrated from the former nix-auto-installer
+      # flake): a self-contained NixOS installer that boots, discovers this
+      # flake's own nixosConfigurations over the network, and runs
+      # nixos-install against whichever one the operator picks. These are
+      # deliberately not part of the platform x build-type matrix above —
+      # they're throwaway boot media, not persistent hosts, so they skip
+      # disko/sops-nix/home-manager and just need `vars`.
+      installerTargets = {
+        installer = nixpkgs.lib.nixosSystem {
+          inherit system;
+          modules = [ ./modules/installer/iso.nix ];
+          specialArgs = { inherit vars; };
+        };
+      };
+
+      # Same installer environment, built as netboot (kernel + initrd +
+      # iPXE script) instead of an ISO — this is what packages.pxe bundles.
+      netbootSystem = nixpkgs.lib.nixosSystem {
+        inherit system;
+        modules = [
+          ./modules/installer/iso.nix
+          ({ modulesPath, ... }: {
+            imports = [
+              (modulesPath + "/installer/netboot/netboot-minimal.nix")
+            ];
+          })
+        ];
+        specialArgs = { inherit vars; };
       };
 
     in
     {
 
-      nixosConfigurations = generatedTargets;
+      nixosConfigurations = generatedTargets // installerTargets;
+
+      # Buildable auto-installer artifacts (`nix build .#<name>`). No `lxc`
+      # variant (installer-boots-as-an-LXC-container) or `all` bundle
+      # anymore — lxc-* and proxmox-* hosts deploy via their own tarball/
+      # disk-image outputs instead (see docs/auto-installer.md and
+      # docs/proxmox-images.md), which left the installer's own LXC form
+      # with no real use case: it's excluded from the install menu (same
+      # bind-mount problem as any LXC nixos-install target) and nothing
+      # else needed booting the installer itself as a container.
+      packages.${system} = {
+        iso = installerTargets.installer.config.system.build.isoImage;
+
+        pxe = pkgs.linkFarm "pxe" [
+          { name = "netboot.ipxe"; path = netbootSystem.config.system.build.netbootIpxeScript; }
+          { name = "initrd"; path = netbootSystem.config.system.build.netbootRamdisk; }
+          { name = "kernel"; path = netbootSystem.config.system.build.kernel; }
+        ];
+      };
     };
 }

hosts/docker/host.nix

@@ -1,4 +1,4 @@
-{ ... }:
+_:
 
 {
   networking.hostName = "docker";

hosts/linode-minimal/host.nix

@@ -1,9 +0,0 @@
-{ ... }:
-
-{
-  networking.hostName = "linode-minimal";
-
-  # Preserved from the pre-refactor `linode-minimal` target — stateVersion
-  # must never be bumped on an already-installed machine.
-  system.stateVersion = "26.05";
-}

hosts/lxc-minimal/host.nix

@@ -1,9 +0,0 @@
-{ ... }:
-
-{
-  networking.hostName = "lxc-minimal";
-
-  # No pre-existing deployed machine to preserve — pin explicitly to the
-  # current release rather than let it silently default.
-  system.stateVersion = "26.05";
-}

hosts/nix-cache/host.nix

@@ -1,19 +1,19 @@
-{ config, ... }:
+{ vars, ... }:
 
 {
-  networking.hostName = "nix-cache";
+  imports = [
+    (import ../../modules/beszel/host-token.nix {
+      name = "nix-cache";
+      sopsFile = ../../secrets/nix-cache.yaml;
+    })
+  ];
 
-  sops.secrets."beszel-token".sopsFile = ../../secrets/nix-cache.yaml;
+  networking.hostName = vars.nixCacheHost;
-  sops.templates."nix-cache-beszel.env".content = ''
-    TOKEN=${config.sops.placeholder."beszel-token"}
-  '';
 
   services.beszel.agent.environment = {
     #DOCKER_HOST = "tcp://docker-socket-proxy:2375";
-    #HUB_URL = "http://docker.sweet.home:8090";
     KEY = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIFPR9kwtC4TAeTRu46A7+opZsYpxqkRJ+x/ZyB2GWCeG";
   };
-  services.beszel.agent.environmentFile = config.sops.templates."nix-cache-beszel.env".path;
 
   # Preserved from the pre-refactor `nix-cache` target — stateVersion must
   # never be bumped on an already-installed machine.

hosts/nix-minimal/host.nix

@@ -1,4 +1,4 @@
-{ ... }:
+_:
 
 {
   # Preserves the hostname of the existing, already-deployed machine

hosts/nixos/home.nix

@@ -1,79 +1,82 @@
-{ config, pkgs, lib, ... }:
+{ config, pkgs, lib, vars, ... }:
 
 {
 
-    imports = [
+  imports = [
     ../../modules/common/aliases.nix
   ];
 
-  home.username = "nixos";         # your actual username
+  home = {
-  home.homeDirectory = "/home/nixos";
+    username = vars.primaryUser;
-  home.stateVersion = "25.05";        # match your NixOS stateVersion
+    homeDirectory = "/home/${vars.primaryUser}";
+    stateVersion = "25.05"; # match your NixOS stateVersion
 
-  programs.home-manager.enable = true;  # mandatory to activate HM
+    # Optional: packages
+    packages = with pkgs; [
+      git
+      vim
+      tmux
+      nextcloud-client
+      #    vscode
+      chromium
+    ];
 
-  # Optional: packages
+    # Optional: set environment vars
-  home.packages = with pkgs; [
+    sessionVariables = {
-    git
+      EDITOR = "vim";
-    vim
+    };
-    tmux
-    nextcloud-client
-#    vscode
-    chromium
-  ];
 
-  # Optional: set environment vars
+    file = {
-  home.sessionVariables = {
+      ".local/share/applications/proxmox-chromium-app.desktop".text = ''
-    EDITOR = "vim";
+        [Desktop Entry]
+        Type=Application
+        Name=Proxmox (Chromium)
+        Exec=chromium --app=https://pve.${vars.homeDomain}:${toString vars.ports.pveWeb} --window-size=1920,1080 --window-position=0,0
+        Icon=${config.home.homeDirectory}/.local/share/icons/proxmox.png
+        Terminal=false
+        Categories=Hypervisor;
+        StartupWMClass=PVE
+      '';
+      ".local/share/applications/pbs-chromium-app.desktop".text = ''
+        [Desktop Entry]
+        Type=Application
+        Name=Proxmox Backup Server (Chromium)
+        Exec=chromium --app=https://${vars.pbsIp}:${toString vars.ports.pbsWeb} --window-size=1920,1080 --window-position=0,0
+        Icon=${config.home.homeDirectory}/.local/share/icons/proxmox.png
+        Terminal=false
+        Categories=backup;
+
+      '';
+      ".local/share/applications/proxmox-firefox-app.desktop".text = ''
+        [Desktop Entry]
+        Type=Application
+        Name=Proxmox (Firefox)
+        Exec=firefox --new-instance https://pve.${vars.homeDomain}:${toString vars.ports.pveWeb} --profile ProxmoxWebApp --window-size=1920,1080 --class ProxmoxWebApp
+        Icon=${config.home.homeDirectory}/.local/share/icons/proxmox.png
+        Terminal=false
+        Categories=Hypervisor;
+        StartupWMClass=PVE
+      '';
+      ".local/share/applications/pbs-firefox-app.desktop".text = ''
+        [Desktop Entry]
+        Type=Application
+        Name=Proxmox Backup Server (Firefox)
+        Exec=firefox --new-window https://${vars.pbsIp}:${toString vars.ports.pbsWeb} --profile PbsWebApp --window-size=1920,1080 --class PbsWebApp
+        Icon=${config.home.homeDirectory}/.local/share/icons/proxmox.png
+        Terminal=false
+        Categories=backup;
+        StartupWMClass=PBS
+      '';
+    };
   };
 
+  programs.home-manager.enable = true; # mandatory to activate HM
+
   # Optional: enable bash (or zsh, fish...)
   programs.bash.enable = true;
-    services.nextcloud-client = {
+  services.nextcloud-client = {
     enable = true;
     # Optionally start in background directly
     startInBackground = true;
   };
-home.file = {
+}
-  ".local/share/applications/proxmox-chromium-app.desktop".text = ''
-    [Desktop Entry]
-    Type=Application
-    Name=Proxmox (Chromium)
-    Exec=chromium --app=https://pve.sweet.home:8006 --window-size=1920,1080 --window-position=0,0
-    Icon=/home/nixos/.local/share/icons/proxmox.png
-    Terminal=false
-    Categories=Hypervisor;
-    StartupWMClass=PVE
-  '';
-  ".local/share/applications/pbs-chromium-app.desktop".text = ''
-    [Desktop Entry]
-    Type=Application
-    Name=Proxmox Backup Server (Chromium)
-    Exec=chromium --app=https://192.168.2.108:8007 --window-size=1920,1080 --window-position=0,0
-    Icon=/home/nixos/.local/share/icons/proxmox.png
-    Terminal=false
-    Categories=backup;
-
-  '';
-  ".local/share/applications/proxmox-firefox-app.desktop".text = ''
-    [Desktop Entry]
-    Type=Application
-    Name=Proxmox (Firefox)
-    Exec=firefox --new-instance https://pve.sweet.home:8006 --profile ProxmoxWebApp --window-size=1920,1080 --class ProxmoxWebApp
-    Icon=/home/nixos/.local/share/icons/proxmox.png
-    Terminal=false
-    Categories=Hypervisor;
-    StartupWMClass=PVE
-  '';
-  ".local/share/applications/pbs-firefox-app.desktop".text = ''
-    [Desktop Entry]
-    Type=Application
-    Name=Proxmox Backup Server (Firefox)
-    Exec=firefox --new-window https://192.168.2.108:8007 --profile PbsWebApp --window-size=1920,1080 --class PbsWebApp
-    Icon=/home/nixos/.local/share/icons/proxmox.png
-    Terminal=false
-    Categories=backup;
-    StartupWMClass=PBS
-  '';
-};
-}

hosts/nixos/host.nix

@@ -1,4 +1,4 @@
-{ ... }:
+_:
 
 {
   networking.hostName = "nixos";

hosts/pxe-boot/host.nix

@@ -1,4 +1,4 @@
-{ ... }:
+_:
 
 {
   networking.hostName = "pxe-boot";

hosts/server/host.nix

@@ -1,22 +1,22 @@
-{ config, ... }:
+{ vars, ... }:
 
 {
-  networking.hostName = "server";
+  imports = [
-  networking.hostId = "6689f93e";
+    (import ../../modules/beszel/host-token.nix {
+      name = "server";
+      sopsFile = ../../secrets/server.yaml;
+    })
+  ];
 
-  sops.secrets."beszel-token".sopsFile = ../../secrets/server.yaml;
+  networking.hostName = vars.nfsServerHost;
-  sops.templates."server-beszel.env".content = ''
+  networking.hostId = "6689f93e";
-    TOKEN=${config.sops.placeholder."beszel-token"}
-  '';
 
   services.beszel.agent.environment = {
     #DOCKER_HOST = "tcp://docker-socket-proxy:2375";
-    #HUB_URL = "http://docker.sweet.home:8090";
     KEY = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIFPR9kwtC4TAeTRu46A7+opZsYpxqkRJ+x/ZyB2GWCeG";
-    EXTRA_FILESYSTEMS = "/tank/docker/volumes";
+    EXTRA_FILESYSTEMS = "${vars.storageRoot}/${vars.nfsShares.dockerVolumes.subpath}";
     LOG_LEVEL = "debug";
   };
-  services.beszel.agent.environmentFile = config.sops.templates."server-beszel.env".path;
 
   # Preserved from the pre-refactor `server` target — stateVersion must never
   # be bumped on an already-installed machine.

hosts/tailscale-exit-node/host.nix

@@ -0,0 +1,12 @@
+_:
+
+{
+  networking.hostName = "exit-node";
+
+  # No networking.hostId: only ZFS-touching hosts (server, docker) need one
+  # for pool-import safety, and this host does neither.
+
+  # A genuinely new host (not a pre-refactor carry-over), so it tracks the
+  # flake's current nixpkgs release rather than being pinned to an older one.
+  system.stateVersion = "26.05";
+}

modules/beszel/enable-agent.nix

@@ -1,9 +1,18 @@
-{ ... }:
+{ vars, ... }:
 
 {
-services.beszel.agent.enable = true;
+  services.beszel.agent.enable = true;
-services.beszel.agent.environment = {
+  services.beszel.agent.environment = {
-#DOCKER_HOST = "tcp://docker-socket-proxy:2375";
+    #DOCKER_HOST = "tcp://docker-socket-proxy:2375";
-HUB_URL = "http://docker.sweet.home:8090";
+    HUB_URL = "http://${vars.dockerHost}.${vars.homeDomain}:${toString vars.ports.beszelHub}";
-};
+  };
+
+  # The upstream module runs beszel-agent under DynamicUser with
+  # ProtectSystem = "strict" and no StateDirectory, so /var/lib/beszel-agent
+  # (where the agent persists its hub-pairing fingerprint, per
+  # https://github.com/henrygd/beszel/discussions/1542) isn't writable --
+  # every restart silently fails to save it and regenerates a fresh one in
+  # memory, permanently desyncing from whatever the hub has on record after
+  # the very first successful pairing. Give it real persistent storage.
+  systemd.services.beszel-agent.serviceConfig.StateDirectory = "beszel-agent";
 }

modules/beszel/host-token.nix

@@ -0,0 +1,11 @@
+{ name, sopsFile }:
+
+{ config, ... }:
+
+{
+  sops.secrets."beszel-token".sopsFile = sopsFile;
+  sops.templates."${name}-beszel.env".content = ''
+    TOKEN=${config.sops.placeholder."beszel-token"}
+  '';
+  services.beszel.agent.environmentFile = config.sops.templates."${name}-beszel.env".path;
+}

modules/boot/efi.nix

@@ -1,6 +1,6 @@
-{ ... }:
+_:
 
 {
   boot.loader.systemd-boot.enable = true;
   boot.loader.efi.canTouchEfiVariables = true;
-}
+}

modules/build-types/docker.nix

@@ -1,4 +1,4 @@
-{ pkgs, ... }:
+{ pkgs, vars, ... }:
 
 {
   # Pins the Docker Engine version, carried forward from the pre-refactor
@@ -13,11 +13,11 @@
   imports = [
     ../docker/mount-data.nix
     ../docker/enable-service.nix
+    ../docker/nextcloud-cron-job.nix
+    ../docker/docker-health-to-gotify.nix
     ../tailscale/enable-service.nix
-    ../rotate-traefik-logs.nix
+    ../traefik/rotate-logs.nix
     ../raspi/mount-data.nix
-    ../services/nextcloud-cron-job.nix
-    ../services/docker-health-to-gotify.nix
     ../services/enable-rpcbind.nix
   ];
 
@@ -28,13 +28,18 @@
   boot.supportedFilesystems = [ "nfs" ];
 
   systemd.tmpfiles.rules = [
-    "L+ /home/nixos/docker - - - - /mnt/docker/config"
+    "L+ /home/${vars.primaryUser}/docker - - - - ${vars.nfsShares.dockerConfig.mountpoint}"
-    "d /mnt/docker 0755 nixos users -"
+    "d /mnt/docker 0755 ${vars.primaryUser} users -"
-    "d /mnt/raspi-backup 0755 nixos users -"
+    "d ${vars.nfsShares.raspiVolumes.mountpoint} 0755 ${vars.primaryUser} users -"
   ];
 
-  users.users.nixos.extraGroups = [ "docker" ];
+  users.users.${vars.primaryUser}.extraGroups = [ "docker" ];
   services.openssh.settings.PermitRootLogin = "yes";
 
-  networking.firewall.allowedTCPPorts = [ 80 8080 443 8090 ];
+  networking.firewall.allowedTCPPorts = [
+    vars.ports.dockerHttp
+    vars.ports.dockerExtra
+    vars.ports.dockerHttps
+    vars.ports.beszelHub
+  ];
 }

modules/build-types/gui.nix

@@ -1,8 +1,8 @@
-{ config, pkgs, lib, inputs, ... }:
+{ config, pkgs, lib, inputs, vars, ... }:
 
 {
   environment.systemPackages = with pkgs; [
-    inputs.nixos-conf-editor.packages.${pkgs.system}.nixos-conf-editor
+    inputs.nixos-conf-editor.packages.${pkgs.stdenv.hostPlatform.system}.nixos-conf-editor
     nodejs
     appimage-run
     seahorse
@@ -19,39 +19,55 @@
 
   boot.loader.grub.useOSProber = true;
 
-  services.xserver.enable = true;
+  services = {
-  services.xserver.displayManager.lightdm.enable = true;
+    xserver = {
-  services.xserver.desktopManager.cinnamon.enable = true;
+      enable = true;
 
-  services.xserver.xkb = {
+      displayManager = {
-    layout = "au";
+        lightdm.enable = true;
-    variant = "";
+        sessionCommands = ''
+          eval $(gnome-keyring-daemon --start --components=secrets,ssh)
+          export SSH_AUTH_SOCK
+        '';
+      };
+
+      desktopManager.cinnamon.enable = true;
+
+      xkb = {
+        layout = "au";
+        variant = "";
+      };
+    };
+
+    printing.enable = true;
+
+    pipewire = {
+      enable = true;
+      alsa.enable = true;
+      alsa.support32Bit = true;
+      pulse.enable = true;
+    };
+
+    xrdp = {
+      enable = true;
+      defaultWindowManager = "cinnamon-session";
+      openFirewall = true;
+    };
+
+    gnome.gnome-keyring.enable = true;
   };
 
-  services.printing.enable = true;
+  security = {
-
+    rtkit.enable = true;
-  security.rtkit.enable = true;
+    pam.services.login.enableGnomeKeyring = true;
-  services.pipewire = {
-    enable = true;
-    alsa.enable = true;
-    alsa.support32Bit = true;
-    pulse.enable = true;
   };
 
-  users.users.nixos.extraGroups = [ "networkmanager" ];
+  # The networkmanager group only exists when NM is actually enabled — the
+  # lxc platform module force-disables it, so don't add the user to a group
+  # that won't exist there.
+  users.users.${vars.primaryUser}.extraGroups = lib.mkIf config.networking.networkmanager.enable [ "networkmanager" ];
 
   programs.firefox.enable = true;
 
-  services.xrdp.enable = true;
-  services.xrdp.defaultWindowManager = "cinnamon-session";
-  services.xrdp.openFirewall = true;
   nixpkgs.config.allowUnfree = true;
-
-  services.gnome.gnome-keyring.enable = true;
-  security.pam.services.login.enableGnomeKeyring = true;
-
-  services.xserver.displayManager.sessionCommands = ''
-    eval $(gnome-keyring-daemon --start --components=secrets,ssh)
-    export SSH_AUTH_SOCK
-  '';
 }

modules/build-types/minimal.nix

@@ -1,9 +1,12 @@
-{ pkgs, ... }:
+{ lib, pkgs, config, vars, ... }:
 
 {
   networking.networkmanager.enable = true;
 
-  users.users.nixos.extraGroups = [ "networkmanager" ];
+  # The networkmanager group only exists when NM is actually enabled — the
+  # lxc platform module force-disables it, so don't add the user to a group
+  # that won't exist there.
+  users.users.${vars.primaryUser}.extraGroups = lib.mkIf config.networking.networkmanager.enable [ "networkmanager" ];
 
   environment.systemPackages = with pkgs; [
     inetutils

modules/build-types/pxe-boot.nix

@@ -1,10 +1,10 @@
-{ config, lib, pkgs, inputs, ... }:
+{ config, lib, pkgs, inputs, vars, ... }:
 
 let
   pxeRoot = "/srv/pxe";
   httpRoot = "${pxeRoot}/http";
   tftpRoot = "${pxeRoot}/tftp";
-  pxeBaseUrl = "http://192.168.2.247";
+  pxeBaseUrl = "http://${vars.pxeServerIp}";
 
   bootIpxe = pkgs.writeText "boot.ipxe" ''
     #!ipxe
@@ -76,9 +76,7 @@ let
     choose target && goto ''${target}
 
     :nixos
-    kernel ''${base}/nixos/bzImage ip=dhcp
+    chain ''${base}/nixos/netboot.ipxe
-    initrd ''${base}/nixos/initrd
-    boot
 
     :rescue
     chain ''${base}/systemrescue.ipxe
@@ -91,32 +89,40 @@ let
   '';
 in
 {
+  imports = [
+    ../pxe-boot/stage-installer-artifacts.nix
+  ];
+
   environment.systemPackages = with pkgs; [
     ipxe
   ];
 
-  services.nginx = {
+  services = {
-    enable = true;
+    nginx = {
+      enable = true;
 
-    virtualHosts."pxe-boot" = {
+      virtualHosts."pxe-boot" = {
-      default = true;
+        default = true;
-      root = httpRoot;
+        root = httpRoot;
-      locations."/" = {
+        locations."/" = {
-        extraConfig = ''
+          extraConfig = ''
-          autoindex on;
+            autoindex on;
-        '';
+          '';
+        };
       };
     };
-  };
 
-  # TFTP is only used to deliver the initial iPXE bootloader. After iPXE
+    # TFTP is only used to deliver the initial iPXE bootloader. After iPXE
-  # starts, all further assets are fetched via nginx over HTTP.
+    # starts, all further assets are fetched via nginx over HTTP.
-  services.atftpd = {
+    atftpd = {
-    enable = true;
+      enable = true;
-    root = tftpRoot;
+      root = tftpRoot;
-    extraOptions = [
+      extraOptions = [
-      "--verbose=5"
+        "--verbose=5"
-    ];
+      ];
+    };
+
+    openssh.settings.PermitRootLogin = "yes";
   };
 
   systemd.tmpfiles.rules = [
@@ -149,8 +155,6 @@ in
     };
   };
 
-  services.openssh.settings.PermitRootLogin = "yes";
+  networking.firewall.allowedTCPPorts = [ vars.ports.pxeBootHttp ];
-
+  networking.firewall.allowedUDPPorts = [ vars.ports.pxeBootTftp ];
-  networking.firewall.allowedTCPPorts = [ 80 ];
-  networking.firewall.allowedUDPPorts = [ 69 ];
 }

modules/build-types/server.nix

@@ -1,4 +1,4 @@
-{ ... }:
+{ vars, lib, ... }:
 
 {
   imports = [
@@ -6,7 +6,7 @@
     ../services/zfs/enable-service.nix
   ];
 
-  boot.zfs.extraPools = [ "tank" ];
+  boot.zfs.extraPools = [ (lib.removePrefix "/" vars.storageRoot) ];
 
   systemd.services.nfs-server = {
     after = [ "zfs-mount.service" ];
@@ -16,13 +16,13 @@
   services.nfs.server = {
     enable = true;
     exports = ''
-      /tank/docker/config 192.168.2.0/24(rw,sync,no_subtree_check,no_root_squash)
+      ${vars.storageRoot}/${vars.nfsShares.dockerConfig.subpath} ${vars.lanCidr}(rw,sync,no_subtree_check,no_root_squash)
-      /tank/docker/volumes 192.168.2.0/24(rw,sync,no_subtree_check,no_root_squash)
+      ${vars.storageRoot}/${vars.nfsShares.dockerVolumes.subpath} ${vars.lanCidr}(rw,sync,no_subtree_check,no_root_squash)
-      /tank/docker/databases 192.168.2.0/24(rw,sync,no_subtree_check,no_root_squash)
+      ${vars.storageRoot}/${vars.nfsShares.dockerDatabases.subpath} ${vars.lanCidr}(rw,sync,no_subtree_check,no_root_squash)
-      /tank/docker/nextcloud-data 192.168.2.0/24(rw,sync,no_subtree_check,no_root_squash)
+      ${vars.storageRoot}/${vars.nfsShares.nextcloudData.subpath} ${vars.lanCidr}(rw,sync,no_subtree_check,no_root_squash)
-      /tank/raspi/volumes 192.168.2.0/24(rw,sync,no_subtree_check,no_root_squash)
+      ${vars.storageRoot}/${vars.nfsShares.raspiVolumes.subpath} ${vars.lanCidr}(rw,sync,no_subtree_check,no_root_squash)
     '';
   };
 
-  networking.firewall.allowedTCPPorts = [ 111 2049 ];
+  networking.firewall.allowedTCPPorts = [ vars.ports.nfsRpcbind vars.ports.nfsd ];
 }

modules/build-types/tailscale-exit-node.nix

@@ -0,0 +1,21 @@
+{ ... }:
+
+{
+  imports = [
+    ../tailscale/exit-node.nix
+  ];
+
+  # "server", not "both": this build type only ever advertises itself as an
+  # exit node (see ../tailscale/exit-node.nix) -- it doesn't advertise LAN
+  # subnet routes, so it doesn't need the "client"-side loose reverse-path
+  # filtering that "both" would also turn on. Deliberately left unbundled
+  # from LAN-subnet-route advertisement so this build type stays valid on
+  # every platform, including linode (a remote VPS with no network path to
+  # the home LAN at all).
+  services.tailscale.useRoutingFeatures = "server";
+
+  # Forwarded exit-node traffic arrives on tailscale0 already
+  # tailscale-authenticated -- the firewall's normal per-port allow-list
+  # would otherwise drop it. Standard NixOS/Tailscale exit-node guidance.
+  networking.firewall.trustedInterfaces = [ "tailscale0" ];
+}

modules/common/aliases.nix

@@ -1,4 +1,4 @@
-{ config, pkgs, lib, ... }:
+{ config, pkgs, lib, vars, ... }:
 
 let
   # Flake attribute names are now <platform>-<buildtype> (e.g. proxmox-docker)
@@ -9,13 +9,33 @@ let
     sudo nixos-rebuild switch \
       --no-write-lock-file \
       --refresh \
-      --flake git+https://gitea.lan.ddnsgeek.com/beatzaplenty/nixos.git#$(cat /etc/flake-target)
+      --flake git+https://${vars.lanDomain}/beatzaplenty/nixos.git#$(cat /etc/flake-target)
   '';
   myTestCmd = ''
     sudo nixos-rebuild test \
       --no-write-lock-file \
       --refresh \
-      --flake git+https://gitea.lan.ddnsgeek.com/beatzaplenty/nixos.git#$(cat /etc/flake-target)
+      --flake git+https://${vars.lanDomain}/beatzaplenty/nixos.git#$(cat /etc/flake-target)
+  '';
+
+  # lxc-* hosts pre-seed their SSH host key at build time (see
+  # modules/platforms/lxc.nix) so sops-nix's .sops.yaml recipient matches on
+  # first boot -- without it, secrets permanently fail to decrypt (see that
+  # file's comment for the confirmed failure). That requires --impure plus
+  # NIXOS_HOST_KEYS_DIR pointing at the repo's host-keys/ dir, same pattern
+  # docs/auto-installer.md uses for the installer ISO. A function, not a
+  # shellAlias, since the target name has to interpolate into the middle of
+  # the flake attribute path, not just append after it. Must be run from the
+  # repo root, same as every other host-keys/ command in this repo.
+  buildImageFn = ''
+    buildImage() {
+      if [ -z "$1" ]; then
+        echo "usage: buildImage <flake-target>  (e.g. lxc-docker)" >&2
+        return 1
+      fi
+      NIXOS_HOST_KEYS_DIR="$(pwd)/host-keys" nix build --impure \
+        ".#nixosConfigurations.$1.config.system.build.tarball"
+    }
   '';
 in
 {
@@ -25,5 +45,6 @@ in
       "Switch-nix" = mySwitchCmd;
       "Test-nix" = myTestCmd;
     };
+    initExtra = buildImageFn;
   };
 }

modules/common/configuration.nix

@@ -1,29 +1,36 @@
-{ config, lib, pkgs, ... }:
+{ config, lib, pkgs, vars, ... }:
 
 {
-    imports =
+  imports =
-    [ # Include the results of the hardware scan.
+    [
-#      ./hardware-configuration.nix
+      # Include the results of the hardware scan.
-      ../set-locale.nix
+      #      ./hardware-configuration.nix
+      ./set-locale.nix
     ];
   # Use the GRUB 2 boot loader.
   # boot.loader.grub.enable = true;
   #boot.loader.grub.device = "/dev/sda"; # or "nodev" for efi only
 
-  networking.networkmanager.enable = true;  # Easiest to use and most distros use this by default.
+  networking.networkmanager.enable = true; # Easiest to use and most distros use this by default.
+
+  # Recommended over the true default (bypasses ZFS's own import safeguards)
+  # per the option's own docs; matches hosts/docker/host.nix and
+  # modules/services/zfs/enable-service.nix, which already set this
+  # explicitly. Harmless no-op on hosts that don't use ZFS at all.
+  boot.zfs.forceImportRoot = false;
 
   # Set your time zone.
-  time.timeZone = "Australia/Brisbane";
+  time.timeZone = vars.timeZone;
 
   # Enable QEMU agent
   services.qemuGuest.enable = true;
 
-    # Enable docker-compose
+  # Enable docker-compose
   environment.systemPackages = with pkgs; [
-  vim
+    vim
-  btop
+    btop
-  git
+    git
-  gcr
+    gcr
   ];
 
   # Secrets shared by every host, decrypted at activation via each host's
@@ -32,28 +39,34 @@
   # or docs/ for the sops workflow). hashedPassword/hashedPasswordFile need
   # neededForUsers so they're available before the normal secret-activation
   # step, since user creation happens very early in boot.
-  sops.defaultSopsFile = ../../secrets/common.yaml;
+  sops = {
-  sops.secrets."root-hashedPassword".neededForUsers = true;
+    defaultSopsFile = ../../secrets/common.yaml;
-  sops.secrets."nixos-hashedPassword".neededForUsers = true;
+
-  sops.secrets."nix-github-token" = { };
+    secrets = {
+      "root-hashedPassword".neededForUsers = true;
+      "nixos-hashedPassword".neededForUsers = true;
+      "nix-github-token" = { };
+    };
+
+    # nix.conf doesn't support a *File-style option for access-tokens, so the
+    # token is rendered into a runtime-only file (never touches the Nix store)
+    # and pulled in via nix.conf's native !include directive.
+    templates."nix-github-token.conf".content = ''
+      access-tokens = github.com=${config.sops.placeholder."nix-github-token"}
+    '';
+  };
 
-  # nix.conf doesn't support a *File-style option for access-tokens, so the
-  # token is rendered into a runtime-only file (never touches the Nix store)
-  # and pulled in via nix.conf's native !include directive.
-  sops.templates."nix-github-token.conf".content = ''
-    access-tokens = github.com=${config.sops.placeholder."nix-github-token"}
-  '';
   nix.extraOptions = ''
     !include ${config.sops.templates."nix-github-token.conf".path}
   '';
 
-#Set root password
+  #Set root password
-users.users.root = {
+  users.users.root = {
-  hashedPasswordFile = config.sops.secrets."root-hashedPassword".path;
+    hashedPasswordFile = config.sops.secrets."root-hashedPassword".path;
-};
+  };
 
   # Define a user account. Don't forget to set a password with ‘passwd’.
-  users.users.nixos = {
+  users.users.${vars.primaryUser} = {
     isNormalUser = true;
     extraGroups = [ "wheel" ]; # Enable ‘sudo’ for the user.
     packages = with pkgs; [
@@ -61,8 +74,8 @@ users.users.root = {
     ];
     hashedPasswordFile = config.sops.secrets."nixos-hashedPassword".path;
     openssh.authorizedKeys.keys = [
-    "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCq/Q5LvIXlZwO2kdeAN5nLGZ59nZB7JHYMEszHxmNtGMzv1lM31jiPNsr0z2EKVZhE7OOfa2IF9rhWYD7JUA9G0yzdZ4WTXFNGVVOJoOVH6vAF3XCxoVilOEwTc7h2Wiy+rzd0B28/3spffzQQWJhY6GRQVa8j+6xAGF60Fcvl1vLosYT9Bn2ZbK4TCWOwAn2jqXIieGpZdn/UNZbGOeKRiCvhktDfMAzuQzN/9jMu/oF4pkPn2X1UrsQdNlvp0Ci8md612MozIpncQJyAF1ADhunr3sMx0isUXiqD29R5DS4TftpekqLNLak+zcxFa8N7DcRNp3DcKfJvyTkwQrR4r+b7lFLYOLHLagSso9CzeW/paAS2q9I5SBm/2DtE1diLLg2jZikYcstsu/G5RgvbzbKqjiaMwTdXC3AMvDxQrs7U5pDRZFzoofG3cpODbTm+uy3m0kP70z0M1K45UbDG0p+itnTu9x40JbQEgefbx38AItNvAIx1A8HO4I1VX28= wayne@stream"
+      vars.adminSshKey
-    "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICMJhrfFayLBG+gWtO6oAvgambw5nWWgztiTFEaaaVRH debian@surface"
+      "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICMJhrfFayLBG+gWtO6oAvgambw5nWWgztiTFEaaaVRH debian@surface"
     ];
   };
 
@@ -88,4 +101,4 @@ users.users.root = {
 
 
 
-}
+}

modules/common/home.nix

@@ -1,65 +1,69 @@
-{ config, pkgs, lib, ... }:
+{ config, pkgs, lib, vars, ... }:
 
 let
   remote = "root@proxmox-ip:/var/lib/vz/template/iso";
   localMount = "${config.home.homeDirectory}/proxmox-iso";
-in {
+in
+{
 
   imports = [
     ./aliases.nix
   ];
 
-  home.username = "nixos";         # your actual username
+  home = {
-  home.homeDirectory = "/home/nixos";
+    username = vars.primaryUser;
-  home.stateVersion = "25.11";        # match your NixOS stateVersion
+    homeDirectory = "/home/${vars.primaryUser}";
+    stateVersion = "25.11"; # match your NixOS stateVersion
+
+    # Optional: packages
+    packages = with pkgs; [
+      git
+      vim
+      tmux
+      nano
+      sshfs
+    ];
+
+    # Optional: set environment vars
+    sessionVariables = {
+      EDITOR = "nano";
+    };
+  };
+
+  programs.home-manager.enable = true; # mandatory to activate HM
+
+  programs.bash.enable = true;
 
-  programs.home-manager.enable = true;  # mandatory to activate HM
-  
-programs.bash.enable = true;
-  
   # GitHub access-tokens setting used to live here in plaintext; it's now
   # rendered system-wide from a sops-nix secret via nix.extraOptions in
   # modules/common/configuration.nix instead (covers the daemon for every
   # user, not just this one).
 
-  # Optional: packages
+  #  systemd.user.services.mount-proxmox-iso = {
-  home.packages = with pkgs; [
+  #    Unit = {
-    git
+  #      Description = "Mount Proxmox ISO dir via SSHFS";
-    vim
+  #      After = [ "network-online.target" ];
-    tmux
+  #      Wants = [ "network-online.target" ];
-    nano
+  #    };
-    sshfs
-  ];
 
-  # Optional: set environment vars
+  #    Service = {
-  home.sessionVariables = {
+  #      Type = "simple";
-    EDITOR = "nano";
+  #      ExecStartPre = "${pkgs.coreutils}/bin/mkdir -p ${localMount}";
-  };
+  #      ExecStart = "${pkgs.sshfs}/bin/sshfs -o IdentityFile=${config.home.homeDirectory}/.ssh/id_ed25519,allow_other,reconnect,ServerAliveInterval=15,ServerAliveCountMax=3 root@proxmox-ip:/var/lib/vz/template/iso ${localMount}";
-#  systemd.user.services.mount-proxmox-iso = {
+  #      ExecStop = "${pkgs.fuse3}/bin/fusermount3 -u ${localMount}";
-#    Unit = {
+  #      Restart = "on-failure";
-#      Description = "Mount Proxmox ISO dir via SSHFS";
+  #    };
-#      After = [ "network-online.target" ];
-#      Wants = [ "network-online.target" ];
-#    };
 
-#    Service = {
+  #    Install = {
-#      Type = "simple";
+  #      WantedBy = [ "default.target" ];
-#      ExecStartPre = "${pkgs.coreutils}/bin/mkdir -p ${localMount}";
+  #    };
-#      ExecStart = "${pkgs.sshfs}/bin/sshfs -o IdentityFile=${config.home.homeDirectory}/.ssh/id_ed25519,allow_other,reconnect,ServerAliveInterval=15,ServerAliveCountMax=3 root@proxmox-ip:/var/lib/vz/template/iso ${localMount}";
+  #  };
-#      ExecStop = "${pkgs.fuse3}/bin/fusermount3 -u ${localMount}";
-#      Restart = "on-failure";
-#    };
-
-#    Install = {
-#      WantedBy = [ "default.target" ];
-#    };
-#  };
   # Optional: enable bash (or zsh, fish...)
-#  programs.bash.enable = true;
+  #  programs.bash.enable = true;
 
   # Optional: manage dotfiles via symlinks
-#  home.file = {
+  #  home.file = {
-#    ".tmux.conf".source = ./dotfiles/tmux.conf;
+  #    ".tmux.conf".source = ./dotfiles/tmux.conf;
-#    ".config/nvim/init.vim".source = ./dotfiles/init.vim;
+  #    ".config/nvim/init.vim".source = ./dotfiles/init.vim;
-#  };
+  #  };
 }

modules/common/set-locale.nix

@@ -1,4 +1,4 @@
-{ ... }:
+_:
 
 {
   i18n.defaultLocale = "en_AU.UTF-8";
@@ -15,4 +15,4 @@
     LC_TIME = "en_AU.UTF-8";
   };
 
-}
+}

modules/disko/linode.nix

@@ -0,0 +1,35 @@
+_:
+
+{
+  # Linode provisions and sizes these disks itself (via the Linode
+  # dashboard/API) before the OS ever boots, and presents them as whole,
+  # unpartitioned block devices — /dev/sda is the root filesystem directly,
+  # /dev/sdb is swap directly, no partition table on either. Nothing here
+  # should ever repartition or resize them:
+  #   - `destroy = false` skips each disk entirely during disko's destroy
+  #     stage (see disko's disk.destroy option) — no wipefs, ever.
+  #   - the filesystem content type's own create step only runs mkfs if the
+  #     device isn't already formatted (checked via `blkid`), so re-running
+  #     this against an already-provisioned Linode disk is a no-op.
+  disko.devices.disk = {
+    main = {
+      device = "/dev/sda";
+      destroy = false;
+
+      content = {
+        type = "filesystem";
+        format = "ext4";
+        mountpoint = "/";
+      };
+    };
+
+    swap = {
+      device = "/dev/sdb";
+      destroy = false;
+
+      content = {
+        type = "swap";
+      };
+    };
+  };
+}

modules/disko/proxmox.nix

@@ -1,4 +1,4 @@
-{ ... }:
+{ config, vars, ... }:
 
 {
   disko.devices = {
@@ -6,6 +6,16 @@
       type = "disk";
       device = "/dev/sda";
 
+      # Only used when building a standalone disk image directly (`nix build
+      # .#nixosConfigurations.<host>.config.system.build.diskoImagesScript`)
+      # rather than formatting a real device — see docs/proxmox-images.md.
+      # imageSize sets the .raw file's total size (root's "100%" below fills
+      # whatever's left after ESP + swap within it); imageName keeps each
+      # host's image distinctly named instead of every proxmox-* host
+      # producing an identical "main.raw".
+      imageSize = vars.proxmoxImageSize;
+      imageName = config.networking.hostName;
+
       content = {
         type = "gpt";
 
@@ -57,4 +67,4 @@
       };
     };
   };
-}
+}

modules/docker/docker-health-to-gotify.nix

@@ -1,4 +1,4 @@
-{ pkgs, ... }:
+{ pkgs, vars, ... }:
 
 {
   systemd.services.docker-health-to-gotify = {
@@ -7,9 +7,9 @@
     serviceConfig = {
       Type = "oneshot";
       # Run as root so it can read /etc/secrets and access docker socket
-     # User = "root";
+      # User = "root";
       #EnvironmentFile = "-/etc/secrets/docker-health-alert.env";
-      ExecStart = "${pkgs.bash}/bin/bash /home/nixos/docker/monitoring/gotify/docker-health-to-gotify.sh";
+      ExecStart = "${pkgs.bash}/bin/bash /home/${vars.primaryUser}/docker/monitoring/gotify/docker-health-to-gotify.sh";
       StandardOutput = "journal";
       StandardError = "journal";
     };
@@ -25,4 +25,4 @@
       Persistent = true;
     };
   };
-}
+}

modules/docker/enable-service.nix

@@ -1,23 +1,23 @@
 { pkgs, ... }:
 
 {
-    #  virtualisation.docker.enable = true;
+  #  virtualisation.docker.enable = true;
   virtualisation.docker = {
-  enable = true;
+    enable = true;
-  package = pkgs.docker;
+    package = pkgs.docker;
-#  listenOptions = [
+    #  listenOptions = [
-#  "unix:///var/run/docker.sock"
+    #  "unix:///var/run/docker.sock"
-#  "tcp://0.0.0.0:2375"
+    #  "tcp://0.0.0.0:2375"
-#];
+    #];
 
-#  daemon.settings = {
+    #  daemon.settings = {
-#    metrics-addr = "0.0.0.0:9323";
+    #    metrics-addr = "0.0.0.0:9323";
-#    experimental = true;
+    #    experimental = true;
-#  };
+    #  };
-};
+  };
 
-environment.systemPackages = with pkgs; [
+  environment.systemPackages = with pkgs; [
-  docker-compose
+    docker-compose
-  docker-buildx
+    docker-buildx
-];
+  ];
-}
+}

modules/docker/mount-data.nix

@@ -1,63 +1,65 @@
-{ config, lib, pkgs, ... }:
+{ config, lib, pkgs, vars, ... }:
 
 {
-  fileSystems."/mnt/docker/config" = {
+  fileSystems = {
-    device = "server:/tank/docker/config";
+    ${vars.nfsShares.dockerConfig.mountpoint} = {
-    fsType = "nfs";
+      device = "${vars.nfsServerHost}:${vars.storageRoot}/${vars.nfsShares.dockerConfig.subpath}";
+      fsType = "nfs";
 
-    options = [
+      options = [
-      "nfsvers=4.2"
+        "nfsvers=4.2"
-      "_netdev"
+        "_netdev"
-      "x-systemd.automount"
+        "x-systemd.automount"
-      "noatime"
+        "noatime"
-    ];
+      ];
-  };
+    };
 
-  fileSystems."/mnt/docker/databases" = {
+    ${vars.nfsShares.dockerDatabases.mountpoint} = {
-    device = "server:/tank/docker/databases";
+      device = "${vars.nfsServerHost}:${vars.storageRoot}/${vars.nfsShares.dockerDatabases.subpath}";
-    fsType = "nfs";
+      fsType = "nfs";
 
-    options = [
+      options = [
-      "nfsvers=4.2"
+        "nfsvers=4.2"
-      "_netdev"
+        "_netdev"
-      "x-systemd.automount"
+        "x-systemd.automount"
-      "noatime"
+        "noatime"
-    ];
+      ];
-  };
+    };
 
-  fileSystems."/mnt/docker/volumes" = {
+    ${vars.nfsShares.dockerVolumes.mountpoint} = {
-    device = "server:/tank/docker/volumes";
+      device = "${vars.nfsServerHost}:${vars.storageRoot}/${vars.nfsShares.dockerVolumes.subpath}";
-    fsType = "nfs";
+      fsType = "nfs";
 
-    options = [
+      options = [
-      "nfsvers=4.2"
+        "nfsvers=4.2"
-      "_netdev"
+        "_netdev"
-      "x-systemd.automount"
+        "x-systemd.automount"
-      "noatime"
+        "noatime"
-    ];
+      ];
-  };
+    };
 
- fileSystems."/mnt/nextcloud-data" = {
+    ${vars.nfsShares.nextcloudData.mountpoint} = {
-    device = "server:/tank/docker/nextcloud-data";
+      device = "${vars.nfsServerHost}:${vars.storageRoot}/${vars.nfsShares.nextcloudData.subpath}";
-    fsType = "nfs";
+      fsType = "nfs";
 
-    options = [
+      options = [
-      "nfsvers=4.2"
+        "nfsvers=4.2"
-      "_netdev"
+        "_netdev"
-      "x-systemd.automount"
+        "x-systemd.automount"
-      "noatime"
+        "noatime"
-    ];
+      ];
-  };
+    };
 
- fileSystems."/mnt/raspi-backup" = {
+    ${vars.nfsShares.raspiVolumes.mountpoint} = {
-    device = "server:/tank/raspi/volumes";
+      device = "${vars.nfsServerHost}:${vars.storageRoot}/${vars.nfsShares.raspiVolumes.subpath}";
-    fsType = "nfs";
+      fsType = "nfs";
 
-    options = [
+      options = [
-      "nfsvers=4.2"
+        "nfsvers=4.2"
-      "_netdev"
+        "_netdev"
-      "x-systemd.automount"
+        "x-systemd.automount"
-      "noatime"
+        "noatime"
-    ];
+      ];
+    };
   };
 }

modules/docker/nextcloud-cron-job.nix

@@ -0,0 +1,22 @@
+{ pkgs, vars, ... }:
+
+{
+  # Create nextcloud cron scheduled task
+  systemd.services.nextcloud = {
+    description = "Nextcloud scheduled task";
+    script = ''${pkgs.bash}/bin/bash ~/docker/services-up.sh --profile nextcloud exec -u 33 nextcloud-webapp php ./cron.php'';
+    serviceConfig = {
+      Type = "oneshot";
+      User = vars.primaryUser;
+    };
+    path = with pkgs; [ docker docker-compose ];
+  };
+
+  systemd.timers.nextcloud = {
+    wantedBy = [ "timers.target" ];
+    timerConfig = {
+      OnCalendar = "*:0/5";
+      Persistent = true;
+    };
+  };
+}

modules/hardware-configuration/vm/linode.nix

@@ -5,36 +5,39 @@
 
 {
   imports =
-    [ (modulesPath + "/profiles/qemu-guest.nix")
+    [
+      (modulesPath + "/profiles/qemu-guest.nix")
     ];
 
-  boot.initrd.availableKernelModules = [ "virtio_pci" "virtio_scsi" "ahci" "sd_mod" ];
+  boot = {
-  boot.initrd.kernelModules = [ ];
+    initrd.availableKernelModules = [ "virtio_pci" "virtio_scsi" "ahci" "sd_mod" ];
-  boot.kernelModules = [ ];
+    initrd.kernelModules = [ ];
-  boot.extraModulePackages = [ ];
+    kernelModules = [ ];
-  boot.loader.grub.device = "/dev/sda";
+    extraModulePackages = [ ];
 
-  fileSystems."/" =
+    # Enable LISH
-    { device = "/dev/sda";
+    kernelParams = [ "console=ttyS0,19200n8" ];
-      fsType = "ext4";
+
+    loader = {
+      grub = {
+        device = "/dev/sda";
+        extraConfig = ''
+          serial --speed=19200 --unit=0 --word=8 --parity=no --stop=1;
+          terminal_input serial;
+          terminal_output serial;
+        '';
+        forceInstall = true;
+        # device = "nodev";
+      };
+      timeout = 10;
     };
+  };
 
-  swapDevices =
+  # fileSystems."/" and swapDevices are now owned by disko
-    [ { device = "/dev/sdb"; }
+  # (../disko/linode.nix, imported from ../platforms/linode.nix) — same
-    ];
+  # /dev/sda root + /dev/sdb swap layout, declared there instead so disko's
-
+  # (idempotent, non-destructive — see that file) format/mount scripts stay
-# Enable LISH
+  # in sync with what NixOS actually mounts.
-boot.kernelParams = [ "console=ttyS0,19200n8" ];
-boot.loader.grub.extraConfig = ''
-  serial --speed=19200 --unit=0 --word=8 --parity=no --stop=1;
-  terminal_input serial;
-  terminal_output serial;
-'';
-
-boot.loader.grub.forceInstall = true;
-# boot.loader.grub.device = "nodev";
-boot.loader.timeout = 10;
-
 
   nixpkgs.hostPlatform = lib.mkDefault "x86_64-linux";
 }

modules/hardware-configuration/vm/proxmox.nix

@@ -5,13 +5,16 @@
 
 {
   imports =
-    [ (modulesPath + "/profiles/qemu-guest.nix")
+    [
+      (modulesPath + "/profiles/qemu-guest.nix")
     ];
 
-  boot.initrd.availableKernelModules = [ "ata_piix" "uhci_hcd" "virtio_pci" "virtio_scsi" "sd_mod" "sr_mod" ];
+  boot = {
-  boot.initrd.kernelModules = [ ];
+    initrd.availableKernelModules = [ "ata_piix" "uhci_hcd" "virtio_pci" "virtio_scsi" "sd_mod" "sr_mod" ];
-  boot.kernelModules = [ "kvm-amd" ];
+    initrd.kernelModules = [ ];
-  boot.extraModulePackages = [ ];
+    kernelModules = [ "kvm-amd" ];
+    extraModulePackages = [ ];
+  };
   # boot.loader.grub.device = "/dev/sda2"; # or "nodev" for efi only
 
   # fileSystems."/" =

modules/installer/common.nix

@@ -0,0 +1,240 @@
+{ pkgs, lib, vars, ... }:
+
+{
+  imports = [
+    ./host-keys.nix
+  ];
+
+  networking.useDHCP = lib.mkDefault true;
+
+  # Recommended over the true default (bypasses ZFS's own import safeguards)
+  # per the option's own docs. This installer environment has no ZFS pools
+  # of its own to import, so this is a no-op here — just silences the
+  # eval-time warning, matching modules/common/configuration.nix.
+  boot.zfs.forceImportRoot = false;
+
+  time.timeZone = vars.timeZone;
+
+  # Without this, the installer only ever sees cache.nixos.org, which
+  # doesn't carry sops-install-secrets (it's built straight from the
+  # sops-nix flake's own Go source, not part of nixpkgs) — every install
+  # would otherwise compile it from scratch, which is what ran an 8GB LXC
+  # container's disk out of space. Push a built copy to nix-cache once
+  # (from a machine with real disk headroom) and every future install,
+  # of any type, fetches instead of rebuilding.
+  nix.settings = {
+    substituters = [
+      "http://nix-cache"
+      "https://cache.nixos.org/"
+    ];
+    trusted-public-keys = [
+      "cache.local-1:usoWYanY3Kpq2+kDIS2nhWoLZiRxanmdysdzqCFBHW4="
+      "cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY="
+    ];
+  };
+
+  environment = {
+    systemPackages = with pkgs; [
+      git
+      curl
+      jq
+      parted
+      e2fsprogs
+      btrfs-progs
+      util-linux
+      disko
+    ];
+
+    # Write auto-install script to /root
+    etc."auto-install.sh" = {
+      text = ''
+            #!/run/current-system/sw/bin/bash
+            set -eux
+
+            set -euo pipefail
+
+        export FLAKE_BASE_URL="git+https://${vars.lanDomain}/beatzaplenty/nixos.git"
+
+        echo "Fetching available NixOS hosts from flake..."
+        # Two categories deliberately excluded from the menu:
+        #   lxc-*     — these build a config.system.build.tarball meant for
+        #               `pct restore` on Proxmox directly, not an install.
+        #               Running nixos-install against one here would
+        #               bind-mount / onto /mnt and then refuse to touch the
+        #               filesystem it's currently running on — see
+        #               docs/auto-installer.md.
+        #   installer — this *is* the installer image's own flake target,
+        #               not a deployable host; "installing" it means
+        #               nixos-install-ing a copy of the installer into
+        #               itself.
+        mapfile -t options < <(
+          nix eval --json --no-use-registries --no-accept-flake-config --extra-experimental-features "flakes nix-command" \
+            "''${FLAKE_BASE_URL}#nixosConfigurations" \
+            --apply builtins.attrNames \
+          | jq -r '.[]
+              | select(startswith("lxc-") | not)
+              | select(. != "installer")'
+        )
+
+        if [[ ''${#options[@]} -eq 0 ]]; then
+          echo "ERROR: No NixOS hosts found in ''${FLAKE_BASE_URL}#nixosConfigurations" >&2
+          exit 1
+        fi
+
+        echo "Note: lxc-* targets aren't installed this way — build them with"
+        echo "  nix build .#nixosConfigurations.<name>.config.system.build.tarball"
+        echo "and 'pct restore' the result on Proxmox directly. See docs/auto-installer.md."
+
+        echo "Choose the flake profile to install:"
+        select choice in "''${options[@]}"; do
+          if [[ -n "$choice" ]]; then
+            echo "You selected: $choice"
+            break
+          else
+            echo "Invalid selection. Try again."
+          fi
+        done
+
+        echo "Starting install with flake: ''${FLAKE_BASE_URL}#''${choice}"
+
+        # Optional: confirm before proceeding
+        read -rp "Proceed with installation? (y/N): " confirm
+        if [[ ! "$confirm" =~ ^[Yy]$ ]]; then
+          echo "Aborted."
+          exit 1
+        fi
+
+        # A nix-cache host is *the* substituter/remote-builder for every other
+        # host once installed (its own config explicitly excludes itself from
+        # using either — see buildType != "nix-cache" in the nixos flake.nix).
+        # Installing one shouldn't depend on a nix-cache substituter either,
+        # for the same reason — plus in practice "nix-cache" only resolves over
+        # Tailscale, which a fresh installer environment was never connected to
+        # anyway, so it's dead weight even for non-nix-cache installs until
+        # that's sorted out. Override it away here specifically for nix-cache
+        # targets to keep install-time behaviour consistent with run-time.
+        nix_extra_opts=()
+        if [[ "''${choice}" == *-nix-cache ]]; then
+            echo "Installing a nix-cache host — skipping the nix-cache substituter."
+            nix_extra_opts+=(--option substituters "https://cache.nixos.org/")
+        fi
+
+        # Every host reachable through this menu has a Disko config (lxc-*
+        # is filtered out above, and is the only category that doesn't —
+        # see docs/auto-installer.md), so this can run unconditionally: no
+        # need to probe the flake first and branch on whether Disko applies.
+        disko --mode destroy,format,mount \
+            --flake "''${FLAKE_BASE_URL}#''${choice}" "''${nix_extra_opts[@]}" --yes-wipe-all-disks
+
+        # sops-nix derives this host's decryption key from its own SSH host key
+        # at *activation* time, which runs before systemd would otherwise
+        # generate one on first boot. Without pre-seeding it here, secrets
+        # (including the login password) fail to decrypt on first boot.
+        # Generate the key with scripts/prepare-host-key.sh first.
+        #
+        # Two places a key can come from, checked in order:
+        #   /etc/host-keys  — baked into this image at build time (see
+        #                      modules/installer/host-keys.nix; only present
+        #                      if built with NIXOS_HOST_KEYS_DIR set)
+        #   /root/host-keys — scp'd in manually after boot (older fallback,
+        #                      still supported for images built without keys)
+        mkdir -p /root/host-keys
+        if [[ -f "/etc/host-keys/''${choice}_ssh_host_ed25519_key" ]]; then
+            echo "Found baked-in SSH host key for ''${choice}, installing to target..."
+            install -D -m 0600 "/etc/host-keys/''${choice}_ssh_host_ed25519_key" /mnt/etc/ssh/ssh_host_ed25519_key
+            install -D -m 0644 "/etc/host-keys/''${choice}_ssh_host_ed25519_key.pub" /mnt/etc/ssh/ssh_host_ed25519_key.pub
+        elif [[ -f "/root/host-keys/''${choice}_ssh_host_ed25519_key" ]]; then
+            echo "Found pre-seeded SSH host key for ''${choice}, installing to target..."
+            install -D -m 0600 "/root/host-keys/''${choice}_ssh_host_ed25519_key" /mnt/etc/ssh/ssh_host_ed25519_key
+            install -D -m 0644 "/root/host-keys/''${choice}_ssh_host_ed25519_key.pub" /mnt/etc/ssh/ssh_host_ed25519_key.pub
+        else
+            echo "WARNING: no SSH host key found for ''${choice} (checked /etc/host-keys and /root/host-keys)"
+            echo "sops-nix secrets (including the login password) will NOT decrypt on first boot."
+            echo "Run scripts/prepare-host-key.sh for host ''${choice} on your admin workstation first,"
+            echo "then either rebuild this image with NIXOS_HOST_KEYS_DIR set, or scp the result to"
+            echo "/root/host-keys/ on this machine."
+            read -rp "Continue without a pre-seeded key anyway? (y/N): " skip_key
+            if [[ ! "$skip_key" =~ ^[Yy]$ ]]; then
+                echo "Aborted."
+                exit 1
+            fi
+        fi
+
+        mkdir -p /mnt/install-tmp
+        export TMPDIR=/mnt/install-tmp
+
+        nixos-install \
+            --flake "''${FLAKE_BASE_URL}#''${choice}" \
+            "''${nix_extra_opts[@]}" \
+            --no-root-password
+
+
+            rm -rf /mnt/install-tmp
+            # Redundant copy of the host's private key — the real one is now at
+            # /etc/ssh/ssh_host_ed25519_key. Nothing NixOS-managed ever cleans this
+            # up on its own since it was written imperatively, not declaratively.
+            rm -rf /root/host-keys
+            sleep 10
+            reboot
+      '';
+
+      mode = "0755";
+    };
+  };
+
+  programs.git.enable = true;
+
+  # Run the installer on first login. Previously this copied an /etc file
+  # into the nixos user's ~/.bash_profile via an activation script that
+  # got dropped in a refactor (and only ever worked for that one user
+  # anyway) — loginShellInit is NixOS's native hook for this, applies to
+  # any user's login shell (root included), and needs no home-directory
+  # file-copying/chown.
+  programs.bash.loginShellInit = ''
+    if [ -n "$PS1" ] && [ ! -e "$HOME/.auto_install_ran" ]; then
+      sudo /etc/auto-install.sh
+      touch "$HOME/.auto_install_ran"
+    fi
+  '';
+
+  services.openssh.enable = true;
+
+  services.openssh.settings = {
+    PermitRootLogin = "yes";
+    PasswordAuthentication = true;
+  };
+
+  # nixpkgs' own installer profile (profiles/installation-device.nix, pulled
+  # in via installation-cd-minimal.nix) sets initialHashedPassword = "" for
+  # both users — its own passwordless-login convention for install media.
+  # That's a second, non-null password option alongside our hashedPassword
+  # below, which NixOS warns about as ambiguous precedence. Force it null
+  # rather than adopting passwordless login: this image now also boots over
+  # LAN PXE with PasswordAuthentication enabled, so passwordless root SSH
+  # would be reachable by anyone on the LAN, not just local console.
+  users.users.root = {
+    hashedPassword =
+      "$6$Kwv9KAyvcurAViQF$H4.u3feqGE7lVoNgkFXhE3n2Pmo//9JYDTCz8ifrVHBxPjwa1xMby7tEZ8Bpt5MXs9Rkx6/YbZWxs5CpH0s/70";
+    initialHashedPassword = lib.mkForce null;
+  };
+
+  users.users.${vars.primaryUser} = {
+    isNormalUser = true;
+
+    extraGroups = [
+      "wheel"
+    ];
+
+    shell = pkgs.bashInteractive;
+
+    hashedPassword =
+      "$6$Kwv9KAyvcurAViQF$H4.u3feqGE7lVoNgkFXhE3n2Pmo//9JYDTCz8ifrVHBxPjwa1xMby7tEZ8Bpt5MXs9Rkx6/YbZWxs5CpH0s/70";
+    initialHashedPassword = lib.mkForce null;
+
+    openssh.authorizedKeys.keys = [
+      vars.adminSshKey
+    ];
+  };
+
+  system.stateVersion = "26.05";
+}

modules/installer/host-keys.nix

@@ -0,0 +1,37 @@
+{ lib, ... }:
+
+let
+  # host-keys/ is gitignored (private key material must never be committed),
+  # which means flakes' git-filtered source tree can never see it via a
+  # normal relative path — referencing it at all requires stepping outside
+  # pure evaluation. builtins.getEnv is neutered to "" under normal
+  # `nix build`/`nix eval` (no error, just empty), so this whole module is a
+  # silent no-op unless the operator explicitly opts in with --impure and
+  # the env var set — safe by default, including in CI.
+  #
+  #   NIXOS_HOST_KEYS_DIR=$(pwd)/host-keys nix build .#iso --impure
+  #
+  # See docs/auto-installer.md.
+  hostKeysDirStr = builtins.getEnv "NIXOS_HOST_KEYS_DIR";
+  hasHostKeysDir = hostKeysDirStr != "" && builtins.pathExists hostKeysDirStr;
+  hostKeysDir = /. + hostKeysDirStr;
+
+  keyFileNames =
+    if hasHostKeysDir
+    then
+      lib.filter
+        (name: lib.hasSuffix "_ssh_host_ed25519_key" name || lib.hasSuffix "_ssh_host_ed25519_key.pub" name)
+        (lib.attrNames (builtins.readDir hostKeysDir))
+    else [ ];
+in
+{
+  environment.etc = lib.listToAttrs (map
+    (name: {
+      name = "host-keys/${name}";
+      value = {
+        source = hostKeysDir + "/${name}";
+        mode = "0400";
+      };
+    })
+    keyFileNames);
+}

modules/installer/iso.nix

@@ -0,0 +1,8 @@
+{ modulesPath, ... }:
+
+{
+  imports = [
+    "${modulesPath}/installer/cd-dvd/installation-cd-minimal.nix"
+    ./common.nix
+  ];
+}

modules/nix-cache/client.nix

@@ -1,9 +1,9 @@
-{ ... }:
+{ vars, ... }:
 
 {
   nix.settings = {
     substituters = [
-      "http://nix-cache"
+      "http://${vars.nixCacheHost}"
       "https://cache.nixos.org/"
     ];
     trusted-public-keys = [

modules/nix-cache/remote-builder-client.nix

@@ -0,0 +1,36 @@
+{ pkgs, vars, ... }:
+
+{
+  # Install the remote builder key on each client host (do not commit private keys):
+  #   sudo install -d -m 0700 /root/.ssh
+  #   sudo install -m 0600 ./nixremote /root/.ssh/nixremote
+  #   sudo ssh -i /root/.ssh/nixremote nixremote@nix-cache nix-store --version
+  # Trust nix-cache's SSH host key declaratively so the nix-daemon (root)
+  # can connect the first time without a manual ssh-keyscan/known_hosts
+  # step on every new client.
+  programs.ssh.knownHosts.${vars.nixCacheHost} = {
+    hostNames = [ vars.nixCacheHost ];
+    publicKey = vars.nixCacheHostKey;
+  };
+
+  nix = {
+    distributedBuilds = true;
+
+    buildMachines = [
+      {
+        hostName = vars.nixCacheHost;
+        sshUser = vars.remoteBuilderUser;
+        sshKey = "/root/.ssh/${vars.remoteBuilderUser}";
+        inherit (pkgs.stdenv.hostPlatform) system;
+        maxJobs = 4;
+        speedFactor = 2;
+        supportedFeatures = [ "nixos-test" "benchmark" "big-parallel" "kvm" ];
+      }
+    ];
+
+    settings = {
+      builders-use-substitutes = true;
+      max-jobs = "auto";
+    };
+  };
+}

modules/nix-cache/server.nix

@@ -1,54 +1,53 @@
-{ config, pkgs, ... }:
+{ config, pkgs, vars, ... }:
 
 {
-  # Generate the binary cache key pair on the nix-cache host:
+  # nix-serve's signing key has to be the *same* key on every host that
-  #   sudo install -d -m 0700 /etc/nix
+  # ever plays the nix-cache role -- modules/nix-cache/client.nix hardcodes
-  #   sudo nix-store --generate-binary-cache-key nix-cache-1 \
+  # every client's trust in one specific public key ("cache.local-1:..."),
-  #     /etc/nix/cache-priv.pem \
+  # so a freshly self-generated key here wouldn't be trusted by anyone.
-  #     /etc/nix/cache-pub.pem
+  # Managed via sops-nix like every other secret in this repo instead of
-  #   sudo chmod 0600 /etc/nix/cache-priv.pem
+  # the old manual `nix-store --generate-binary-cache-key` step -- see
-  #   sudo chmod 0644 /etc/nix/cache-pub.pem
+  # "Binary cache signing key" in docs/nix-cache.md for how to add/rotate
-  #   cat /etc/nix/cache-pub.pem
+  # the value in secrets/nix-cache.yaml.
-  services.nix-serve = {
+  sops.secrets."cache-priv-key".sopsFile = ../../secrets/nix-cache.yaml;
-    enable = true;
-    secretKeyFile = "/etc/nix/cache-priv.pem";
-  };
 
-  services.nginx = {
+  services = {
-    enable = true;
+    nix-serve = {
-    recommendedProxySettings = true;
+      enable = true;
-    virtualHosts."nix-cache" = {
+      secretKeyFile = config.sops.secrets."cache-priv-key".path;
-      locations."/" = {
+    };
-        proxyPass = "http://${config.services.nix-serve.bindAddress}:${toString config.services.nix-serve.port}";
+
+    nginx = {
+      enable = true;
+      recommendedProxySettings = true;
+      virtualHosts.${vars.nixCacheHost} = {
+        locations."/" = {
+          proxyPass = "http://${config.services.nix-serve.bindAddress}:${toString config.services.nix-serve.port}";
+        };
       };
     };
+
+    openssh.enable = true;
   };
 
-  networking.firewall.allowedTCPPorts = [ 80 ];
+  networking.firewall.allowedTCPPorts = [ vars.ports.nixCacheHttp ];
 
-  users.groups.nixremote = {};
+  users.groups.${vars.remoteBuilderUser} = { };
 
-  users.users.nixremote = {
+  users.users.${vars.remoteBuilderUser} = {
     isSystemUser = true;
-    group = "nixremote";
+    group = vars.remoteBuilderUser;
     createHome = true;
     home = "/var/lib/nixremote";
     shell = pkgs.bashInteractive;
-    # Provide remote builder public keys here (safe to commit public keys only):
+    # Client public keys allowed to use this host as a remote builder —
-    # openssh.authorizedKeys.keys = [ "ssh-ed25519 AAAA... client@host" ];
+    # single source of truth is vars.remoteBuilderAuthorizedKeys (safe to
-    #
+    # commit public keys only).
-    # Avoid absolute keyFiles paths here because they break pure flake evaluation.
+    openssh.authorizedKeys.keys = vars.remoteBuilderAuthorizedKeys;
-    openssh.authorizedKeys.keys = ["ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIFDEA1S2ikpObREgbP5uVBWMxIOGbY8B+Wx7VTZK1m6t root@server"
-					"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPAYIT9ormlmxZ0SziyDQaUntnKI8HK9/s3Qac1ZKjP2 root@docker" 
-					"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKKKzoEPl/ZW9KBRHBcp6/ThOngGpwMv5EhkTlgC4aDf root@nixos"
-					"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIGtOWOCS+ImHc7NehguoyD7PbonGosKMZqc9+QR3v/h root@nixos"
-					"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHxXTQxFnArK5HXG7czeoybZebCGfxpUdusJkPn+BCSp root@server"];
   };
 
-  services.openssh.enable = true;
-
   nix.settings = {
-    trusted-users = [ "root" "nixremote" ];
+    trusted-users = [ "root" vars.remoteBuilderUser ];
     experimental-features = [ "nix-command" "flakes" ];
     auto-optimise-store = true;
     builders-use-substitutes = true;
@@ -57,6 +56,6 @@
   nix.gc = {
     automatic = true;
     dates = "weekly";
-    options = "--delete-older-than 30d";
+    options = "--delete-older-than ${vars.nixCacheGcMaxAge}";
   };
 }

modules/platforms/linode.nix

@@ -3,6 +3,7 @@
 {
   imports = [
     ../hardware-configuration/vm/linode.nix
+    ../disko/linode.nix
   ];
 
   networking = {

modules/platforms/lxc.nix

@@ -1,8 +1,148 @@
-{ ... }:
+{ lib, modulesPath, flakeTarget, ... }:
 
+let
+  # Bakes this exact flake target's pre-generated SSH host key straight
+  # into /etc/ssh/ -- mirrors modules/installer/host-keys.nix's
+  # builtins.getEnv pattern (impure and empty under normal `nix
+  # build`/`nix eval`, so this is a no-op unless explicitly opted into
+  # with NIXOS_HOST_KEYS_DIR=... --impure), but places the key directly
+  # rather than staging it under /etc/host-keys/ for a later manual copy
+  # -- this is the whole system for a `lxc-*` host, built straight to a
+  # pct-restorable tarball with no install step, so there's no later copy
+  # step to stage for.
+  #
+  # Without this, config.system.build.tarball's built-in system just
+  # generates a fresh host key at first boot like any other host would --
+  # but sops-nix derives its decryption key from *this* file, and
+  # .sops.yaml only trusts whatever key scripts/sync-host-keys.sh already
+  # registered for this exact target name. A freshly-generated key can
+  # never match that, so every secret (including this host's own login)
+  # permanently fails to decrypt. Confirmed live: sops-install-secrets
+  # errored with "Error getting data key: 0 successful groups required,
+  # got 0" -- the container's actual host key's age fingerprint didn't
+  # match the one registered in .sops.yaml at all.
+  hostKeysDirStr = builtins.getEnv "NIXOS_HOST_KEYS_DIR";
+  hasHostKeysDir = hostKeysDirStr != "" && builtins.pathExists hostKeysDirStr;
+  hostKeysDir = /. + hostKeysDirStr;
+
+  # flakeTarget ("${platform}-${buildType}") comes in via specialArgs from
+  # flake.nix's mkTarget -- exactly the name scripts/sync-host-keys.sh
+  # registers keys under. Deliberately not read back from
+  # config.environment.etc."flake-target" (which is set to the same value)
+  # -- this module also *contributes* to environment.etc below, and a
+  # module reading the merged value of an option it's still defining is a
+  # circular dependency (confirmed: "infinite recursion encountered").
+  privKeyFile = hostKeysDir + "/${flakeTarget}_ssh_host_ed25519_key";
+  pubKeyFile = hostKeysDir + "/${flakeTarget}_ssh_host_ed25519_key.pub";
+  hasKeyForThisTarget =
+    hasHostKeysDir
+    && builtins.pathExists privKeyFile
+    && builtins.pathExists pubKeyFile;
+in
 {
-  boot.isContainer = true;
+  # LXC containers share the host kernel — Proxmox starts them by exec'ing
+  # /sbin/init directly, no bootloader/initrd involved — and Proxmox has its
+  # own container hostname/network provisioning outside Nix. nixpkgs' own
+  # virtualisation/proxmox-lxc.nix module already handles all of this
+  # correctly (boot.isContainer, loader.initScript, systemd-networkd) and,
+  # critically, provides config.system.build.tarball — a directly
+  # `pct restore`-able container image, no nixos-install/bind-mount needed
+  # (nixos-install refuses to touch the filesystem it's currently running
+  # on, which is exactly what bind-mounting / onto /mnt for an installer
+  # LXC container does).
+  imports = [
+    (modulesPath + "/virtualisation/proxmox-lxc.nix")
+  ];
 
-  boot.loader.grub.enable = false;
+  proxmoxLXC = {
-  boot.loader.systemd-boot.enable = false;
+    # host.nix declares each host's real hostname (networking.hostName);
+    # keep that instead of letting Proxmox's ambient container config win.
+    manageHostName = true;
+    # Unprivileged matches how these containers are actually created.
+    privileged = false;
+  };
+
+  boot.loader = {
+    grub.enable = false;
+    systemd-boot.enable = false;
+  };
+
+  # NetworkManager depends on a running udevd to enumerate/classify devices,
+  # which boot.isContainer disables (see nixpkgs' container-config.nix) —
+  # that's what broke DHCP-hostname registration in Pi-hole. The imported
+  # proxmox-lxc.nix module already switches networking to systemd-networkd
+  # for the same reason; it just doesn't disable NetworkManager itself,
+  # which modules/common/configuration.nix enables for every host.
+  networking.networkmanager.enable = lib.mkForce false;
+
+  environment.etc = lib.mkIf hasKeyForThisTarget {
+    "ssh/ssh_host_ed25519_key" = {
+      source = privKeyFile;
+      mode = "0600";
+    };
+    "ssh/ssh_host_ed25519_key.pub" = {
+      source = pubKeyFile;
+      mode = "0644";
+    };
+  };
+
+  # virtualisation/proxmox-lxc.nix (imported above) registers the Nix
+  # store DB via a systemd service (register-nix-paths) -- it never runs
+  # an activation script at all. Confirmed live this means neither
+  # sops-nix's "for users" secrets (password hashes -- installed by the
+  # activation script itself, not a systemd service, since they need to
+  # exist *before* user creation) nor the user-creation step that
+  # consumes them ever run on a real lxc-* boot. Regular secrets
+  # (nix-serve's key, beszel's token, etc.) work anyway because sops-nix
+  # provides its own systemd service for those.
+  #
+  # A systemd service, not boot.postBootCommands: tried that first (it's
+  # a genuine, generally-invoked hook -- nixos/modules/system/boot/stage-2-init.sh,
+  # which becomes this container's actual /sbin/init, unconditionally
+  # runs it) but switch-to-configuration behaves differently that early in
+  # boot (raw stage-2-init.sh, before systemd itself has even started) --
+  # confirmed live it silently failed to rewrite /etc/shadow from there
+  # even in "test" mode, despite the exact same command working reliably
+  # every time when run post-boot (i.e. as a normal systemd service, which
+  # is what this is). Not fully root-caused why the early context
+  # specifically breaks it; a real systemd service sidesteps needing to.
+  #
+  # /etc/shadow already has PLACEHOLDER entries for every declared user
+  # baked in at build time (part of constructing the system closure).
+  # update-users-groups.pl deliberately never overwrites an *existing*
+  # shadow entry -- a correct safety property in general (don't clobber a
+  # real user's real password on a config rebuild) -- but on a genuine
+  # first boot that only means the real hashedPasswordFile-derived hash
+  # never gets the chance to be applied either, since the placeholder is
+  # already "seen". Safe to clear here specifically: there is no real
+  # password yet to protect on a first boot.
+  #
+  # "test" mode, not "boot": confirmed live "boot" mode aborts partway
+  # through (before rewriting /etc/shadow) on a warning that "/boot" is on
+  # a different filesystem -- a real check for a host with a bootloader to
+  # update, meaningless for a container that has none
+  # (boot.loader.{grub,systemd-boot}.enable are both false above), but it
+  # still aborts the script. "test" runs every activation step without
+  # touching boot-loader state at all.
+  #
+  # ConditionPathExists (systemd-native, not a bash-level check) means
+  # this only ever runs once, on the genuine first boot -- systemd itself
+  # skips even starting it on every later boot once the marker exists.
+  # switch-to-configuration is otherwise the operator's call per this
+  # repo's own safety rules, not something to run on every boot.
+  systemd.services.nixos-lxc-first-boot-activate = {
+    description = "Complete first-boot NixOS activation (users, secrets) for this LXC container";
+    wantedBy = [ "multi-user.target" ];
+    unitConfig.ConditionPathExists = "!/var/lib/nixos-lxc-first-boot-activated";
+    serviceConfig = {
+      Type = "oneshot";
+      RemainAfterExit = true;
+    };
+    script = ''
+      rm -f /etc/shadow
+      /run/current-system/bin/switch-to-configuration test
+      mkdir -p /var/lib
+      touch /var/lib/nixos-lxc-first-boot-activated
+    '';
+  };
 }

modules/pxe-boot/stage-installer-artifacts.nix

@@ -0,0 +1,23 @@
+{ netbootSystem, ... }:
+
+let
+  # config.system.build.kernel and .netbootRamdisk are directories, not the
+  # files themselves — nixpkgs' own system.build.kexecTree does the same
+  # ${...}/<file> dereference for the same reason.
+  inherit (netbootSystem.config.system.boot.loader) kernelFile;
+in
+{
+  # Builds this flake's own installer netboot image (the same one
+  # `nix build .#pxe` produces) and stages it where menu.ipxe's :nixos
+  # entry expects it, so the pxe-boot host is self-contained — no manual
+  # operator step to populate /srv/pxe/http/nixos after deploy.
+  systemd.tmpfiles.rules = [
+    # Declared here too (not just in build-types/pxe-boot.nix) so this
+    # module's C+ rules don't depend on cross-module list-merge ordering —
+    # tmpfiles' C type needs the target directory to already exist.
+    "d /srv/pxe/http/nixos 0755 root root -"
+    "C+ /srv/pxe/http/nixos/${kernelFile} 0644 root root - ${netbootSystem.config.system.build.kernel}/${kernelFile}"
+    "C+ /srv/pxe/http/nixos/initrd 0644 root root - ${netbootSystem.config.system.build.netbootRamdisk}/initrd"
+    "C+ /srv/pxe/http/nixos/netboot.ipxe 0644 root root - ${netbootSystem.config.system.build.netbootIpxeScript}/netboot.ipxe"
+  ];
+}

modules/raspi/mount-data.nix

@@ -1,26 +1,26 @@
-{ ... }:
+{ vars, ... }:
 
 {
-fileSystems."/mnt/raspi" = {
+  fileSystems.${vars.raspiMountpoint} = {
-  device = "raspberrypi.tail13f623.ts.net:/home/raspi/raspi";
+    device = "${vars.raspberryPiHost}.${vars.tailnetDomain}:${vars.raspiNfsPath}";
-  fsType = "nfs4";
+    fsType = "nfs4";
-  options = [
+    options = [
-    "nofail"
+      "nofail"
-    "_netdev"
+      "_netdev"
-    "noatime"
+      "noatime"
 
-    # Don't mount until first access
+      # Don't mount until first access
-    "x-systemd.automount"
+      "x-systemd.automount"
 
-    # Unmount after 10 min idle
+      # Unmount after 10 min idle
-    "x-systemd.idle-timeout=600"
+      "x-systemd.idle-timeout=600"
 
-    # Give the Pi/Tailscale a little time to appear
+      # Give the Pi/Tailscale a little time to appear
-    "x-systemd.device-timeout=10s"
+      "x-systemd.device-timeout=10s"
 
-    # Explicitly use NFSv4.2 if supported
+      # Explicitly use NFSv4.2 if supported
-    "nfsvers=4.2"
+      "nfsvers=4.2"
-  ];
+    ];
-};
+  };
 
-}
+}

modules/remote-builder-client.nix

@@ -1,26 +0,0 @@
-{ pkgs, ... }:
-
-{
-  # Install the remote builder key on each client host (do not commit private keys):
-  #   sudo install -d -m 0700 /root/.ssh
-  #   sudo install -m 0600 ./nixremote /root/.ssh/nixremote
-  #   sudo ssh -i /root/.ssh/nixremote nixremote@nix-cache nix-store --version
-  nix.distributedBuilds = true;
-
-  nix.buildMachines = [
-    {
-      hostName = "nix-cache";
-      sshUser = "nixremote";
-      sshKey = "/root/.ssh/nixremote";
-      system = pkgs.stdenv.hostPlatform.system;
-      maxJobs = 4;
-      speedFactor = 2;
-      supportedFeatures = [ "nixos-test" "benchmark" "big-parallel" "kvm" ];
-    }
-  ];
-
-  nix.settings = {
-    builders-use-substitutes = true;
-    max-jobs = "auto";
-  };
-}

modules/rotate-traefik-logs.nix

@@ -1,20 +0,0 @@
-{ ... }:
-
-{
-      services.logrotate = {
-    enable = true;
-
-    settings = {
-      "/mnt/docker/volumes/traefik-data/logs/*.log" = {
-        daily = true;
-        size = "100M";
-        rotate = 20;
-        compress = true;
-        missingok = true;
-        notifempty = true;
-        copytruncate = true;
-      };
-
-     };
-  };
-}

modules/services/enable-rpcbind.nix

@@ -1,5 +1,5 @@
- { ... }:
+_:
- 
+
- {
+{
- services.rpcbind.enable = true;
+  services.rpcbind.enable = true;
- }
+}

modules/services/nextcloud-cron-job.nix

@@ -1,22 +0,0 @@
-{ pkgs, ... }:
-
-{
-# Create nextcloud cron scheduled task
-systemd.services.nextcloud = {
-  description = "Nextcloud scheduled task";
-  script = ''${pkgs.bash}/bin/bash ~/docker/services-up.sh --profile nextcloud exec -u 33 nextcloud-webapp php ./cron.php'';
-  serviceConfig = {
-    Type = "oneshot";
-    User = "nixos";
-  };
-  path = with pkgs; [ docker docker-compose ];
-};
-
-systemd.timers.nextcloud = {
-  wantedBy = [ "timers.target" ];
-  timerConfig = {
-    OnCalendar = "*:0/5";
-    Persistent = true;
-  };
-};
-}

modules/services/zfs/auto-mount-volumes.nix

@@ -1,12 +1,12 @@
 { pkgs, boot, ... }:
 
 {
-boot.postBootCommands = ''
+  boot.postBootCommands = ''
-  echo "=== STARTING ZPOOL IMPORT ==="
+    echo "=== STARTING ZPOOL IMPORT ==="
-  ${pkgs.zfs_unstable}/bin/zpool import -a -N -d /dev/disk/by-path
+    ${pkgs.zfs_unstable}/bin/zpool import -a -N -d /dev/disk/by-path
-  ${pkgs.zfs_unstable}/bin/zpool status
+    ${pkgs.zfs_unstable}/bin/zpool status
-  ${pkgs.zfs_unstable}/bin/zfs mount -a
+    ${pkgs.zfs_unstable}/bin/zfs mount -a
-  ${pkgs.zfs_unstable}/bin/zfs list
+    ${pkgs.zfs_unstable}/bin/zfs list
-    echo "=== ZPOOL IMPORT COMPLETE ==="
+      echo "=== ZPOOL IMPORT COMPLETE ==="
-'';
+  '';
- }
+}

modules/services/zfs/enable-service.nix

@@ -1,16 +1,21 @@
 { pkgs, ... }:
 
- {
+{
-boot.supportedFilesystems = [ "zfs" ];
+  boot = {
-  boot.zfs.forceImportRoot = false;
+    supportedFilesystems = [ "zfs" ];
-  boot.zfs.package = pkgs.zfs_unstable;
+    zfs = {
-      services.zfs = {
+      forceImportRoot = false;
+      package = pkgs.zfs_unstable;
+      devNodes = "/dev/disk/by-id";
+    };
+  };
+
+  services.zfs = {
     autoScrub.enable = true;
     autoSnapshot.enable = true;
     trim.enable = true;
   };
 
-#systemd.services.zfs-import-cache.enable = true;
+  #systemd.services.zfs-import-cache.enable = true;
-systemd.services.zfs-mount.enable = true;
+  systemd.services.zfs-mount.enable = true;
-boot.zfs.devNodes = "/dev/disk/by-id";
+}
- }

modules/tailscale/enable-service.nix

@@ -1,5 +1,5 @@
-{ ... }:
+_:
 
 {
-    services.tailscale.enable = true;
+  services.tailscale.enable = true;
-}
+}

modules/tailscale/exit-node.nix

@@ -1,12 +1,19 @@
-{ ... }:
+_:
 
 {
   services.tailscale = {
     enable = true;
 
-    extraUpFlags = [
+    # extraSetFlags (tailscale set, via the always-on tailscaled-set
+    # service), not extraUpFlags -- extraUpFlags is only ever applied by
+    # tailscaled-autoconnect, which itself only runs when
+    # services.tailscale.authKeyFile is set (nothing in this repo sets one,
+    # so tailscale up is a manual, one-time operator step on every host that
+    # uses this service). extraSetFlags has no such gate, so
+    # --advertise-exit-node self-reapplies on every boot once the operator
+    # has authenticated the node once.
+    extraSetFlags = [
       "--advertise-exit-node"
-      "--advertise-routes=192.168.2.0/24"
     ];
   };
 }

modules/traefik/rotate-logs.nix

@@ -0,0 +1,20 @@
+{ vars, ... }:
+
+{
+  services.logrotate = {
+    enable = true;
+
+    settings = {
+      "${vars.nfsShares.dockerVolumes.mountpoint}/traefik-data/logs/*.log" = {
+        daily = true;
+        size = vars.traefikLogRotate.maxSize;
+        rotate = vars.traefikLogRotate.keep;
+        compress = true;
+        missingok = true;
+        notifempty = true;
+        copytruncate = true;
+      };
+
+    };
+  };
+}

prepare.sh

@@ -1,30 +0,0 @@
-#create MBR table
-parted /dev/sda -- mklabel msdos
-#create nixos partition
-parted /dev/sda -- mkpart primary 1MB -8GB
-#set nixos partition to bootable
-parted /dev/sda -- set 1 boot on
-# create swap partition
-parted /dev/sda -- mkpart primary linux-swap -8GB 100%
-
-#format OS partition
-mkfs.ext4 -L nixos /dev/sda1
-#format swap
-mkswap -L swap /dev/sda2
-
-#activate swap
-swapon /dev/sda2
-
-#mount nixos partition
-mount /dev/disk/by-label/nixos /mnt
-export TMPDIR=/mnt/install-tmp
-mkdir -p /mnt/install-tmp
-#Generate config
-#nixos-generate-config --root /mnt/
-
-#copy customised configuration over
-#cp configuration.nix /mnt/etc/nixos/configuration.nix
-
-#nixos-install --no-root-passwd
-
-#reboot

scripts/bump-nixpkgs-release.sh

@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+# Bumps the NixOS release branch this flake tracks — flake.nix's
+# `nixpkgs.url` and `home-manager.url` — in one place, via targeted
+# substitution of just those two lines. Deliberately does NOT touch any
+# `system.stateVersion` anywhere in the repo: per NixOS's own docs, that
+# value must stay fixed at whatever it was on a host's first install (it
+# pins on-disk data-format defaults, not "which nixpkgs release am I on"),
+# so it's never something a channel bump should follow.
+#
+# scripts/codex-maintenance.sh's own `nixos-25.11` pin (used only to fetch
+# nixpkgs-fmt/statix — see CLAUDE.md) is a separate, independently-versioned
+# reference on purpose: it doesn't have to track the flake's own nixpkgs
+# input, since the tooling just needs to build, not match. Bump it with
+# --tooling if you want it moved too; the default run leaves it alone.
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "$0")/.." && pwd)"
+flake_nix="${repo_root}/flake.nix"
+maintenance_sh="${repo_root}/scripts/codex-maintenance.sh"
+claude_md="${repo_root}/CLAUDE.md"
+
+usage() {
+  cat <<EOF
+Usage: $0 <release> [--tooling <release>]
+
+  <release>            New NixOS release for flake.nix's nixpkgs.url and
+                        home-manager.url, e.g. 26.11
+  --tooling <release>  Also bump scripts/codex-maintenance.sh's separate
+                        nixpkgs-fmt/statix pin (and its mention in
+                        CLAUDE.md) to this release. Independent of the
+                        first argument — pass the same value if you want
+                        both in sync, a different one if you don't.
+
+Examples:
+  $0 26.11
+  $0 26.11 --tooling 26.11
+EOF
+}
+
+release_re='^[0-9]{2}\.(05|11)$'
+
+if [[ $# -eq 0 || "$1" == "-h" || "$1" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+new_release="$1"
+shift
+
+tooling_release=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+  --tooling)
+    tooling_release="${2:?--tooling requires a release argument}"
+    shift 2
+    ;;
+  *)
+    echo "Unknown argument: $1" >&2
+    usage >&2
+    exit 1
+    ;;
+  esac
+done
+
+check_release_format() {
+  local release="$1"
+  if [[ ! "$release" =~ $release_re ]]; then
+    echo "ERROR: '$release' doesn't look like a NixOS release (expected e.g. 26.11)" >&2
+    exit 1
+  fi
+}
+
+check_branch_exists() {
+  local repo_url="$1" branch="$2"
+  echo "Checking '$branch' exists on $repo_url..."
+  if ! git ls-remote --exit-code --heads "$repo_url" "$branch" >/dev/null; then
+    echo "ERROR: branch '$branch' not found on $repo_url. Typo, or not cut yet?" >&2
+    exit 1
+  fi
+}
+
+check_release_format "$new_release"
+
+current_release="$(grep -oE 'nixos-[0-9]{2}\.[0-9]{2}' "$flake_nix" | head -1 | sed 's/^nixos-//')"
+if [[ -z "$current_release" ]]; then
+  echo "ERROR: couldn't find flake.nix's current nixpkgs release" >&2
+  exit 1
+fi
+
+if [[ "$current_release" == "$new_release" ]]; then
+  echo "flake.nix is already on $new_release."
+else
+  echo "Bumping flake.nix's nixpkgs/home-manager release: $current_release -> $new_release"
+  check_branch_exists "https://github.com/NixOS/nixpkgs.git" "nixos-$new_release"
+  check_branch_exists "https://github.com/nix-community/home-manager.git" "release-$new_release"
+
+  sed -i \
+    -e "s|github:NixOS/nixpkgs/nixos-${current_release}|github:NixOS/nixpkgs/nixos-${new_release}|" \
+    -e "s|github:nix-community/home-manager/release-${current_release}|github:nix-community/home-manager/release-${new_release}|" \
+    "$flake_nix"
+
+  echo "Updated:"
+  grep -n "nixos-${new_release}\|release-${new_release}" "$flake_nix"
+fi
+
+if [[ -n "$tooling_release" ]]; then
+  check_release_format "$tooling_release"
+
+  current_tooling_release="$(grep -oE 'nixos-[0-9]{2}\.[0-9]{2}' "$maintenance_sh" | head -1 | sed 's/^nixos-//')"
+
+  if [[ "$current_tooling_release" == "$tooling_release" ]]; then
+    echo "codex-maintenance.sh's tooling pin is already on $tooling_release."
+  else
+    echo "Bumping codex-maintenance.sh's nixpkgs-fmt/statix pin: $current_tooling_release -> $tooling_release"
+    check_branch_exists "https://github.com/NixOS/nixpkgs.git" "nixos-$tooling_release"
+
+    sed -i "s|github:NixOS/nixpkgs/nixos-${current_tooling_release}|github:NixOS/nixpkgs/nixos-${tooling_release}|g" \
+      "$maintenance_sh"
+    sed -i "s|nixos-${current_tooling_release}|nixos-${tooling_release}|g" \
+      "$claude_md"
+
+    echo "Updated:"
+    grep -n "nixos-${tooling_release}" "$maintenance_sh" "$claude_md"
+  fi
+fi
+
+echo
+echo "flake.lock still points at the old input revisions until refreshed. Either:"
+echo "  nix flake update nixpkgs home-manager   # just these two inputs"
+echo "  nix flake update                        # everything — see docs/flake-lock-automation.md"
+echo
+echo "Then run 'bash scripts/codex-maintenance.sh dry-run' before committing —"
+echo "a channel bump can shift option defaults across every host."

scripts/codex-maintenance.sh

@@ -55,6 +55,31 @@ echo "Evaluating host toplevel derivations..."
 for host in $hosts; do
   echo "==> $host"
   nix eval --raw --no-use-registries --no-accept-flake-config ".#nixosConfigurations.${host}.config.system.build.toplevel.drvPath"
+
+  # lxc-* hosts deploy via a directly pct-restore-able tarball instead of
+  # nixos-install (see docs/auto-installer.md); proxmox-* hosts can
+  # alternatively be built as a standalone disk image (see
+  # docs/proxmox-images.md). Both are otherwise-unvalidated buildable
+  # surface, easy to silently break without this.
+  case "$host" in
+    lxc-*)
+      echo "==> $host (tarball)"
+      nix eval --raw --no-use-registries --no-accept-flake-config ".#nixosConfigurations.${host}.config.system.build.tarball.drvPath"
+      ;;
+    proxmox-*)
+      echo "==> $host (diskoImagesScript)"
+      nix eval --raw --no-use-registries --no-accept-flake-config ".#nixosConfigurations.${host}.config.system.build.diskoImagesScript.drvPath"
+      ;;
+  esac
+done
+
+echo
+echo "Evaluating buildable packages..."
+packages_json="$(nix eval --json --no-use-registries --no-accept-flake-config .#packages.x86_64-linux --apply builtins.attrNames)"
+packages="$(echo "$packages_json" | jq -r '.[]')"
+for pkg in $packages; do
+  echo "==> packages.x86_64-linux.${pkg}"
+  nix eval --raw --no-use-registries --no-accept-flake-config ".#packages.x86_64-linux.${pkg}"
 done
 
 if [[ "$MODE" == "dry-run" ]]; then
@@ -63,6 +88,24 @@ if [[ "$MODE" == "dry-run" ]]; then
   for host in $hosts; do
     echo "==> Dry-run build: $host"
     nix build --dry-run --no-link --no-use-registries --no-accept-flake-config ".#nixosConfigurations.${host}.config.system.build.toplevel"
+
+    case "$host" in
+      lxc-*)
+        echo "==> Dry-run build: $host (tarball)"
+        nix build --dry-run --no-link --no-use-registries --no-accept-flake-config ".#nixosConfigurations.${host}.config.system.build.tarball"
+        ;;
+      proxmox-*)
+        echo "==> Dry-run build: $host (diskoImagesScript)"
+        nix build --dry-run --no-link --no-use-registries --no-accept-flake-config ".#nixosConfigurations.${host}.config.system.build.diskoImagesScript"
+        ;;
+    esac
+  done
+
+  echo
+  echo "Running dry-run builds for all packages."
+  for pkg in $packages; do
+    echo "==> Dry-run build: packages.x86_64-linux.${pkg}"
+    nix build --dry-run --no-link --no-use-registries --no-accept-flake-config ".#packages.x86_64-linux.${pkg}"
   done
 fi
 

scripts/create-linode-installer-disk.sh

@@ -1,9 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-#boot to rescue mode
-# set root password
-scp $RESULT_ISO root@$LINODE_IP:/tmp/nixos-auto.iso
-
-#in LISH or ssh to rescue mode
-dd if=/tmp/nixos.iso of=/dev/sda bs=4M status=progress conv=fsync

scripts/create-proxmox-resource.sh

@@ -0,0 +1,556 @@
+#!/usr/bin/env bash
+# Creates new Proxmox VMs/LXC containers from this flake, and reconfigures
+# existing ones -- the manual workflows in docs/proxmox-images.md (VM) and
+# docs/auto-installer.md's "LXC hosts" section (container), automated.
+#
+# Usage:
+#   scripts/create-proxmox-resource.sh --type lxc|vm --host <name> [options]
+#   scripts/create-proxmox-resource.sh --type lxc|vm --list
+#   scripts/create-proxmox-resource.sh --modify --vmid <n> [--cores N] [--memory MB] [--grow-disk GB]
+#
+# SAFETY:
+#   - The default (create) mode only ever creates a NEW resource -- it
+#     refuses to run if the target VMID already exists on the node, or if
+#     a VM/CT identified as --host already exists under any other VMID
+#     (checked live against the node; --allow-duplicate-host overrides).
+#   - --modify only ever touches a resource you name explicitly via
+#     --vmid, shows exactly what will change first, and (outside
+#     --dry-run) always requires typing that VMID back to confirm before
+#     anything is sent to the node. There is no bulk/implicit modify.
+#   - Neither mode can start/stop/delete a resource. Not implemented on
+#     purpose -- ask before adding it.
+#
+# See --help for the full option list.
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck source=env.sh
+source "${repo_root}/scripts/env.sh"
+
+sync_keys="${repo_root}/scripts/sync-host-keys.sh"
+
+usage() {
+  cat <<EOF
+Usage: $0 --type lxc|vm --host <name> [options]      (create)
+       $0 --type lxc|vm --list                        (list --host values)
+       $0 --modify --vmid <n> [options]                (reconfigure)
+
+Create mode (default):
+  --type lxc|vm        lxc = container, built as a CT template tarball.
+                        vm  = VM, built as a Disko .raw disk image (UEFI/OVMF).
+  --host <name>         Which host identity to deploy -- matches
+                        config.networking.hostName (server, docker,
+                        nix-cache, nixos, pxe-boot, nix-minimal). Use
+                        --list to see what's available for --type.
+  --name <name>          Proxmox display name/hostname (default: --host's
+                          value, e.g. nix-cache -- for lxc this becomes the
+                          guest's real networking.hostName too, since
+                          proxmoxLXC.manageHostName pulls it from Proxmox's
+                          own container config, so it must match host.nix
+                          regardless of build type)
+  --vmid <n>              Numeric VMID (default: next free, via
+                          \`pvesh get /cluster/nextid\` on the node).
+                          Refuses to run if this ID already exists.
+  --disk-size <GB>           lxc only: rootfs size for \`pct create\`
+                              (default: \$PROXMOX_DEFAULT_LXC_DISK_GB, ${PROXMOX_DEFAULT_LXC_DISK_GB}).
+  --image <path>              Use this local image/tarball instead of
+                              checking the node / building one from the flake.
+  --force-rebuild                Skip the "does the node already have this
+                                  image" check -- always build fresh and
+                                  overwrite what's there.
+  --allow-duplicate-host        Required if a VM/CT identified as --host
+                                already exists on the node (checked live via
+                                qm/pct, not any file in this repo) --
+                                otherwise refused, since it'd share that
+                                host's hostName/hostId.
+
+Modify mode (reconfigure an EXISTING resource -- requires --modify):
+  --modify                Switch to modify mode.
+  --vmid <n>                Required: which existing resource to change.
+                            Type/VM-vs-CT is auto-detected on the node.
+  --grow-disk <GB>            Grow the primary disk by this many GB
+                              (qm/pct resize; Proxmox only supports
+                              growing, never shrinking, an existing disk).
+  At least one of --cores / --memory / --grow-disk is required. Always
+  prints the current -> new values and requires typing the VMID back to
+  confirm, even outside --dry-run.
+
+Shared:
+  --cores <n>              create: default \$PROXMOX_DEFAULT_CORES (${PROXMOX_DEFAULT_CORES}).
+                            modify: omit to leave unchanged.
+  --memory <MB>              create: default \$PROXMOX_DEFAULT_MEMORY_MB (${PROXMOX_DEFAULT_MEMORY_MB}).
+                              modify: omit to leave unchanged.
+  --swap <MB>                 lxc only, create time: \`--memory\` doesn't
+                              touch swap -- it silently stays at Proxmox's
+                              own 512M default otherwise. (default: matches
+                              whatever --memory resolves to)
+  --storage <pool>              (default: \$PROXMOX_STORAGE, ${PROXMOX_STORAGE})
+  --iso-storage <pool>            (default: \$PROXMOX_ISO_STORAGE, ${PROXMOX_ISO_STORAGE})
+  --bridge <bridge>                (default: \$PROXMOX_BRIDGE, ${PROXMOX_BRIDGE})
+  --node <host>                     Proxmox node to SSH into (default:
+                                    \$PROXMOX_HOST, ${PROXMOX_HOST})
+  --dry-run                           Print the full plan; touch nothing
+                                      local or remote, no prompts.
+  -h, --help
+
+Config for --storage/--bridge/--node/etc. lives in scripts/env.sh -- edit
+that instead of passing the same flag every time.
+EOF
+}
+
+dry_run=0
+modify=0
+type=""
+host=""
+name=""
+vmid=""
+cores=""
+memory=""
+swap=""
+disk_size=""
+grow_disk=""
+image=""
+storage="$PROXMOX_STORAGE"
+iso_storage="$PROXMOX_ISO_STORAGE"
+bridge="$PROXMOX_BRIDGE"
+node="$PROXMOX_HOST"
+do_list=0
+allow_duplicate_host=0
+force_rebuild=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+  --type) type="$2"; shift 2 ;;
+  --host) host="$2"; shift 2 ;;
+  --name) name="$2"; shift 2 ;;
+  --vmid) vmid="$2"; shift 2 ;;
+  --cores) cores="$2"; shift 2 ;;
+  --memory) memory="$2"; shift 2 ;;
+  --swap) swap="$2"; shift 2 ;;
+  --disk-size) disk_size="$2"; shift 2 ;;
+  --grow-disk) grow_disk="$2"; shift 2 ;;
+  --image) image="$2"; shift 2 ;;
+  --storage) storage="$2"; shift 2 ;;
+  --iso-storage) iso_storage="$2"; shift 2 ;;
+  --bridge) bridge="$2"; shift 2 ;;
+  --node) node="$2"; shift 2 ;;
+  --list) do_list=1; shift ;;
+  --allow-duplicate-host) allow_duplicate_host=1; shift ;;
+  --force-rebuild) force_rebuild=1; shift ;;
+  --modify) modify=1; shift ;;
+  --dry-run) dry_run=1; shift ;;
+  -h | --help) usage; exit 0 ;;
+  *) echo "Unknown option: $1" >&2; usage >&2; exit 1 ;;
+  esac
+done
+
+ssh_target="${PROXMOX_SSH_USER}@${node}"
+
+remote() {
+  if [[ "$dry_run" -eq 1 ]]; then
+    echo "[dry-run] ssh ${ssh_target} -- $*"
+  else
+    ssh "$ssh_target" "$@"
+  fi
+}
+
+# ============================================================ modify mode
+cmd_modify() {
+  if [[ -z "$vmid" ]]; then
+    echo "ERROR: --modify requires --vmid." >&2
+    exit 1
+  fi
+  if [[ -z "$cores" && -z "$memory" && -z "$grow_disk" ]]; then
+    echo "ERROR: --modify needs at least one of --cores / --memory / --grow-disk." >&2
+    exit 1
+  fi
+
+  echo "Looking up VMID ${vmid} on ${node}..."
+  local kind current_cores current_memory disk_key
+  if ssh "$ssh_target" "qm status ${vmid}" >/dev/null 2>&1; then
+    kind="vm"
+    disk_key="scsi0"
+  elif ssh "$ssh_target" "pct status ${vmid}" >/dev/null 2>&1; then
+    kind="lxc"
+    disk_key="rootfs"
+  else
+    echo "ERROR: VMID ${vmid} doesn't exist on ${node} -- nothing to modify." >&2
+    exit 1
+  fi
+
+  local config_cmd="qm config ${vmid}"
+  [[ "$kind" == "lxc" ]] && config_cmd="pct config ${vmid}"
+  local current_config
+  current_config="$(ssh "$ssh_target" "$config_cmd")"
+  current_cores="$(echo "$current_config" | grep -oP '^cores:\s*\K\S+' || echo '?')"
+  current_memory="$(echo "$current_config" | grep -oP '^memory:\s*\K\S+' || echo '?')"
+
+  echo
+  echo "VMID ${vmid} is a ${kind} on ${node}. Planned changes:"
+  [[ -n "$cores" ]] && echo "  cores:  ${current_cores} -> ${cores}"
+  [[ -n "$memory" ]] && echo "  memory: ${current_memory} MB -> ${memory} MB"
+  [[ -n "$grow_disk" ]] && echo "  ${disk_key}: grow by +${grow_disk}G (Proxmox can only grow, not shrink, an existing disk)"
+
+  if [[ "$dry_run" -eq 1 ]]; then
+    echo
+    echo "[dry-run] Nothing was changed."
+    return
+  fi
+
+  echo
+  read -rp "Type the VMID (${vmid}) to confirm these changes: " confirm
+  if [[ "$confirm" != "$vmid" ]]; then
+    echo "Cancelled -- input didn't match ${vmid}."
+    exit 1
+  fi
+
+  local set_cmd="qm set"
+  local resize_cmd="qm resize"
+  [[ "$kind" == "lxc" ]] && set_cmd="pct set" && resize_cmd="pct resize"
+
+  if [[ -n "$cores" || -n "$memory" ]]; then
+    local args=""
+    [[ -n "$cores" ]] && args="${args} --cores ${cores}"
+    [[ -n "$memory" ]] && args="${args} --memory ${memory}"
+    remote "${set_cmd} ${vmid}${args}"
+  fi
+  if [[ -n "$grow_disk" ]]; then
+    remote "${resize_cmd} ${vmid} ${disk_key} +${grow_disk}G"
+  fi
+
+  echo
+  echo "Done. VMID ${vmid} updated."
+}
+
+if [[ "$modify" -eq 1 ]]; then
+  cmd_modify
+  exit 0
+fi
+
+# ============================================================= create mode
+if [[ "$type" != "lxc" && "$type" != "vm" ]]; then
+  echo "ERROR: --type must be 'lxc' or 'vm'." >&2
+  usage >&2
+  exit 1
+fi
+
+platform_prefix="lxc"
+[[ "$type" == "vm" ]] && platform_prefix="proxmox"
+[[ -z "$cores" ]] && cores="$PROXMOX_DEFAULT_CORES"
+[[ -z "$memory" ]] && memory="$PROXMOX_DEFAULT_MEMORY_MB"
+
+# --- discover / resolve the flake target from --host --------------------
+list_hosts() {
+  local target hostname
+  for target in $(nix eval --json --no-use-registries --no-accept-flake-config \
+    "${repo_root}#nixosConfigurations" --apply builtins.attrNames 2>/dev/null \
+    | jq -r --arg p "${platform_prefix}-" '.[] | select(startswith($p))'); do
+    hostname="$(nix eval --raw --no-use-registries --no-accept-flake-config \
+      "${repo_root}#nixosConfigurations.${target}.config.networking.hostName" 2>/dev/null)"
+    printf '  %-12s -> %s\n' "$hostname" "$target"
+  done
+}
+
+if [[ "$do_list" -eq 1 ]]; then
+  echo "Available --host values for --type ${type}:"
+  list_hosts
+  exit 0
+fi
+
+if [[ -z "$host" ]]; then
+  echo "ERROR: --host is required (or use --list to see options)." >&2
+  exit 1
+fi
+
+flake_target=""
+for target in $(nix eval --json --no-use-registries --no-accept-flake-config \
+  "${repo_root}#nixosConfigurations" --apply builtins.attrNames \
+  | jq -r --arg p "${platform_prefix}-" '.[] | select(startswith($p))'); do
+  hn="$(nix eval --raw --no-use-registries --no-accept-flake-config \
+    "${repo_root}#nixosConfigurations.${target}.config.networking.hostName")"
+  if [[ "$hn" == "$host" ]]; then
+    flake_target="$target"
+    break
+  fi
+done
+
+if [[ -z "$flake_target" ]]; then
+  echo "ERROR: no ${platform_prefix}-* target has hostName '${host}'." >&2
+  echo "Available:" >&2
+  list_hosts >&2
+  exit 1
+fi
+
+# The container/VM's real identity is --host (e.g. "nix-cache"), validated
+# above against config.networking.hostName -- not the flake target name
+# (e.g. "lxc-nix-cache"), which is build-type-specific and only exists to
+# pick which platform variant to build. Defaulting --name to the flake
+# target would make lxc's --hostname (which proxmoxLXC.manageHostName
+# feeds straight into the guest's real hostname) disagree with host.nix.
+[[ -z "$name" ]] && name="$host"
+
+# --- refuse to duplicate a host that's already live on the node ---------
+# Queries the node itself (qm/pct's own name/hostname config), not any
+# static list in this repo -- a file can't track whether a resource still
+# actually exists, and this used to be checked against variables.nix's
+# deployedTargets, which drifted stale (it kept naming a VM as "the real
+# deployment" well after that VM had been destroyed, blocking its own
+# redeploy) until that list was dropped in favour of this live check. This
+# only catches guests identified with the default --name (== --host, what
+# this script itself always uses unless --name is overridden) -- a guest
+# manually renamed on the node afterwards wouldn't match, but nothing here
+# creates guests that way.
+if [[ "$allow_duplicate_host" -eq 1 ]]; then
+  echo
+  echo "--allow-duplicate-host: skipping the check for an existing '${host}' on ${node}."
+elif [[ "$dry_run" -eq 1 ]]; then
+  echo
+  echo "[dry-run] would check ${node} for an existing VM/CT identified as '${host}'"
+else
+  echo
+  echo "==> Checking ${node} for an existing VM/CT identified as '${host}'..."
+  ssh_check_status=0
+  existing="$(ssh "$ssh_target" bash -s -- "$host" <<'REMOTE_SCRIPT'
+target="$1"
+for id in $(qm list 2>/dev/null | awk 'NR>1{print $1}'); do
+  n="$(qm config "$id" 2>/dev/null | grep -oP '^name:\s*\K\S+' || true)"
+  [[ "$n" == "$target" ]] && echo "vm ${id} ${n}"
+done
+for id in $(pct list 2>/dev/null | awk 'NR>1{print $1}'); do
+  n="$(pct config "$id" 2>/dev/null | grep -oP '^hostname:\s*\K\S+' || true)"
+  [[ "$n" == "$target" ]] && echo "lxc ${id} ${n}"
+done
+REMOTE_SCRIPT
+  )" || ssh_check_status=$?
+  if [[ "$ssh_check_status" -ne 0 ]]; then
+    echo "ERROR: couldn't reach ${node} (ssh exited ${ssh_check_status}) to check for an" >&2
+    echo "existing '${host}' resource -- refusing to guess. Fix connectivity and retry," >&2
+    echo "or pass --allow-duplicate-host if you're sure none exists (this skips the" >&2
+    echo "check entirely)." >&2
+    exit 1
+  fi
+  if [[ -n "$existing" ]]; then
+    echo "ERROR: '${host}' already exists on ${node}:" >&2
+    echo "$existing" | while read -r kind id n; do
+      echo "  - ${kind} VMID ${id} (${n})" >&2
+    done
+    echo "Refusing to create a second resource sharing this identity. Pass" >&2
+    echo "--allow-duplicate-host to create one anyway (it gets its own distinct" >&2
+    echo "sops key and VMID -- the existing resource(s) above are left untouched)," >&2
+    echo "or use --modify to reconfigure the existing one instead." >&2
+    exit 1
+  fi
+fi
+
+echo "Target: ${flake_target} (host=${host}, type=${type}) -> Proxmox resource '${name}'"
+
+# Decide on nix-cache once, here -- this is the earliest point that needs
+# it (sync-host-keys.sh below needs nix-shell packages regardless of
+# whether an image ends up getting built later), and the decision is
+# exported so that subprocess -- and this script's own later build step,
+# if it gets there -- both reuse it instead of probing again.
+nix_extra_opts
+
+# --- make sure this target has a registered host key --------------------
+echo
+echo "==> Ensuring host key exists and is registered..."
+sync_args=("$flake_target")
+[[ "$dry_run" -eq 1 ]] && sync_args+=(--dry-run)
+bash "$sync_keys" "${sync_args[@]}"
+
+# --- VMID: pick one, and refuse to touch anything that already exists ---
+echo
+if [[ -z "$vmid" ]]; then
+  if [[ "$dry_run" -eq 1 ]]; then
+    vmid="<next-free-vmid>"
+    echo "[dry-run] would ask ${node} for the next free VMID (pvesh get /cluster/nextid)"
+  else
+    vmid="$(ssh "$ssh_target" "pvesh get /cluster/nextid" | tr -d '[:space:]')"
+    echo "Auto-assigned VMID: ${vmid}"
+  fi
+else
+  echo "Requested VMID: ${vmid}"
+fi
+
+if [[ "$dry_run" -eq 0 ]]; then
+  # qm/pct status exits non-zero (and prints "does not exist") for a free
+  # ID on that resource type -- but a VMID could exist as the OTHER
+  # resource type (e.g. requested a CT id that's actually a VM), so check
+  # both. Any success here means something is already using this ID --
+  # refuse to go anywhere near it. (Reconfiguring an existing resource is
+  # --modify's job, not this one's.)
+  if ssh "$ssh_target" "qm status ${vmid}" >/dev/null 2>&1 \
+    || ssh "$ssh_target" "pct status ${vmid}" >/dev/null 2>&1; then
+    echo "ERROR: VMID ${vmid} already exists on ${node}. Refusing to touch an" >&2
+    echo "existing resource here -- use --modify to reconfigure it, pick a" >&2
+    echo "different --vmid, or omit it to auto-assign." >&2
+    exit 1
+  fi
+fi
+
+# --- resolve the remote path -- fixed naming (not the nix store's own
+# derivation-hash-based filename), so a later run can check for it by name.
+# lxc uploads as a CT *template* (Proxmox's "vztmpl" content type, under
+# iso_storage) -- config.system.build.tarball is a plain rootfs tarball,
+# not a vzdump backup archive, so it's created with `pct create ... vztmpl`,
+# not restored with `pct restore` (that expects backup-archive metadata
+# this tarball doesn't have, and fails with "archive contains no
+# configuration file").
+remote_dir="/var/lib/vz/import"
+remote_filename="${flake_target}.raw"
+if [[ "$type" == "lxc" ]]; then
+  remote_dir="/var/lib/vz/template/cache"
+  remote_filename="${flake_target}.tar.xz"
+fi
+remote_path="${remote_dir}/${remote_filename}"
+
+# --- build (or reuse an image already on the node) ------------------------
+echo
+local_image=""
+image_already_remote=0
+
+if [[ -n "$image" ]]; then
+  [[ -f "$image" ]] || { echo "ERROR: --image '${image}' not found." >&2; exit 1; }
+  local_image="$image"
+  echo "Using provided image: ${local_image}"
+elif [[ "$force_rebuild" -eq 1 ]]; then
+  echo "--force-rebuild: skipping the existing-image check on ${node}."
+else
+  echo "==> Checking whether ${node} already has ${remote_path}..."
+  if [[ "$dry_run" -eq 1 ]]; then
+    echo "[dry-run] would check: ssh ${ssh_target} -- test -f ${remote_path}"
+  elif ssh "$ssh_target" "test -f '${remote_path}'" 2>/dev/null; then
+    echo "Found it -- reusing, skipping build and upload (use --force-rebuild to override)."
+    image_already_remote=1
+  else
+    echo "Not found -- will build."
+  fi
+fi
+
+if [[ "$image_already_remote" -eq 0 && -z "$local_image" ]]; then
+  # Mirrors the real build commands' "${NIX_OPTS[@]}" below -- nix_extra_opts
+  # (called earlier, once) has already decided whether nix-cache is in play,
+  # and the dry-run preview needs to reflect that decision instead of always
+  # printing the same command regardless of outcome.
+  nix_opts_display=""
+  if [[ ${#NIX_OPTS[@]} -gt 0 ]]; then
+    printf -v nix_opts_display '%q ' "${NIX_OPTS[@]}"
+    nix_opts_display=" ${nix_opts_display% }"
+  fi
+  if [[ "$type" == "lxc" ]]; then
+    if [[ "$dry_run" -eq 1 ]]; then
+      echo "[dry-run] would build: NIXOS_HOST_KEYS_DIR=${repo_root}/host-keys nix build --impure \\"
+      echo "[dry-run]   --no-use-registries --no-accept-flake-config${nix_opts_display} \\"
+      echo "[dry-run]   .#nixosConfigurations.${flake_target}.config.system.build.tarball"
+      local_image="<built-tarball>"
+    else
+      echo "==> Building LXC tarball for ${flake_target}..."
+      NIXOS_HOST_KEYS_DIR="${repo_root}/host-keys" nix build --impure \
+        --no-use-registries --no-accept-flake-config "${NIX_OPTS[@]}" \
+        ".#nixosConfigurations.${flake_target}.config.system.build.tarball" \
+        --out-link "${repo_root}/result-${flake_target}"
+      local_image="$(find "${repo_root}/result-${flake_target}/tarball" -maxdepth 1 -type f | head -1)"
+      echo "Built: ${local_image}"
+    fi
+  else
+    if [[ "$dry_run" -eq 1 ]]; then
+      echo "[dry-run] would build: nix build --no-use-registries --no-accept-flake-config${nix_opts_display} \\"
+      echo "[dry-run]   .#nixosConfigurations.${flake_target}.config.system.build.diskoImagesScript"
+      echo "[dry-run] would run:   sudo ./result-${flake_target} \\"
+      echo "[dry-run]                --pre-format-files host-keys/${flake_target}_ssh_host_ed25519_key /etc/ssh/ssh_host_ed25519_key \\"
+      echo "[dry-run]                --pre-format-files host-keys/${flake_target}_ssh_host_ed25519_key.pub /etc/ssh/ssh_host_ed25519_key.pub \\"
+      echo "[dry-run]                --build-memory 2048"
+      local_image="<built-image>.raw"
+    else
+      echo "==> Building Disko image script for ${flake_target}..."
+      nix build --no-use-registries --no-accept-flake-config "${NIX_OPTS[@]}" \
+        ".#nixosConfigurations.${flake_target}.config.system.build.diskoImagesScript" \
+        --out-link "${repo_root}/result-${flake_target}"
+      echo "==> Running it (builds the .raw image in a temporary QEMU VM, needs sudo)..."
+      ( cd "$repo_root" && sudo "./result-${flake_target}" \
+          --pre-format-files "host-keys/${flake_target}_ssh_host_ed25519_key" /etc/ssh/ssh_host_ed25519_key \
+          --pre-format-files "host-keys/${flake_target}_ssh_host_ed25519_key.pub" /etc/ssh/ssh_host_ed25519_key.pub \
+          --build-memory 2048 )
+      local_image="$(find "$repo_root" -maxdepth 1 -name "*.raw" -newer "${repo_root}/result-${flake_target}" | head -1)"
+      if [[ -z "$local_image" ]]; then
+        echo "ERROR: expected a .raw image after the build but didn't find one in ${repo_root}." >&2
+        exit 1
+      fi
+      echo "Built: ${local_image}"
+    fi
+  fi
+fi
+
+# --- upload (skip entirely if reusing an image already on the node) ------
+echo
+if [[ "$image_already_remote" -eq 1 ]]; then
+  : # nothing to upload
+elif [[ "$dry_run" -eq 1 ]]; then
+  echo "[dry-run] would upload: scp ${local_image} ${ssh_target}:${remote_path}"
+else
+  echo "==> Uploading to ${node}:${remote_path}..."
+  ssh "$ssh_target" "mkdir -p ${remote_dir}"
+  scp "$local_image" "${ssh_target}:${remote_path}"
+fi
+
+# --- create -----------------------------------------------------------------
+echo
+if [[ "$type" == "lxc" ]]; then
+  echo "==> Creating LXC container ${vmid} (${name})..."
+  local_disk_size="${disk_size:-$PROXMOX_DEFAULT_LXC_DISK_GB}"
+  # --memory doesn't touch swap -- it silently stays at Proxmox's own
+  # 512M default otherwise (confirmed live: --memory 2048 left swap at
+  # 512). Default to matching whatever --memory resolved to above.
+  local_swap="${swap:-$memory}"
+  # --unprivileged 1: modules/platforms/lxc.nix sets proxmoxLXC.privileged
+  # = false, so the NixOS config inside the image assumes it's running as
+  # an unprivileged container (cgroup/capability/mount expectations baked
+  # in at boot). `pct create`'s own CLI default for this flag is
+  # privileged (unlike the web UI, which defaults its checkbox the other
+  # way) -- leaving it unset creates a privileged container running a
+  # NixOS config that assumes unprivileged, a real mismatch.
+  #
+  # --features nesting=1,keyctl=1: required for a modern (v247+) systemd
+  # guest to actually boot unprivileged -- confirmed live: without this,
+  # AppArmor denies the nested user namespaces and credential mounts
+  # systemd routinely uses (even plain getty units), and every getty
+  # crash-loops on a denied mount every ~3s (visible as garbage on the
+  # console) while core services like nsncd fail the same way.
+  create_cmd="pct create ${vmid} ${iso_storage}:vztmpl/${remote_filename} --unprivileged 1 --features ${PROXMOX_DEFAULT_LXC_FEATURES} --rootfs ${storage}:${local_disk_size} --hostname ${name} --cores ${cores} --memory ${memory} --swap ${local_swap} --net0 name=eth0,bridge=${bridge},ip=dhcp"
+  remote "$create_cmd"
+  remote "pct start ${vmid}"
+else
+  echo "==> Creating VM ${vmid} (${name})..."
+  # pre-enrolled-keys=0 disables OVMF's Secure Boot key pre-enrollment --
+  # required, or systemd-boot (unsigned) can't be trusted by the firmware.
+  remote "qm create ${vmid} --name ${name} --memory ${memory} --cores ${cores} \
+--net0 virtio,bridge=${bridge} --bios ovmf --machine q35 --scsihw virtio-scsi-pci \
+--efidisk0 ${storage}:1,efitype=4m,pre-enrolled-keys=0"
+
+  if [[ "$dry_run" -eq 1 ]]; then
+    echo "[dry-run] ssh ${ssh_target} -- qm importdisk ${vmid} ${remote_path} ${storage}"
+    echo "[dry-run] (would parse the resulting disk identifier from that output)"
+    echo "[dry-run] ssh ${ssh_target} -- qm set ${vmid} --scsi0 ${storage}:<parsed-disk-id>"
+  else
+    importdisk_output="$(ssh "$ssh_target" "qm importdisk ${vmid} ${remote_path} ${storage}")"
+    echo "$importdisk_output"
+    disk_id="$(echo "$importdisk_output" | grep -oP "(?<=Successfully imported disk as ')[^']+" | sed 's/^unused[0-9]*://')"
+    if [[ -z "$disk_id" ]]; then
+      echo "ERROR: couldn't parse the imported disk identifier from qm importdisk's output above." >&2
+      echo "The VM shell (${vmid}) and imported disk both exist -- finish attaching it by hand:" >&2
+      echo "  ssh ${ssh_target} -- qm set ${vmid} --scsi0 ${storage}:<disk-id-from-output-above>" >&2
+      echo "  ssh ${ssh_target} -- qm set ${vmid} --boot order=scsi0" >&2
+      exit 1
+    fi
+    remote "qm set ${vmid} --scsi0 ${disk_id}"
+  fi
+  remote "qm set ${vmid} --boot order=scsi0"
+  remote "qm start ${vmid}"
+fi
+
+echo
+if [[ "$dry_run" -eq 1 ]]; then
+  echo "[dry-run] Nothing was built, uploaded, or created."
+else
+  echo "Done. ${name} (VMID ${vmid}) should be booting on ${node}."
+fi

scripts/env.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# Shared config for scripts/*.sh. Source this instead of hardcoding a
+# second copy of these values in every script:
+#   source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/env.sh"
+# Every variable can still be overridden per-invocation via the
+# environment (e.g. PROXMOX_STORAGE=tank-nvme ./scripts/create-proxmox-resource.sh ...)
+# since each one only sets a default if unset.
+
+# SSH-reachable Proxmox node that scripts/create-proxmox-resource.sh runs
+# pct/qm on. Matches the Proxmox web UI hostname already used in
+# hosts/nixos/home.nix's desktop shortcuts (pve.<homeDomain> from
+# variables.nix) -- change this if that's not actually reachable over SSH,
+# or if you're targeting a different node in a multi-node cluster.
+: "${PROXMOX_HOST:=pve.sweet.home}"
+: "${PROXMOX_SSH_USER:=root}"
+
+# Storage pool names -- Proxmox's own stock-install defaults, but this
+# varies a lot by setup (ZFS pool name, custom LVM-thin volume, etc.).
+# Verify with `pvesm status` on the node and correct these if wrong.
+: "${PROXMOX_STORAGE:=local-lvm}"     # VM disks / CT rootfs
+: "${PROXMOX_ISO_STORAGE:=local}"     # uploaded images/ISOs/CT templates
+
+: "${PROXMOX_BRIDGE:=vmbr0}"
+
+# Fallback resource sizing when a script doesn't get --cores/--memory.
+: "${PROXMOX_DEFAULT_CORES:=2}"
+: "${PROXMOX_DEFAULT_MEMORY_MB:=2048}"
+
+# `pct create` (unlike `pct restore`) requires an explicit rootfs size --
+# no backup metadata to infer it from. Matches Proxmox's own GUI default.
+: "${PROXMOX_DEFAULT_LXC_DISK_GB:=8}"
+
+# `pct create --memory` only sets RAM -- swap is a wholly separate
+# parameter that otherwise silently stays at Proxmox's own 512M default
+# regardless of --memory (confirmed: creating with --memory 2048 left
+# swap at 512). create-proxmox-resource.sh defaults --swap to whatever
+# --memory resolves to at runtime rather than a static value here, so it
+# tracks a --memory picked at the CLI too, not just the default above.
+
+# Required for a modern (v247+) systemd guest to actually boot as an
+# unprivileged container: systemd's routine use of nested user namespaces
+# and credential mounts (LoadCredential=, DynamicUser=, etc. -- used even
+# by plain getty units) gets denied by AppArmor's default LXC confinement
+# without these. Confirmed live: without them, every getty unit
+# crash-loops on a denied `/run/credentials/*` mount every ~3s (visible
+# as garbage on the console) and core services like nsncd fail the same
+# way on userns_create; system.build.tarball never finishes activating.
+: "${PROXMOX_DEFAULT_LXC_FEATURES:=nesting=1,keyctl=1}"
+
+export PROXMOX_HOST PROXMOX_SSH_USER PROXMOX_STORAGE PROXMOX_ISO_STORAGE \
+  PROXMOX_BRIDGE PROXMOX_DEFAULT_CORES PROXMOX_DEFAULT_MEMORY_MB \
+  PROXMOX_DEFAULT_LXC_DISK_GB PROXMOX_DEFAULT_LXC_FEATURES
+
+# Matches variables.nix's nixCacheHost -- update both if it ever changes.
+: "${NIX_CACHE_HOST:=nix-cache}"
+export NIX_CACHE_HOST
+
+# nix_extra_opts: call as a plain statement (NOT inside $(...)/<(...) --
+# that forks a subshell, and the whole point is exporting a decision back
+# into *this* shell) to populate the global NIX_OPTS array with whatever
+# extra `nix`/`nix-shell` CLI options are needed to avoid nix-cache when
+# it's unreachable:
+#   nix_extra_opts
+#   nix build "${NIX_OPTS[@]}" ...
+#
+# Without this, every single `nix eval`/`nix build` call retries each
+# store path against a dead substituter up to 5 times with backoff
+# (confirmed: ~15s+ per lookup even with a short connect-timeout, because
+# nix's own retry count isn't controllable that way), and separately
+# tries it as a remote builder too -- both fail independently, so both
+# are checked.
+#
+# Checked with a single fast `curl`/TCP probe (bypassing nix's retry logic
+# entirely) the first time this is called in a given process, and the
+# result is exported as NIX_EXTRA_OPTS so a script that shells out to
+# another script in this repo (e.g. create-proxmox-resource.sh calling
+# sync-host-keys.sh) reuses the same decision instead of probing twice.
+declare -a NIX_OPTS=()
+
+nix_extra_opts() {
+  if [[ -n "${NIX_EXTRA_OPTS_DECIDED:-}" ]]; then
+    if [[ -n "${NIX_EXTRA_OPTS:-}" ]]; then
+      eval "NIX_OPTS=(${NIX_EXTRA_OPTS})"
+    else
+      NIX_OPTS=()
+    fi
+    return
+  fi
+  export NIX_EXTRA_OPTS_DECIDED=1
+  NIX_OPTS=()
+
+  # Retry a couple of times, 1s apart, before believing either check --
+  # belt-and-suspenders against a genuine multi-second blip (nix-cache
+  # restarting), on top of the fix below. Worst case (~11s total, host
+  # genuinely gone) is still nowhere near the 15s+ *per lookup* nix's own
+  # substituter retries would cost if this check didn't exist at all.
+  local attempt cache_up=0 builder_up=0
+  for attempt in 1 2 3; do
+    if curl --silent --fail --max-time 3 "http://${NIX_CACHE_HOST}/nix-cache-info" >/dev/null 2>&1; then
+      cache_up=1
+      break
+    fi
+    [[ "$attempt" -lt 3 ]] && sleep 1
+  done
+
+  if [[ "$cache_up" -eq 0 ]]; then
+    echo "nix-cache (http://${NIX_CACHE_HOST}) is unreachable -- skipping it (substituter + remote builder) for the rest of this run." >&2
+    NIX_OPTS=(--option substituters "https://cache.nixos.org/" --builders "")
+  else
+    for attempt in 1 2 3; do
+      # `exec 3<>/dev/tcp/...` just opens the fd and returns -- it does NOT
+      # read from it. Confirmed live this is load-bearing, not stylistic:
+      # the previous `cat < /dev/tcp/.../22` blocked forever and always hit
+      # the timeout even against a perfectly healthy nix-cache, because
+      # sshd sends its banner and then holds the connection open waiting
+      # for the client to speak next -- `cat` never sees EOF, so this
+      # check reported "unreachable" unconditionally, 100% of the time,
+      # regardless of whether the remote builder was actually up.
+      if timeout 3 bash -c "exec 3<>/dev/tcp/${NIX_CACHE_HOST}/22" 2>/dev/null; then
+        builder_up=1
+        break
+      fi
+      [[ "$attempt" -lt 3 ]] && sleep 1
+    done
+    if [[ "$builder_up" -eq 0 ]]; then
+      echo "nix-cache's SSH remote builder (nixremote@${NIX_CACHE_HOST}:22) is unreachable -- disabling remote builds for the rest of this run." >&2
+      NIX_OPTS=(--builders "")
+    fi
+  fi
+
+  # `printf '%q '` with a genuinely empty NIX_OPTS still runs one format
+  # pass over a missing argument and yields the literal `'' ` rather than
+  # an empty string (confirmed live) -- a subprocess that later does
+  # `eval "NIX_OPTS=(${NIX_EXTRA_OPTS})"` (the branch above, for e.g.
+  # sync-host-keys.sh reusing this process's decision) would then rebuild
+  # a 1-element array holding an empty string instead of a 0-element
+  # array, and `nix-shell "${NIX_OPTS[@]}" -p <pkg>` chokes on that stray
+  # element as a bogus positional argument. Guard the empty case
+  # explicitly so nix-cache being reachable (NIX_OPTS legitimately empty)
+  # round-trips as truly empty instead.
+  if [[ ${#NIX_OPTS[@]} -gt 0 ]]; then
+    printf -v NIX_EXTRA_OPTS '%q ' "${NIX_OPTS[@]}"
+  else
+    NIX_EXTRA_OPTS=""
+  fi
+  export NIX_EXTRA_OPTS
+}

scripts/lib/sync-host-keys-edit-sops.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+# Companion to scripts/sync-host-keys.sh. Applies a set of additive edits
+# to .sops.yaml via targeted line insertion -- not a full YAML parse and
+# re-serialize -- so every untouched byte of the file is guaranteed to stay
+# exactly as it was (a full round-trip through a generic YAML library was
+# tested and silently reformatted the whole file's indentation style).
+#
+# Reads a JSON edit plan from stdin:
+#   {
+#     "add_keys": [{"host": "lxc-server", "age_key": "age1..."}],
+#     "add_aliases": [{"host": "lxc-server", "basename": "common.yaml"}],
+#     "remove_keys": ["lxc-server"],
+#     "remove_aliases_for_hosts": ["lxc-server"]
+#   }
+# Idempotent: an anchor or alias that's already present/absent is left
+# alone -- adding what's already there, or removing what's already gone,
+# is a no-op rather than an error.
+# Prints a JSON summary of what actually changed to stdout, so the caller
+# knows which secrets/*.yaml files need `sops updatekeys` and which don't.
+import json
+import re
+import sys
+
+KEY_LINE_RE = re.compile(r"^  - &\S+ age1")
+
+
+def add_keys(lines, add_keys):
+    existing_anchors = set()
+    for line in lines:
+        m = re.match(r"^  - &(\S+) age1", line)
+        if m:
+            existing_anchors.add(m.group(1))
+
+    new = [e for e in add_keys if e["host"] not in existing_anchors]
+    if not new:
+        return lines, []
+
+    last_idx = None
+    for i, line in enumerate(lines):
+        if KEY_LINE_RE.match(line):
+            last_idx = i
+    if last_idx is None:
+        print("ERROR: no '  - &<name> age1...' line found under keys: in .sops.yaml", file=sys.stderr)
+        sys.exit(1)
+
+    insert = [f"  - &{e['host']} {e['age_key']}\n" for e in new]
+    lines = lines[: last_idx + 1] + insert + lines[last_idx + 1 :]
+    return lines, [e["host"] for e in new]
+
+
+def add_aliases(lines, add_aliases):
+    changed_files = []
+    for e in add_aliases:
+        host = e["host"]
+        basename = e["basename"]
+        target = "path_regex: secrets/" + basename.replace(".", r"\.") + "$"
+
+        rule_start = None
+        for i, line in enumerate(lines):
+            if target in line:
+                rule_start = i
+                break
+        if rule_start is None:
+            print(
+                f"WARNING: no creation_rule for secrets/{basename} in .sops.yaml "
+                f"(needed by {host}) -- add one manually, then re-run.",
+                file=sys.stderr,
+            )
+            continue
+
+        rule_end = len(lines)
+        for i in range(rule_start + 1, len(lines)):
+            if re.match(r"^  - path_regex:", lines[i]):
+                rule_end = i
+                break
+
+        block = lines[rule_start:rule_end]
+        if any(re.search(r"\*" + re.escape(host) + r"\s*$", line) for line in block):
+            continue  # already present
+
+        last_alias_idx = None
+        last_alias_indent = None
+        for i in range(rule_start, rule_end):
+            m = re.match(r"^(\s*)- \*\S+\s*$", lines[i])
+            if m:
+                last_alias_idx = i
+                last_alias_indent = m.group(1)
+        if last_alias_idx is None:
+            print(
+                f"WARNING: creation_rule for secrets/{basename} has no existing "
+                f"'- *alias' line to anchor the insertion point -- add {host} manually.",
+                file=sys.stderr,
+            )
+            continue
+
+        new_line = f"{last_alias_indent}- *{host}\n"
+        lines = lines[: last_alias_idx + 1] + [new_line] + lines[last_alias_idx + 1 :]
+        changed_files.append(basename)
+    return lines, changed_files
+
+
+def remove_keys(lines, hosts):
+    hosts = set(hosts)
+    removed = []
+    kept = []
+    for line in lines:
+        m = re.match(r"^  - &(\S+) age1", line)
+        if m and m.group(1) in hosts:
+            removed.append(m.group(1))
+            continue
+        kept.append(line)
+    return kept, removed
+
+
+def remove_aliases_for_hosts(lines, hosts):
+    hosts = set(hosts)
+    if not hosts:
+        return lines, []
+
+    changed_files = []
+    result = []
+    current_basename = None
+    current_block_changed = False
+
+    def flush():
+        if current_block_changed and current_basename:
+            changed_files.append(current_basename)
+
+    for line in lines:
+        if re.match(r"^  - path_regex:", line):
+            flush()
+            current_block_changed = False
+            m = re.search(r"path_regex: secrets/(.+)\$", line)
+            current_basename = m.group(1).replace(r"\.", ".") if m else None
+            result.append(line)
+            continue
+
+        if current_basename is not None and any(
+            re.search(r"\*" + re.escape(h) + r"\s*$", line) for h in hosts
+        ):
+            current_block_changed = True
+            continue  # drop this alias line
+
+        result.append(line)
+
+    flush()
+    return result, changed_files
+
+
+def main():
+    sops_path = sys.argv[1]
+    edits = json.load(sys.stdin)
+
+    with open(sops_path) as f:
+        lines = f.readlines()
+
+    lines, added_keys = add_keys(lines, edits.get("add_keys", []))
+    lines, added_alias_files = add_aliases(lines, edits.get("add_aliases", []))
+    lines, removed_keys = remove_keys(lines, edits.get("remove_keys", []))
+    lines, removed_alias_files = remove_aliases_for_hosts(
+        lines, edits.get("remove_aliases_for_hosts", [])
+    )
+
+    with open(sops_path, "w") as f:
+        f.writelines(lines)
+
+    changed_files = sorted(set(added_alias_files) | set(removed_alias_files))
+    json.dump(
+        {
+            "added_keys": added_keys,
+            "removed_keys": removed_keys,
+            "changed_secrets_files": changed_files,
+        },
+        sys.stdout,
+    )
+    print()
+
+
+if __name__ == "__main__":
+    main()

scripts/prepare-host-key.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# Generates a new machine's SSH host key by an arbitrary name, before it
+# necessarily has a flake target yet -- prints the .sops.yaml snippet to
+# add by hand. For any host that already has a flake target,
+# scripts/sync-host-keys.sh <target> does this same job plus the
+# .sops.yaml/key_groups registration and re-encryption automatically; use
+# this script only to pre-generate a key ahead of adding the flake target
+# itself.
+#
+# Why a host key is needed at all: sops-nix derives each host's decryption key from
+# its own /etc/ssh/ssh_host_ed25519_key at *activation* time, but that
+# activation runs before systemd would otherwise generate this key on
+# first boot (sshd-keygen is a normal systemd service gated behind
+# multi-user.target; activation scripts run earlier than that). Without
+# pre-seeding, secrets — including the root/nixos login password — fail
+# to decrypt on the machine's very first boot.
+#
+# This script only touches your admin workstation and this repo's
+# .sops.yaml (it never contacts the target machine). Run it, follow the
+# printed next steps, then use the resulting key with the auto-install.sh
+# prompt (see modules/installer/common.nix) when you actually install the
+# new machine.
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "$0")/.." && pwd)"
+
+hostname="${1:?usage: scripts/prepare-host-key.sh <hostname>}"
+sops_yaml="${repo_root}/.sops.yaml"
+
+if [[ ! -f "$sops_yaml" ]]; then
+  echo "ERROR: $sops_yaml not found — is this script still under nixos/scripts/?" >&2
+  exit 1
+fi
+
+keydir="${repo_root}/host-keys"
+mkdir -p "$keydir"
+keyfile="${keydir}/${hostname}_ssh_host_ed25519_key"
+
+if [[ -f "$keyfile" ]]; then
+  echo "ERROR: $keyfile already exists. Remove it first if you want to regenerate." >&2
+  exit 1
+fi
+
+nix-shell -p openssh --run "ssh-keygen -t ed25519 -N '' -C '${hostname}' -f '${keyfile}'" >/dev/null
+
+age_pub="$(nix-shell -p ssh-to-age --run "ssh-to-age -i '${keyfile}.pub'")"
+
+cat <<EOF
+
+Generated: ${keyfile}(.pub)
+
+=== 1. Add this line under keys: in ${sops_yaml} ===
+  - &${hostname} ${age_pub}
+
+=== 2. Add *${hostname} to whichever creation_rules key_groups this host needs ===
+(e.g. secrets/common.yaml always; add a per-host secrets/${hostname}.yaml
+ block too if this host will get its own secrets, same pattern as
+ nix-cache/server.)
+
+=== 3. Re-encrypt every secrets file you just added it to ===
+  nix-shell -p sops --run 'sops updatekeys ${repo_root}/secrets/common.yaml'
+
+=== 4. Commit + push this repo so the flake build picks up the new recipient ===
+
+=== 5. Get the key onto the installer, one of two ways ===
+  a) Rebuild the installer image with all host-keys/ baked in (see
+     docs/auto-installer.md):
+       NIXOS_HOST_KEYS_DIR="${keydir}" nix build .#iso --impure
+     (or .#pxe — --impure is required since host-keys/ is gitignored and
+     flakes can't see it otherwise)
+
+  b) Or, for an image already built without keys, scp it in after boot:
+       scp ${keyfile}{,.pub} root@<target-ip>:/root/host-keys/
+
+Then continue with /etc/auto-install.sh as normal — it checks
+/etc/host-keys (baked in) before /root/host-keys (scp'd) and installs
+whichever it finds before running nixos-install.
+EOF

scripts/sync-host-keys.sh

@@ -0,0 +1,441 @@
+#!/usr/bin/env bash
+# Manages host-keys/ + .sops.yaml + secrets/*.yaml recipients together, so
+# a flake target's SSH host key and its sops registration never drift out
+# of sync with each other or with the flake itself.
+#
+#   sync-host-keys.sh --all                Generate/register every flake
+#                                           target missing a key.
+#   sync-host-keys.sh <target>              Same, for just one target.
+#   sync-host-keys.sh --remove              Interactively remove one
+#                                           locally-managed key.
+#   sync-host-keys.sh --regenerate-all-keys Remove and freshly regenerate
+#                                           every locally-managed key.
+#
+# "Generate/register" is idempotent and additive only: an existing
+# host-keys/ file is never touched, and .sops.yaml only ever gains an
+# anchor/alias it doesn't already have -- safe to re-run any time, e.g.
+# right after adding a new host to flake.nix.
+#
+# --remove and --regenerate-all-keys only ever operate on anchors that have
+# a corresponding host-keys/<name>_ssh_host_ed25519_key file. Anchors
+# without one (&admin, and any anchor for an already-deployed host whose
+# real /etc/ssh key was registered by hand, e.g. &docker/&server/&nix-cache
+# today) are never listed, removed, or regenerated -- this tooling only
+# ever touches keys it itself manages.
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "$0")/.." && pwd)"
+sops_yaml="${repo_root}/.sops.yaml"
+keydir="${repo_root}/host-keys"
+editor="${repo_root}/scripts/lib/sync-host-keys-edit-sops.py"
+
+# shellcheck source=env.sh
+source "${repo_root}/scripts/env.sh"
+
+mkdir -p "$keydir"
+
+usage() {
+  cat <<EOF
+Usage: $0 --all [--dry-run]
+       $0 <flake-target> [--dry-run]
+       $0 --remove [--dry-run]
+       $0 --regenerate-all-keys [--dry-run]
+
+  --all                    Generate + register a host key for every flake
+                            target that's missing one.
+  <flake-target>            Same, for just one target (e.g. lxc-server).
+                            Reports if it already has one.
+  --remove                  Interactively pick one locally-managed key to
+                            remove from .sops.yaml and host-keys/.
+  --regenerate-all-keys     Remove every locally-managed key and generate
+                            fresh replacements for every current flake
+                            target. Destructive -- requires typed
+                            confirmation.
+  --dry-run                 Combine with any of the above: print what would
+                            change (host-keys/ files, .sops.yaml anchors and
+                            key_groups, which secrets/*.yaml would be
+                            re-encrypted) without touching anything. No keys
+                            generated, no files written, no sops calls,
+                            no prompts for confirmation.
+EOF
+}
+
+# --- step 0: make sure we can actually decrypt anything at all -------------
+#
+# Registering a host means editing .sops.yaml and then running
+# `sops updatekeys`, which has to decrypt each secrets file with an
+# existing recipient's key before it can re-encrypt it for the new one.
+# Check this before doing anything else, the same order sops/age itself
+# resolves a usable key in: SOPS_AGE_KEY (inline), then SOPS_AGE_KEY_FILE,
+# then the XDG default path.
+ensure_admin_decrypt_key() {
+  if [[ -n "${SOPS_AGE_KEY:-}" ]]; then
+    echo "Using SOPS_AGE_KEY from the environment."
+    return
+  fi
+
+  local key_file="${SOPS_AGE_KEY_FILE:-${XDG_CONFIG_HOME:-$HOME/.config}/sops/age/keys.txt}"
+
+  if [[ -s "$key_file" ]]; then
+    echo "Found existing sops age key at ${key_file}."
+    return
+  fi
+
+  if [[ "$dry_run" -eq 1 ]]; then
+    echo "[dry-run] No sops age decryption key found (checked \$SOPS_AGE_KEY, \$SOPS_AGE_KEY_FILE, ${key_file})."
+    echo "[dry-run] Would generate a new one here -- continuing the dry run without one; any"
+    echo "[dry-run] 'would re-encrypt' output below couldn't actually run for real yet."
+    return
+  fi
+
+  echo "No sops age decryption key found (checked \$SOPS_AGE_KEY, \$SOPS_AGE_KEY_FILE, ${key_file})."
+  echo "Generating a new one at ${key_file}..."
+  mkdir -p "$(dirname "$key_file")"
+  nix-shell "${NIX_OPTS[@]}" -p age --run "age-keygen -o '${key_file}'" 2>&1 | grep -v "^Public key:" || true
+  local new_pub
+  new_pub="$(nix-shell "${NIX_OPTS[@]}" -p age --run "age-keygen -y '${key_file}'")"
+
+  cat <<EOF
+
+A brand-new age key was just generated -- it cannot decrypt anything that
+already exists in secrets/*.yaml, since nothing was ever encrypted for it.
+That trust can't be bootstrapped automatically (nobody can decrypt a file
+for a recipient that didn't exist when it was last encrypted).
+
+To actually use this key:
+  1. Have someone who currently CAN decrypt replace the &admin entry in
+     .sops.yaml with this public key:
+       ${new_pub}
+  2. They re-encrypt every secrets/*.yaml:
+       sops updatekeys --yes secrets/common.yaml
+       sops updatekeys --yes secrets/nix-cache.yaml
+       sops updatekeys --yes secrets/server.yaml
+  3. Re-run this script.
+
+Exiting without making any other changes.
+EOF
+  exit 1
+}
+
+discover_targets() {
+  nix eval --json --no-use-registries --no-accept-flake-config \
+    "${repo_root}#nixosConfigurations" --apply builtins.attrNames \
+  | jq -r '.[] | select(. != "installer")'
+  # installer is the one nixosConfigurations target that doesn't import
+  # sops-nix at all (see CLAUDE.md's "Security Notes" -- hardcoded login
+  # password instead) -- config.sops.secrets doesn't exist for it.
+}
+
+locally_managed_hosts() {
+  for f in "$keydir"/*_ssh_host_ed25519_key.pub; do
+    [[ -e "$f" ]] || continue
+    basename "$f" _ssh_host_ed25519_key.pub
+  done
+}
+
+add_keys_json="[]"
+add_aliases_json="[]"
+dry_run=0
+
+queue_host_sync() {
+  local host="$1"
+  local keyfile="${keydir}/${host}_ssh_host_ed25519_key"
+  local has_local_key=0 has_anchor=0
+  [[ -f "$keyfile" ]] && has_local_key=1
+  grep -qE "^  - &${host} age1" "$sops_yaml" && has_anchor=1
+
+  if [[ "$has_local_key" -eq 0 && "$has_anchor" -eq 1 ]]; then
+    echo "SKIP ${host}: .sops.yaml already has an &${host} anchor, but"
+    echo "     host-keys/${host}_ssh_host_ed25519_key is missing locally."
+    echo "     Not generating a replacement -- it wouldn't match whatever's"
+    echo "     already registered (and possibly deployed). Remove the"
+    echo "     &${host} line from .sops.yaml first if you really want a"
+    echo "     fresh key, then re-run."
+    return 1
+  fi
+
+  if [[ "$has_local_key" -eq 0 ]]; then
+    if [[ "$dry_run" -eq 1 ]]; then
+      echo "[dry-run] ${host}: would generate host key"
+    else
+      echo "==> ${host}: generating host key"
+      nix-shell "${NIX_OPTS[@]}" -p openssh --run "ssh-keygen -t ed25519 -N '' -C '${host}' -f '${keyfile}'" >/dev/null
+    fi
+  else
+    echo "==> ${host}: host key already present"
+  fi
+
+  if [[ "$has_anchor" -eq 0 ]]; then
+    local age_pub
+    if [[ "$dry_run" -eq 1 ]]; then
+      age_pub="dry-run-placeholder-not-a-real-key"
+    else
+      age_pub="$(nix-shell "${NIX_OPTS[@]}" -p ssh-to-age --run "ssh-to-age -i '${keyfile}.pub'")"
+    fi
+    add_keys_json="$(jq --arg host "$host" --arg key "$age_pub" \
+      '. + [{host: $host, age_key: $key}]' <<<"$add_keys_json")"
+  fi
+
+  echo "==> ${host}: checking which secrets files it references"
+  local basenames
+  mapfile -t basenames < <(
+    nix eval --json --no-use-registries --no-accept-flake-config \
+      "${repo_root}#nixosConfigurations.${host}.config.sops.secrets" \
+      --apply 'builtins.mapAttrs (n: v: baseNameOf v.sopsFile)' \
+    | jq -r '[.[]] | unique | .[]'
+  )
+  local basename
+  for basename in "${basenames[@]}"; do
+    add_aliases_json="$(jq --arg host "$host" --arg basename "$basename" \
+      '. + [{host: $host, basename: $basename}]' <<<"$add_aliases_json")"
+  done
+}
+
+# In dry-run, this runs the exact same edit logic (so idempotency/what's-
+# actually-new is determined for real, not guessed) but against a scratch
+# copy of .sops.yaml that's discarded afterward -- the real file is never
+# opened for writing, and `sops updatekeys` never runs.
+apply_edit_plan() {
+  local plan="$1"
+  local target="$sops_yaml"
+  local tmpfile=""
+  if [[ "$dry_run" -eq 1 ]]; then
+    tmpfile="$(mktemp)"
+    cp "$sops_yaml" "$tmpfile"
+    target="$tmpfile"
+  fi
+
+  local result
+  result="$(echo "$plan" | nix-shell "${NIX_OPTS[@]}" -p python3 --run "python3 '${editor}' '${target}'")"
+  [[ -n "$tmpfile" ]] && rm -f "$tmpfile"
+
+  local added removed changed
+  added="$(jq -r '.added_keys[]?' <<<"$result")"
+  removed="$(jq -r '.removed_keys[]?' <<<"$result")"
+  changed="$(jq -r '.changed_secrets_files[]?' <<<"$result")"
+
+  if [[ -z "$added" && -z "$removed" && -z "$changed" ]]; then
+    echo "Nothing changed in .sops.yaml."
+    return
+  fi
+
+  local prefix=""
+  [[ "$dry_run" -eq 1 ]] && prefix="[dry-run] would "
+
+  [[ -n "$added" ]] && echo "${prefix}Add .sops.yaml anchors: $(tr '\n' ' ' <<<"$added")"
+  [[ -n "$removed" ]] && echo "${prefix}Remove .sops.yaml anchors: $(tr '\n' ' ' <<<"$removed")"
+
+  if [[ -n "$changed" ]]; then
+    if [[ "$dry_run" -eq 1 ]]; then
+      echo "[dry-run] would re-encrypt:"
+      while IFS= read -r basename; do
+        [[ -z "$basename" ]] && continue
+        echo "  secrets/${basename}"
+      done <<<"$changed"
+    else
+      echo "Re-encrypting affected secrets files..."
+      while IFS= read -r basename; do
+        [[ -z "$basename" ]] && continue
+        echo "==> secrets/${basename}"
+        nix-shell "${NIX_OPTS[@]}" -p sops --run "sops updatekeys --yes '${repo_root}/secrets/${basename}'"
+      done <<<"$changed"
+    fi
+  fi
+}
+
+flush_additions() {
+  if [[ "$add_keys_json" == "[]" && "$add_aliases_json" == "[]" ]]; then
+    echo "Nothing to do -- every requested target already has a fully registered host key."
+    return
+  fi
+  echo
+  echo "Applying .sops.yaml edits..."
+  local plan
+  plan="$(jq -n --argjson add_keys "$add_keys_json" --argjson add_aliases "$add_aliases_json" \
+    '{add_keys: $add_keys, add_aliases: $add_aliases}')"
+  apply_edit_plan "$plan"
+  echo
+  if [[ "$dry_run" -eq 1 ]]; then
+    echo "[dry-run] Nothing was changed. Re-run without --dry-run to apply this."
+  else
+    echo "Done. Review the .sops.yaml / secrets/*.yaml diff, then commit and push --"
+    echo "the flake build the installer uses has to see the new recipient(s) before"
+    echo "any of these hosts can decrypt their secrets on first boot."
+  fi
+}
+
+cmd_all() {
+  echo "Discovering flake targets..."
+  local targets
+  mapfile -t targets < <(discover_targets)
+  local host
+  for host in "${targets[@]}"; do
+    queue_host_sync "$host" || true
+  done
+  flush_additions
+}
+
+cmd_target() {
+  local host="$1"
+  local targets
+  mapfile -t targets < <(discover_targets)
+  if ! printf '%s\n' "${targets[@]}" | grep -qxF "$host"; then
+    echo "ERROR: '${host}' is not a current nixosConfigurations target." >&2
+    echo "Current targets:" >&2
+    printf '  %s\n' "${targets[@]}" >&2
+    exit 1
+  fi
+  queue_host_sync "$host" || exit 1
+  flush_additions
+}
+
+cmd_remove() {
+  local hosts
+  mapfile -t hosts < <(locally_managed_hosts)
+  if [[ "${#hosts[@]}" -eq 0 ]]; then
+    echo "No locally-managed keys in host-keys/ -- nothing to remove."
+    return
+  fi
+
+  echo "Locally-managed keys:"
+  local i=1 host
+  for host in "${hosts[@]}"; do
+    local registered="not registered in .sops.yaml"
+    grep -qE "^  - &${host} age1" "$sops_yaml" && registered="registered in .sops.yaml"
+    printf '  %d) %s (%s)\n' "$i" "$host" "$registered"
+    i=$((i + 1))
+  done
+
+  local choice
+  read -rp "Remove which one? (number, or blank to cancel): " choice
+  if [[ -z "$choice" ]]; then
+    echo "Cancelled."
+    return
+  fi
+  if ! [[ "$choice" =~ ^[0-9]+$ ]] || (( choice < 1 || choice > ${#hosts[@]} )); then
+    echo "ERROR: invalid selection." >&2
+    exit 1
+  fi
+  local target="${hosts[$((choice - 1))]}"
+
+  if [[ "$dry_run" -ne 1 ]]; then
+    read -rp "Really remove '${target}'? Its host-keys/ files will be deleted and it will lose access to every secrets file it can currently decrypt. (y/N): " confirm
+    if [[ ! "$confirm" =~ ^[Yy]$ ]]; then
+      echo "Cancelled."
+      return
+    fi
+  fi
+
+  local plan
+  plan="$(jq -n --arg host "$target" \
+    '{remove_keys: [$host], remove_aliases_for_hosts: [$host]}')"
+  apply_edit_plan "$plan"
+
+  if [[ "$dry_run" -eq 1 ]]; then
+    echo "[dry-run] would delete host-keys/${target}_ssh_host_ed25519_key(.pub)."
+    echo "[dry-run] Nothing was changed. Re-run without --dry-run to apply this."
+  else
+    rm -f "${keydir}/${target}_ssh_host_ed25519_key" "${keydir}/${target}_ssh_host_ed25519_key.pub"
+    echo "Removed host-keys/${target}_ssh_host_ed25519_key(.pub)."
+    echo
+    echo "Review the diff, then commit and push."
+  fi
+}
+
+cmd_regenerate_all() {
+  local hosts
+  mapfile -t hosts < <(locally_managed_hosts)
+  if [[ "${#hosts[@]}" -eq 0 ]]; then
+    echo "No locally-managed keys in host-keys/ -- nothing to regenerate."
+    return
+  fi
+
+  echo "This will remove and freshly regenerate ALL locally-managed keys:"
+  printf '  %s\n' "${hosts[@]}"
+  echo
+  echo "Every host above will need its new key baked into a rebuilt install"
+  echo "image/tarball before it can decrypt secrets again."
+
+  if [[ "$dry_run" -ne 1 ]]; then
+    read -rp "Type REGENERATE to confirm: " confirm
+    if [[ "$confirm" != "REGENERATE" ]]; then
+      echo "Cancelled."
+      return
+    fi
+  fi
+
+  echo
+  local hosts_json
+  hosts_json="$(printf '%s\n' "${hosts[@]}" | jq -R . | jq -s .)"
+  local plan
+  plan="$(jq -n --argjson hosts "$hosts_json" \
+    '{remove_keys: $hosts, remove_aliases_for_hosts: $hosts}')"
+  apply_edit_plan "$plan"
+
+  if [[ "$dry_run" -eq 1 ]]; then
+    echo "[dry-run] would delete ${#hosts[@]} host-keys/ file pair(s)."
+    echo "[dry-run] would then generate fresh replacements for the same hosts"
+    echo "[dry-run] (not simulated further here -- run without --dry-run, or"
+    echo "[dry-run] preview a specific target with: $0 <target> --dry-run)."
+    echo
+    echo "[dry-run] Nothing was changed. Re-run without --dry-run to apply this."
+    return
+  fi
+
+  echo "Removing existing keys..."
+  local host
+  for host in "${hosts[@]}"; do
+    rm -f "${keydir}/${host}_ssh_host_ed25519_key" "${keydir}/${host}_ssh_host_ed25519_key.pub"
+  done
+  echo "Removed ${#hosts[@]} host-keys/ file pair(s)."
+
+  echo
+  echo "Regenerating fresh keys for every current flake target..."
+  cmd_all
+}
+
+main() {
+  local args=()
+  local arg
+  for arg in "$@"; do
+    if [[ "$arg" == "--dry-run" ]]; then
+      dry_run=1
+    else
+      args+=("$arg")
+    fi
+  done
+  set -- "${args[@]+"${args[@]}"}"
+
+  if [[ "$dry_run" -eq 1 ]]; then
+    echo "[dry-run] no changes will be made"
+    echo
+  fi
+
+  nix_extra_opts
+  ensure_admin_decrypt_key
+
+  case "${1:-}" in
+    --all)
+      cmd_all
+      ;;
+    --remove)
+      cmd_remove
+      ;;
+    --regenerate-all-keys)
+      cmd_regenerate_all
+      ;;
+    -h | --help | "")
+      usage
+      ;;
+    --*)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+    *)
+      cmd_target "$1"
+      ;;
+  esac
+}
+
+main "$@"

secrets/common.yaml

@@ -5,40 +5,76 @@ sops:
     age:
         - enc: |
             -----BEGIN AGE ENCRYPTED FILE-----
-            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSB6NkpZRzJuMFNuV09WamR0
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBpWjNSdEdZbUUzamswa08w
-            SERDN0VSUlNQbkhSem1EeFlxdlhmdUx0S21JCnY1VkRBQTBqcW9JRHpJWEtJSitN
+            aCtzSHB0bFVZMnYxTkpuM1psdVYzWW55SzMwCkliMWVOUlBqRG5wOGZjQVg4MkFz
-            dHkyR0I4ckNkWkpGWHAzZGRaZkhJalEKLS0tIHRrU3RhU3UxN3B4NHdLeStuSXQ4
+            NEVkMXdkTjhWRlZmVGlzZElid2pUMXMKLS0tIGtHUmRCNXNhVmloUHYzQnE5YlBS
-            anFkRlpMTHowZzJNdnY0MExQcXd4OUEKgbT7uOSFkfEs6t3X6jmGOiC28lDJWF33
+            YnVSQjJlT3JnQ1RNMm9xV2xKOGRZUDAKc4VTl9NEI9Rv8+4J3JTeHTt2h8Dr2IJv
-            50f2fZ771ylhHa6WJMetGZ5cwl9r1RCaDiWyJEaqNGe7NqARlhr3EQ==
+            tfvoNJQM/w6RAJWNTkaDmzZa9OnUW+grDlBQKlDuAnr6fZmuNTH2hQ==
             -----END AGE ENCRYPTED FILE-----
           recipient: age10nd382a9klsn2mrs60emdtsxe43pht3a0m9p29phfrhy0wfyt3vsq9r667
         - enc: |
             -----BEGIN AGE ENCRYPTED FILE-----
-            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBDamw2ekY0dFZyOGNJelVa
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBOR25UN1c0aE5SYWphbU0y
-            ZGlNK2VNOWtWNTRzU3o2aVJvRi9CME5yS1JFCndlamdFMzVRTnoyVE1ZWXZkTjRR
+            SHRTZ1B0WC9NU3Z5VHpzTXpLSUxHTDI1ZFE0CnFpYUN1eGZQejJMblZPd1ROeUth
-            eWdSZzZERHE5VElrOGZvcE4vK0g2d0EKLS0tIG15QlVyalZTK2NpVDdWWU4yUU4r
+            dklZYVVNa1ZNZ1d4dW9vMCsvQWp1RkEKLS0tIERxakx5L0JrQitib1EyNDRMbDQ5
-            SkFncC9rZkNKUS9MSmF6WGQwOENwZTQKs5kLNLdQJoZtcsw3zlUWUUtJs0MJnuvw
+            Z3hDWUFEazdxczVhaHJYK3VZeEJSSDgKkw9T4ZuT+VHIF4WopqRHt8vW30kOysJ3
-            o5vziOswRnuXENw//xN01nMDC6Ckzvb+q9GFIyxHLE4j3fT5XdZakg==
+            vOq6EZ3Fqkgmoxm69Zp2gFnuE9GZIBy3VPQVLU2k6dZGJ3IvmLYeBA==
             -----END AGE ENCRYPTED FILE-----
           recipient: age19gfn2yedg76dmztm4hncr7vf3r3c9j0qpt4rap7y7gersjk4m3ks2lhd0e
         - enc: |
             -----BEGIN AGE ENCRYPTED FILE-----
-            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSAyaWpWTGd4TEVoaHg4b3hm
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSA0THJzMFBTTCtDMWRmZ25M
-            S1o3VXdkYkZCS0QxcW5hUWxyVjFneE5aSmp3ClNsdEZoMHpPUzI4K3B0ZnBYMlEw
+            dU55OVhBb0trWWRUNlArTnEzRjhiYngvRENNCjF4d0M5NlYyQW50TTdMRXpuUjRr
-            MkJyd2NPcGJDZzgvc1EyWFBhNVlGUVEKLS0tIEptYXI2bnJHZVZGR3hSSm1sMlN5
+            M1NwV05JOHV6T2cxT2FheVpuZ0w2T0kKLS0tIFBxdlVpVEoxOUpSWjk1ejRsK1NM
-            ay8wdUh6TEowL0ZiUWtqbXl3NzhYOVEKW9l4mr+MLhuXA8sgQndaU8NiFeCMcxhG
+            V1UwTU1scG91L2FIemtwSW5JbFlmeG8K/1WIlaIidy3x3ptoRpS/DG88064LQ6Mq
-            qjKFn+mu2GFbwfZWAy6y/KUd9Ug4H6y3pNHlJMHupTu8v2wZ+3S4EA==
+            GbfB0jfq5PILDQMMuZu5oIBY31SxwnhZ02Ns7gA67kgNIRSCmk9WyQ==
             -----END AGE ENCRYPTED FILE-----
           recipient: age1ll6hj5ggruetgjwjfnplpn5xtq35uhlcdflksx3xmnjm6s3uad9sz70jkf
         - enc: |
             -----BEGIN AGE ENCRYPTED FILE-----
-            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSAxVG13RVVweGpRM04vMWxG
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBmRURQVGw1a1E1MkIzV2pa
-            V2hMMnp2Qk5Ub1BZQWNKNXVya3J4NGpreDJrCktqajVPRXdEL1BMU1dMbDhmU01L
+            RG5HSkM0c0huUGVWcnFZOGlacGlGOHFMTVFrCm5OS09HRFc3TGVUYmtzTStxL0Q5
-            UlQvRVQvcEFUZVZ5Umc3Y0hMUWNLVFEKLS0tIFgzRnF1RHdQdktDVjROSURYYTdx
+            N2hRMEcxUE9MTmZXL0wvME5EZXF1Z00KLS0tIHdHMVVHcTZzMmdXU0s4QlVqSS9Y
-            NjAydjVuV1VCOGZoVFdTZmw1YmJ0eEEKN9KRGegafu1sjHlhyn4KCMPPAKxsSZLc
+            ZUVmcWhPaURIUFJGR0V4bUZwKzM1bm8KlvGMNEClbLlfvJqNQHhd0dI4ihShLChF
-            QJkei1ZQ0AVgC2QfCVEXonMOrs45nCIplG+uyER9khZyyjKObWk1pA==
+            GI/fydgrBruw3Otv6KLZu3CBC7iNcKlvZxz+YGD2qbicmyQ5hAhDSQ==
             -----END AGE ENCRYPTED FILE-----
           recipient: age120le4a5l8dh3lyfgvmj3d9ksmej6ajs5mer5y7r0vfg3x9fn69dqf8xgzu
+        - enc: |
+            -----BEGIN AGE ENCRYPTED FILE-----
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSA5bWpFenBlQldna3RhSFpr
+            bEJBaHJDMzM3OHlqTmozcWU0VDM1bTFUWFZzCnZtNHZjZ1U1RzNkUlBHZFozWXdt
+            VVkxQjMvTDJtbFZnclpkUEd4TEVmNTAKLS0tIFlhV2ZSSzJLRVNoMmFyVktDOElR
+            YUxqZUFoY1ZWeGlldGplMjVQa1A5aUUKWelY6yO7Mr6dRvj4MVMbq/Z9JgrAnahz
+            BDhHqObzJrOCtfDCTWiYuP+0yvIFWItMWhGSMw9MwwivvwnrEa+ZuQ==
+            -----END AGE ENCRYPTED FILE-----
+          recipient: age1qz9d4ka4xgexujyd247s7lp737sulp5fhxl5d65fj2ykvc4j4edqrsdks8
+        - enc: |
+            -----BEGIN AGE ENCRYPTED FILE-----
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBiK2hKb2VaVnoyaEVYUHZZ
+            OWVUSGtONGs5dEljTjJQdlhEcjNjdjViT2pVCkpaOHVZMlpXOFRveVlMeXZqWmoz
+            ZHJRQTR2dmJQSEozeTRGMEdUdFlmZ2MKLS0tIERWS1RVdW1jQytBZzlkb3puNjhH
+            ZjdlZmtzNXVOQ25DeCthUzhRRm1MT2cKaxc7zGm57iJFSeYc2IPqF4Eaxa44nR37
+            pWZw+erG4F9AAZ2F047q+oLKe0B8FLSF54IbcXdQhitgGNR7B2HVeA==
+            -----END AGE ENCRYPTED FILE-----
+          recipient: age120whqj96g26lsgy4udvgsn8dc9lumh8jeu3a564fx79rjr5lxffqmrljuu
+        - enc: |
+            -----BEGIN AGE ENCRYPTED FILE-----
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSA1ekhUTG5VOFErL3pFeWZM
+            RG9NVnN6NFl3bzlFeTQzdHFtZmhwem04alQ0ClpJRStObERMZ0w2V0NhR1FSeW96
+            M1d2V2NjUkUrLzN2ZVNSbGY4bll5WmsKLS0tIC94dVFQcXJ6d3pLU0VHNEFGR0ls
+            a1Q2UmNuSjVMNG5XZGZKV1VmNHFPQXcKQJrZGw/9fPnXeFZ4omrkEgrzwplhwvRW
+            i0FXuepoU353sR7enyL34qPoOdm05ivowuPKNzkq8D4i5AF6vGv+YA==
+            -----END AGE ENCRYPTED FILE-----
+          recipient: age164px2a8e48ptsf9ngtan38aa6jls4jdl26mzrgzf6sn3vcvt49hqjrgr8w
+        - enc: |
+            -----BEGIN AGE ENCRYPTED FILE-----
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBoZ2lHM2RBQ3lUK216dkcr
+            Y3RrcXR3QTdFVjJRWlhpQWVFQ1cyZWNabkRFClAwRi9PSHF5ZWFSUzJuRXF3bU1R
+            b0U5TFRZaFdmR1NMS3RRT3E3M2hUdE0KLS0tIEtrUy8ydkNyVHBiOVR6WEdjV2VN
+            NVJHUVgwRkhxcmlwcFkrRlFwTEF6YVkKzXyJk0UnmUsvb+NzNVcf/gf7OEEt3P/K
+            OIGxDrGfs/zNQgeKXNbQlQ4p4jOaybG8aCmX+A4qTk6/I8yY8LTJWg==
+            -----END AGE ENCRYPTED FILE-----
+          recipient: age10at8862478urh0eeuwh8hzln6ck78jgwtztgxatwqlzwagg77y5snm4xzg
     lastmodified: "2026-07-19T02:30:40Z"
     mac: ENC[AES256_GCM,data:UiL3VMDF6rq4Nr87KspcDx434q3tfNXeb5pwH2O+4ssNQ6xzcYDdzXBnhAY3zLBsqPMKrvHBd4Ot/gEMcq3FMIVe7Q6p9yWKpep66KZ/yWEhAlwIVhD79Oj8VS+1CHKjf25zpRdhZorp04oeFQQd9VfjJB4EE/Q1aVbwTGlpIic=,iv:i/0conaFgFia+wzNTdUL6tlSTw35HTK3Ap1Sr5RGHf8=,tag:ULbz5FllShA/JjlSRdxA0g==,type:str]
     unencrypted_suffix: _unencrypted

secrets/nix-cache.yaml

@@ -1,25 +1,35 @@
 beszel-token: ENC[AES256_GCM,data:meuzUP/6wCssJDVTgbC0XwiLZPMGyDl55HEIiON9xOXCD9k6,iv:TDqWcp+8Mxd8wN09r5otQRQXq3XTeQphaTWxvvuLTAs=,tag:cRPZQGlwB/dTguBAheWPQg==,type:str]
+cache-priv-key: ENC[AES256_GCM,data:6vQKIf7eS0WNL2Eptoi4VWr18SRMZfN/H/aFUUtXdMYQY5LLyBp2EHRKqZcGFuh1nZhUdAxUztq/CVXx+QFxKW+ElHxCxUSp0QqI1fdSkBkKZb8hlit5SoX9JtLzZGg0HBNM3nJu,iv:0J+xmrPJhInHhFR/c41ACjuTfaIoMkQFSfbL2KkgFa8=,tag:f4s9Szs5oprVVRSyXaX48A==,type:str]
 sops:
     age:
         - enc: |
             -----BEGIN AGE ENCRYPTED FILE-----
-            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBkb29VM3haQ0c0WDY0STVn
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBDbHd1Y1dpa2ZiQ2E1bXRP
-            L1ZyOUROSnR6ZjZZZWc1VGFFNVp6bWxCV3hZCnlGTC9CbEtIM3MvSGJQaStEbzJ0
+            SnkrWHI0V2U1eGFKY0RZamZQQjluS0hGeENZCmduUFQyd1Q5RkZGMGFoenJhNmZh
-            eWVhY2l6UHNDRTYxdEpkd003WXFia2MKLS0tIHcxU3FPYTVuZ0RqZTZTT1RvZnN0
+            VmZ2OStNaFpJejFxQ2JUZXFpNThaMncKLS0tIEhJdGdQeXEzb25Nbk5YZktCWVUz
-            OGlQM3B2R0l4MHhWNXBBWmpiOEVxK1EK8kxh3ikKL6Fw2am3r7lPGpB0fCqzEukO
+            NUJDUWRoTkd5R2pFblZjS0NSbVR5dkkKDYeW+zRpha04/CasFM91K6v1PpkNGHRu
-            NU10Cbf38Bd+fybRbBnvRuu9To1FOf+KU3iKbsuWmZn4KJn4Ajcbhw==
+            qAoKs9KSg9VxS7ya8RuLmylKRdpPkupm/8SXIJvQuCXp5LWmNJ4zkA==
             -----END AGE ENCRYPTED FILE-----
           recipient: age10nd382a9klsn2mrs60emdtsxe43pht3a0m9p29phfrhy0wfyt3vsq9r667
         - enc: |
             -----BEGIN AGE ENCRYPTED FILE-----
-            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBCNWRhK2QrV1ZibllqY25Y
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSB4UktiUUdmd092bnZMdFMz
-            ZVRPLzZ0TE82TWZ4L0w5ZmFPTDBtT0poODBnCkE5TWhJcXJjNkdva1hYZ3loeVdq
+            Q05xVlhnNzhPZUY4TjF5bjRCbklacTdJd1RBCnJ4bEVMaWRLZExIUFVEUDBXTnlV
-            UlBXWHZpRUpMSGhPU0FIRi9JMEtTdGMKLS0tIE9yUk5Ebjk2MEFtNEkyR3RDcU51
+            MDU4WUk5VlJjdlhVUVpzZXlnWHhqTjQKLS0tIE9iclhGVElPcU9OLzF0bEVjMjVp
-            ZVMwNnNRMlBMVVFlamU1U3JQSy9UT00KJZdEpRHuj4Dp1dGwP1z4xi9oddQOrQj2
+            YzlQTGFYZEhLdTk3N3ZramVjVGRXREUKjOjqO/jX5iEKN43WiJ8qS/1mDfxdj8uO
-            qheEN/IlifVdZDpvlLUc8jgLzd/TO5EeEhVqfbdrlua8FHly29oTNw==
+            K7Yyc/Yj0qMvGwLNzphjmbT29P7dXk4Ht4TedqCd+8DfhpOgLVIaSA==
             -----END AGE ENCRYPTED FILE-----
           recipient: age120le4a5l8dh3lyfgvmj3d9ksmej6ajs5mer5y7r0vfg3x9fn69dqf8xgzu
-    lastmodified: "2026-07-19T02:30:40Z"
+        - enc: |
-    mac: ENC[AES256_GCM,data:7+FeT6aeCGn+JFBXbPO0qP4BJ1nHPSennewv1kWkG+hOTIqs1ymuswUK1Hyfi6Z9h2umFX9HvK+o3qtmYvk6k7BUNe6w6QUHTNwm6lmNqrb7sgAE3iFVI2p9m14NGhgoTfnXx1M4JIZ1iuNYhCukpENI4+svIe+r7x5YeE5Evac=,iv:4AKAPI6upyAvHBr8BLWX7R/NupmJdcXdqiN8e0ZQ3ls=,tag:TkpfpCaLhn+Mx5cQZZuMdA==,type:str]
+            -----BEGIN AGE ENCRYPTED FILE-----
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBjaXpvQU9yRUc3ektPMmU5
+            Q0xLWU9mYXVOeTVBNGNsZzJPa1lkVlRUZHlvClhoSVV6YjB1Q3pTTzVvNFlNYkU4
+            Y2RrbFk5SUFKSDVjeFU0Wlc2aGFUMFUKLS0tIDlVeXM4WWRUakg4Zk5mcjdJL3VC
+            S1k5eFBpVnREQlZwYllpeTNhWW5GS1EKi2sMwyJJ0D8acjCZmxlcwdU1sglBuxR7
+            2SEMsctdGC+5E3ilPXvPpZ5RONZHbXxn6kQRBlBv6AJERpGDzsfgfA==
+            -----END AGE ENCRYPTED FILE-----
+          recipient: age164px2a8e48ptsf9ngtan38aa6jls4jdl26mzrgzf6sn3vcvt49hqjrgr8w
+    lastmodified: "2026-07-19T23:30:21Z"
+    mac: ENC[AES256_GCM,data:kLGE2xawQT7mx+sfw68hmGk5nCEGiEjZrqTEl9B1dtQmTrMwmoVr/1RISi4LfJrwxy31mDgff4lcIL4wIJuM373uk3X8j4RNyYQNTfKEkORT6r8NHeepNs267O77pKGd7OmcM4MT/BqOnB8ELS7Wlf2ect7CAlvUUVyc8icxgZE=,iv:EYLDsHYHZ1XOQXafOTqHHWpk/OBNq/R6IJnOBYV33E4=,tag:thxrCPC5oGvDjhK7Dz87YA==,type:str]
     unencrypted_suffix: _unencrypted
     version: 3.13.1

variables.nix

@@ -0,0 +1,159 @@
+{
+  # Network / domains
+  lanDomain = "gitea.lan.ddnsgeek.com"; # Gitea/DDNS domain
+  homeDomain = "sweet.home"; # base LAN domain for service subdomains (pve., docker.)
+  tailnetDomain = "tail13f623.ts.net"; # Tailscale MagicDNS suffix
+  lanCidr = "192.168.2.0/24"; # LAN subnet
+  pxeServerIp = "192.168.2.247"; # pxe-boot host's LAN IP
+  pbsIp = "192.168.2.108"; # Proxmox Backup Server LAN IP
+
+  # Cross-host references (LAN hostnames/users other hosts reach over the network)
+  nixCacheHost = "nix-cache"; # substituter/remote-builder hostname
+  nfsServerHost = "server"; # NFS export source hostname
+  dockerHost = "docker"; # docker-compose stack host
+
+  # Raspberry Pi's own Tailscale hostname (not fronted by `server` — it
+  # exports its own NFS share directly). Resolved as
+  # "${raspberryPiHost}.${tailnetDomain}" in modules/raspi/mount-data.nix.
+  raspberryPiHost = "raspberrypi";
+
+  remoteBuilderUser = "nixremote"; # remote builder SSH user
+
+  # nix-cache's own SSH host public key (not a secret — the private half
+  # never leaves the host). Wired into every client's
+  # programs.ssh.knownHosts by modules/nix-cache/remote-builder-client.nix
+  # so distributed builds don't hit "Host key verification failed" on a
+  # fresh client that has never manually ssh'd to nix-cache before. Update
+  # this if nix-cache's host key is ever rotated or the host is rebuilt
+  # from scratch.
+  nixCacheHostKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHrMKZlIGUd3pH9G3AqbsruqUGjxIXMAZw52u9MwiBCn lxc-nix-cache";
+
+  # Public keys authorized to SSH in as remoteBuilderUser on the nix-cache
+  # host (modules/nix-cache/server.nix) — one per client host that's allowed
+  # to use it as a distributed builder.
+  remoteBuilderAuthorizedKeys = [
+    "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIFDEA1S2ikpObREgbP5uVBWMxIOGbY8B+Wx7VTZK1m6t root@server"
+    "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPAYIT9ormlmxZ0SziyDQaUntnKI8HK9/s3Qac1ZKjP2 root@docker"
+    "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKKKzoEPl/ZW9KBRHBcp6/ThOngGpwMv5EhkTlgC4aDf root@nixos"
+    "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIGtOWOCS+ImHc7NehguoyD7PbonGosKMZqc9+QR3v/h root@nixos"
+    "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHxXTQxFnArK5HXG7czeoybZebCGfxpUdusJkPn+BCSp root@server"
+    "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICMJhrfFayLBG+gWtO6oAvgambw5nWWgztiTFEaaaVRH debian@surface"
+  ];
+
+  # Admin SSH public key, authorized on the primary user of every host and
+  # the installer image's nixos/root users.
+  adminSshKey = "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCq/Q5LvIXlZwO2kdeAN5nLGZ59nZB7JHYMEszHxmNtGMzv1lM31jiPNsr0z2EKVZhE7OOfa2IF9rhWYD7JUA9G0yzdZ4WTXFNGVVOJoOVH6vAF3XCxoVilOEwTc7h2Wiy+rzd0B28/3spffzQQWJhY6GRQVa8j+6xAGF60Fcvl1vLosYT9Bn2ZbK4TCWOwAn2jqXIieGpZdn/UNZbGOeKRiCvhktDfMAzuQzN/9jMu/oF4pkPn2X1UrsQdNlvp0Ci8md612MozIpncQJyAF1ADhunr3sMx0isUXiqD29R5DS4TftpekqLNLak+zcxFa8N7DcRNp3DcKfJvyTkwQrR4r+b7lFLYOLHLagSso9CzeW/paAS2q9I5SBm/2DtE1diLLg2jZikYcstsu/G5RgvbzbKqjiaMwTdXC3AMvDxQrs7U5pDRZFzoofG3cpODbTm+uy3m0kP70z0M1K45UbDG0p+itnTu9x40JbQEgefbx38AItNvAIx1A8HO4I1VX28= wayne@stream";
+
+  # System
+  timeZone = "Australia/Brisbane";
+
+  # Main interactive user on every host. Every module that grants this user
+  # a group, a home directory, or tmpfiles ownership should reference
+  # vars.primaryUser rather than the literal "nixos", so renaming it is a
+  # one-line change.
+  primaryUser = "nixos";
+
+  # Storage
+  storageRoot = "/tank"; # ZFS pool root on `server`
+
+  # NFS datasets exported from `storageRoot` on `nfsServerHost` and mounted
+  # by client hosts. `subpath` is relative to `storageRoot` — combined with
+  # it to build both the export line in modules/build-types/server.nix and
+  # the "<nfsServerHost>:<storageRoot>/<subpath>" device string each client
+  # mount uses in modules/docker/mount-data.nix. `mountpoint` is the
+  # absolute local path clients mount it at, referenced by that same file's
+  # fileSystems attribute name plus every other place that needs to know
+  # where the share lives locally (modules/build-types/docker.nix's
+  # tmpfiles rules, modules/traefik/rotate-logs.nix's log path). Renaming a
+  # dataset or moving where it's mounted only needs changing it here — the
+  # export and every client reference follow automatically.
+  nfsShares = {
+    dockerConfig = {
+      subpath = "docker/config";
+      mountpoint = "/mnt/docker/config";
+    };
+    dockerDatabases = {
+      subpath = "docker/databases";
+      mountpoint = "/mnt/docker/databases";
+    };
+    dockerVolumes = {
+      subpath = "docker/volumes";
+      mountpoint = "/mnt/docker/volumes";
+    };
+    nextcloudData = {
+      subpath = "docker/nextcloud-data";
+      mountpoint = "/mnt/nextcloud-data";
+    };
+    raspiVolumes = {
+      subpath = "raspi/volumes";
+      mountpoint = "/mnt/raspi-backup";
+    };
+  };
+
+  # The Raspberry Pi's own NFS export — not under storageRoot/nfsServerHost,
+  # served directly by the Pi itself over Tailscale (see raspberryPiHost
+  # above) and mounted at raspiMountpoint by modules/raspi/mount-data.nix.
+  raspiNfsPath = "/home/raspi/raspi";
+  raspiMountpoint = "/mnt/raspi";
+
+  # Every literal port referenced from modules/ or hosts/, grouped by the
+  # service/host that opens or connects to it — kept as separate entries
+  # even where two happen to share a number today (e.g. nixCacheHttp and
+  # pxeBootHttp are both 80) so changing one service's port can never
+  # silently change an unrelated one.
+  ports = {
+    # nix-cache's nginx reverse proxy in front of nix-serve
+    # (modules/nix-cache/server.nix).
+    nixCacheHttp = 80;
+
+    # pxe-boot's nginx asset server, also used to build pxeBaseUrl
+    # (modules/build-types/pxe-boot.nix).
+    pxeBootHttp = 80;
+
+    # pxe-boot's atftpd TFTP server — UDP, not TCP
+    # (modules/build-types/pxe-boot.nix).
+    pxeBootTftp = 69;
+
+    # `server`'s NFS exports need both the portmapper (rpcbind) and the
+    # NFS data port itself opened (modules/build-types/server.nix).
+    nfsRpcbind = 111;
+    nfsd = 2049;
+
+    # Opened on the docker host's firewall for the Traefik-fronted
+    # container stack (docker-compose config lives in the separate
+    # /home/debian/docker repo, not here): 80/443 are Traefik's own
+    # HTTP/HTTPS listeners; 8080 is an additional exposed service whose
+    # exact backend isn't declared in this repo (modules/build-types/docker.nix).
+    dockerHttp = 80;
+    dockerHttps = 443;
+    dockerExtra = 8080;
+
+    # Beszel monitoring hub, reachable at
+    # http://<dockerHost>.<homeDomain>:<beszelHub> from every agent
+    # (modules/beszel/enable-agent.nix, hosts/nixos/home.nix).
+    beszelHub = 8090;
+
+    # Proxmox VE and Proxmox Backup Server web UIs, opened as desktop
+    # shortcuts on the gui build type (hosts/nixos/home.nix).
+    pveWeb = 8006;
+    pbsWeb = 8007;
+  };
+
+  # .raw disk image size for every proxmox-* host's standalone Disko image
+  # build (modules/disko/proxmox.nix, config.system.build.diskoImagesScript
+  # — see docs/proxmox-images.md). Root fills whatever's left after the ESP
+  # and swap partitions within this total.
+  proxmoxImageSize = "20G";
+
+  # nix-cache's Nix store garbage collection retention
+  # (modules/nix-cache/server.nix).
+  nixCacheGcMaxAge = "30d";
+
+  # Traefik access log rotation, watched on the docker host at
+  # nfsShares.dockerVolumes.mountpoint (modules/traefik/rotate-logs.nix).
+  traefikLogRotate = {
+    maxSize = "100M"; # rotate once a log file exceeds this size
+    keep = 20; # number of rotated logs to retain before deleting the oldest
+  };
+
+}