Build Proxmox images directly on the node instead of transferring them

create-proxmox-resource.sh no longer builds locally and scp's a multi-gigabyte image over -- it now clones/pulls this repo onto the Proxmox node itself (bootstrapping build tooling via the existing codex-setup.sh on first use) and runs the nix build / disko image script there, staging the result straight into the node's own import directory. host-keys/ (gitignored) is copied over separately since a git pull doesn't carry it. --image still uploads an explicit local file for the case where you don't want a build at all. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
updated sops keys
2026-07-20 13:29:45 +00:00 · 2026-07-20 12:27:24 +00:00 · 2026-07-20 12:03:30 +00:00 · 2026-07-20 11:47:22 +00:00 · 2026-07-20 11:42:02 +00:00 · 2026-07-20 11:37:05 +00:00
58 changed files with 3172 additions and 388 deletions
@@ -17,13 +17,5 @@ jobs:
      - name: Install Nix
        uses: DeterminateSystems/nix-installer-action@v19

-      - name: Evaluate all NixOS hosts
-        run: |
-          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
+      - name: Run maintenance checks (secrets, fmt, lint, eval)
+        run: bash scripts/codex-maintenance.sh
@@ -17,13 +17,5 @@ jobs:
      - name: Install Nix
        uses: DeterminateSystems/nix-installer-action@v19

-      - name: Evaluate all NixOS hosts
-        run: |
-          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
+      - name: Run maintenance checks (secrets, fmt, lint, eval)
+        run: bash scripts/codex-maintenance.sh
@@ -3,9 +3,19 @@
 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

+# Python bytecode cache (scripts/lib/*.py)
+__pycache__/
+*.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/
@@ -1,11 +1,13 @@
 keys:
-  - &admin age10nd382a9klsn2mrs60emdtsxe43pht3a0m9p29phfrhy0wfyt3vsq9r667
+  - &admin age1njap586hc0q43kr03g6c8eqhdsmk8zcafkl3f83xwlc2gqhlmfgs4tmwad
  - &docker age19gfn2yedg76dmztm4hncr7vf3r3c9j0qpt4rap7y7gersjk4m3ks2lhd0e
  - &server age1ll6hj5ggruetgjwjfnplpn5xtq35uhlcdflksx3xmnjm6s3uad9sz70jkf
  - &nix-cache age120le4a5l8dh3lyfgvmj3d9ksmej6ajs5mer5y7r0vfg3x9fn69dqf8xgzu
  - &lxc-minimal age1qz9d4ka4xgexujyd247s7lp737sulp5fhxl5d65fj2ykvc4j4edqrsdks8
  - &nix-minimal age120whqj96g26lsgy4udvgsn8dc9lumh8jeu3a564fx79rjr5lxffqmrljuu
-  - &lxc-nix-cache age164px2a8e48ptsf9ngtan38aa6jls4jdl26mzrgzf6sn3vcvt49hqjrgr8w
+  - &proxmox-minimal age10at8862478urh0eeuwh8hzln6ck78jgwtztgxatwqlzwagg77y5snm4xzg
+  - &lxc-nix-cache age1xjst4frdh0th6q8m7p7u9g5af7ty5jqeum0p6z8a52a9q7st7ewqw8yl9j
+  - &lxc-docker age1ezk9x53zt8kcnscdm80jcyf0xq97vndv7jsn3rl8cc0cwm2jmpmq372dzs

 creation_rules:
  # Shared across every currently-deployed host: root/nixos password hash,
@@ -22,6 +24,8 @@ creation_rules:
          - *lxc-minimal
          - *nix-minimal
          - *lxc-nix-cache
+          - *proxmox-minimal
+          - *lxc-docker

  - path_regex: secrets/nix-cache\.yaml$
    key_groups:
@@ -7,7 +7,7 @@ servers and workstation.

 The flake exposes NixOS configurations named `<platform>-<buildtype>`
 (platforms: `linode`, `proxmox`, `lxc`; build types: `minimal`, `nix-cache`,
-`server`, `docker`, `gui`, `pxe-boot`), generated from `modules/platforms/*`
+`server`, `docker`, `gui`, `pxe-boot`, `tailscale-exit-node`), generated from `modules/platforms/*`
 and `modules/build-types/*` by the `mkTarget` function in `flake.nix`. Not
 every combination is built — `pxe-boot` has no `linode` variant. See
 `README.md` for the full current target list; treat `flake.nix` as the
@@ -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.
-  `prepare.sh`, `hosts/nixos/configuration.nix`) and SSH public keys (e.g.
-  `modules/nix-cache/server.nix`). The hashes are known tech debt — do not use
-  them as a template for new hosts, and flag any *new* secret-like string you
-  encounter instead of committing it.
+- This repo currently contains **committed password hashes** in
+  `modules/installer/common.nix` (the auto-installer's own root/nixos login —
+  a deliberate, documented choice, see `docs/auto-installer.md`, not
+  accidental tech debt) and **SSH public keys** in `variables.nix`
+  (`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,6 +58,87 @@ 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 every `nixosConfigurations` host plus
+every package/tarball/image variant 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.
+- `scripts/rotate-admin-key.sh <backup-admin-key> [--new-key-file <path>]
+  [--dry-run]` — rotates `.sops.yaml`'s `&admin` age key: decrypts with a
+  backed-up copy of the key currently trusted as `&admin` (verified by
+  deriving its public key and comparing, not taken on faith), replaces the
+  `&admin` line with a new key already present in the environment
+  (defaults to wherever sops/age itself would look), and runs
+  `sops updatekeys` on every `secrets/*.yaml`. One-way: the old key can no
+  longer decrypt anything re-encrypted this way. This is the automation
+  for the manual steps `sync-host-keys.sh`/`create-proxmox-resource.sh`
+  print when they bootstrap a brand-new, not-yet-trusted key on a machine
+  with no prior admin access.
+- `scripts/backup-admin-key.sh <dest-path> [--key-file <path>] [--force]
+  [--dry-run]` — copies the local sops age key (source resolution matches
+  sops/age itself: `$SOPS_AGE_KEY` inline, then `--key-file`, then
+  `$SOPS_AGE_KEY_FILE`, then the XDG default) to an arbitrary destination
+  path with `0600` permissions, validating it's a real age identity and
+  round-tripping the public key before and after the write. Refuses to
+  overwrite an existing `<dest-path>` without `--force`. Purely a local
+  filesystem copy — never touches `.sops.yaml`/`secrets/*.yaml` or the
+  repo at all. The resulting file is exactly what `rotate-admin-key.sh`
+  expects as its backup-key argument.
+
+`sync-host-keys.sh`, `create-proxmox-resource.sh`, and
+`rotate-admin-key.sh` genuinely mutate real state when run for real (not
+`--dry-run`): real `secrets/*.yaml` recipients, real Proxmox VMs/
+containers, real revocation of decrypt access. They require the
+operator's own SSH/sops access, which an agent session doesn't have — but
+don't suggest running any of them non-dry-run without the operator's
+explicit go-ahead even if it becomes technically reachable.
+`backup-admin-key.sh` only writes a key copy to a path the operator gives
+it — lower-stakes than the others, but it still handles a real private
+key, so treat its destination path choice as the operator's call too.
+
 ## Architecture

 `flake.nix` is the single entry point. It generates one
@@ -71,9 +160,10 @@ nixosSystem {
 ```

 Platforms: `linode`, `proxmox`, `lxc`. Build types: `minimal`, `nix-cache`,
-`server`, `docker`, `gui`, `pxe-boot`. Not every 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
+`server`, `docker`, `gui`, `pxe-boot`, `tailscale-exit-node`. Not every
+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
@@ -93,17 +183,39 @@ removing a host.
  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.
+  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.
+  minimal/server/docker/gui/pxe-boot/nix-cache/tailscale-exit-node.
 - `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/installer/` — the auto-installer environment (ISO, also served as
+  PXE netboot): `common.nix` (shared config + the generated
+  `auto-install.sh`), `iso.nix`, `host-keys.nix` (optionally bakes
+  `host-keys/` into the image under `--impure`). See
+  `docs/auto-installer.md`.
+- `modules/pxe-boot/stage-installer-artifacts.nix` — builds the installer's
+  netboot image and stages it on the `pxe-boot` host so its iPXE menu can
+  chain straight to it. See `docs/pxe-boot.md`.
 - `modules/nix-cache/{client,server,remote-builder-client}.nix` — binary cache
  substituter + SSH remote-builder wiring; see `docs/nix-cache.md` for the
  full design (per-host local stores, no shared `/nix/store`, and how the
@@ -129,6 +241,12 @@ 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`.
@@ -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) |
-| `proxmox-minimal` | Minimal NixOS host profile on Proxmox (real, deployed — previously the flat `nix-minimal` target) |
+| `linode-minimal` | Minimal NixOS host profile on a Linode VPS |
+| `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-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-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-gui` / `proxmox-gui` / `lxc-gui` | Cinnamon desktop workstation (`proxmox-gui` is the real, deployed one — 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) |
+| `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 — previously the flat `server` 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 — previously the flat `nixos` 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,17 +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, ...) — passed to every module and Home Manager config as the `vars` argument via `specialArgs`/`extraSpecialArgs` |
+| `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 |
-| `modules/installer/` | Auto-installer environment (ISO/netboot/Proxmox LXC) — see `docs/auto-installer.md` |
+| `modules/installer/` | Auto-installer environment (ISO, also served as PXE netboot) — see `docs/auto-installer.md` |
 | `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, and the auto-installer |
-| `scripts/` | Codex setup, validation, and host-key-prep helpers |
+| `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

@@ -87,6 +96,29 @@ 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 (host-key registration, building the
+image directly on the Proxmox node itself, `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
@@ -107,6 +139,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
@@ -5,8 +5,9 @@ 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/netboot/Proxmox
-LXC) with SSH access, Git support, and an interactive installation script.
+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
@@ -18,7 +19,7 @@ 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
+`lxc-gui`, `lxc-pxe-boot`, `lxc-tailscale-exit-node`) 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
@@ -33,16 +34,76 @@ container image, no install step at all:
 nix build .#nixosConfigurations.lxc-minimal.config.system.build.tarball
 ```

-Then, on the Proxmox host, `pct restore` (or the GUI's "Create CT" → upload
-template flow) that tarball directly as a new container. First boot runs
-`boot.postBootCommands` (registers the Nix store DB and system profile) —
-there's no separate activation step to run yourself.
+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:

-Host keys still need pre-seeding the same way as any other host (see "Host
-keys" below) — the sops-nix activation-vs-first-boot race is identical
-regardless of how the image reaches the machine. `NIXOS_HOST_KEYS_DIR=...
-nix build ... --impure` bakes the matching key into the tarball the same way
-it does for the ISO/PXE installer images.
+```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 (host-key handling, building the tarball directly on the Proxmox
+node itself, `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

@@ -53,32 +114,40 @@ it does for the ISO/PXE installer images.
  `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/proxmox-lxc.nix` — Proxmox LXC-specific: disables
-  bootloader options (containers don't need one) plus `common.nix`.
 - `modules/installer/host-keys.nix` — optionally bakes pre-generated SSH
  host keys into the image; see "Host keys" below.
- `scripts/prepare-host-key.sh` — admin-workstation pre-flight tool, see
-  "Creating a New Machine" 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
-nixosConfigurations.proxmox-lxc   # Proxmox LXC-based installer image
+nixosConfigurations.installer   # ISO/netboot installer image

 packages.x86_64-linux.iso   # installer ISO/netboot image
-packages.x86_64-linux.lxc   # Proxmox LXC installer tarball
 packages.x86_64-linux.pxe   # netboot-ipxe + netboot-initrd + netboot-kernel, bundled
-packages.x86_64-linux.all   # all three of the above, bundled
 ```

 ```sh
 nix build .#iso
-nix build .#lxc
 nix build .#pxe
-nix build .#all
 ```

+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`.
@@ -123,10 +192,24 @@ 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. Each host defines its own layout
-via `disko.devices`; a host without one is installed in place via bind-mount
-(this is how every LXC container target works, since they have no raw block
-device to partition).
+`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

@@ -135,7 +218,7 @@ device to partition).
 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` if the target has a Disko config, otherwise bind-mounts `/` onto `/mnt`.
+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.
@@ -147,24 +230,28 @@ 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. **On your admin workstation**, decide the new machine's flake target name
-   (`<platform>-<buildtype>`, e.g. `proxmox-server`) and generate + register
-   its host key:
+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/prepare-host-key.sh <hostname>
+   ./scripts/sync-host-keys.sh <flake-target>
   ```

-   This generates `host-keys/<hostname>_ssh_host_ed25519_key(.pub)` and
-   prints the `.sops.yaml` snippet to add, which secrets files to
-   re-encrypt it into, and the next steps below.
+   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.

-2. **Edit `.sops.yaml`** with the printed snippet, then re-encrypt every
-   secrets file you added the new host to:
-
-   ```sh
-   nix-shell -p sops --run 'sops updatekeys secrets/common.yaml'
-   ```
+   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
@@ -11,19 +11,38 @@ This repository configures `nix-cache` as a **binary cache server** and a **remo
 - 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`.

-## 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
-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
+nix-shell -p sops --run 'sops secrets/nix-cache.yaml'
 ```

-Do not commit private keys.
-Do not commit new password hashes or live credentials. Existing committed hashes
-should be rotated and moved to host-local secret management.
+Add (or replace) a `cache-priv-key` entry with the private key file's exact
+contents. If you don't have it yet, generate a keypair once:
+
+```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:
@@ -0,0 +1,116 @@
+# 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 building the image directly on the Proxmox node
+itself (no local build, no image transfer) — 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.
@@ -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

@@ -83,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:
@@ -1,5 +1,13 @@
 # Spec: Refactor Flake Targets into Platform × Build-Type Matrix

+**Status: implemented.** `flake.nix`'s `generatedTargets`/`mkTarget` and
+`modules/platforms/*`/`modules/build-types/*` are the result of this spec —
+kept here for historical rationale only (referenced from `CLAUDE.md`'s
+"Composition pattern" section), not as an active or open plan. The "Open
+Questions" below were resolved during implementation; don't treat them as
+outstanding. A `tailscale-exit-node` build type was added later, beyond this
+spec's original scope.
+
 ## Context

 The flake at `~/nixos` currently defines these output targets (flat, ad-hoc naming):
@@ -33,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 = [
@@ -42,7 +45,7 @@
            ./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 = {
@@ -56,7 +59,13 @@
            ./modules/nix-cache/client.nix
            ./modules/nix-cache/remote-builder-client.nix
          ];
-          specialArgs = { inherit inputs vars netbootSystem; };
+          # 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
@@ -85,6 +94,10 @@

        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
@@ -100,12 +113,6 @@
          modules = [ ./modules/installer/iso.nix ];
          specialArgs = { inherit vars; };
        };
-
-        proxmox-lxc = nixpkgs.lib.nixosSystem {
-          inherit system;
-          modules = [ ./modules/installer/proxmox-lxc.nix ];
-          specialArgs = { inherit vars; };
-        };
      };

      # Same installer environment, built as netboot (kernel + initrd +
@@ -128,24 +135,22 @@

      nixosConfigurations = generatedTargets // installerTargets;

-      # Buildable auto-installer artifacts (`nix build .#<name>`), migrated
-      # unchanged from nix-auto-installer's interface.
-      packages.${system} = rec {
+      # 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;

-        lxc = installerTargets.proxmox-lxc.config.system.build.tarball;
-
        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; }
        ];
-
-        all = pkgs.linkFarm "all" [
-          { name = "iso"; path = iso; }
-          { name = "lxc"; path = lxc; }
-          { name = "pxe"; path = pxe; }
-        ];
      };
    };
 }
@@ -31,7 +31,7 @@
        [Desktop Entry]
        Type=Application
        Name=Proxmox (Chromium)
-        Exec=chromium --app=https://pve.${vars.homeDomain}:${toString vars.pveWebPort} --window-size=1920,1080 --window-position=0,0
+        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;
@@ -41,7 +41,7 @@
        [Desktop Entry]
        Type=Application
        Name=Proxmox Backup Server (Chromium)
-        Exec=chromium --app=https://${vars.pbsIp}:${toString vars.pbsWebPort} --window-size=1920,1080 --window-position=0,0
+        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;
@@ -51,7 +51,7 @@
        [Desktop Entry]
        Type=Application
        Name=Proxmox (Firefox)
-        Exec=firefox --new-instance https://pve.${vars.homeDomain}:${toString vars.pveWebPort} --profile ProxmoxWebApp --window-size=1920,1080 --class ProxmoxWebApp
+        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;
@@ -61,7 +61,7 @@
        [Desktop Entry]
        Type=Application
        Name=Proxmox Backup Server (Firefox)
-        Exec=firefox --new-window https://${vars.pbsIp}:${toString vars.pbsWebPort} --profile PbsWebApp --window-size=1920,1080 --class PbsWebApp
+        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;
@@ -14,7 +14,7 @@
  services.beszel.agent.environment = {
    #DOCKER_HOST = "tcp://docker-socket-proxy:2375";
    KEY = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIFPR9kwtC4TAeTRu46A7+opZsYpxqkRJ+x/ZyB2GWCeG";
-    EXTRA_FILESYSTEMS = "${vars.storageRoot}/docker/volumes";
+    EXTRA_FILESYSTEMS = "${vars.storageRoot}/${vars.nfsShares.dockerVolumes.subpath}";
    LOG_LEVEL = "debug";
  };

@@ -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";
+}
@@ -4,6 +4,15 @@
  services.beszel.agent.enable = true;
  services.beszel.agent.environment = {
    #DOCKER_HOST = "tcp://docker-socket-proxy:2375";
-    HUB_URL = "http://${vars.dockerHost}.${vars.homeDomain}:${toString vars.beszelHubPort}";
+    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";
 }
@@ -28,13 +28,18 @@
  boot.supportedFilesystems = [ "nfs" ];

  systemd.tmpfiles.rules = [
-    "L+ /home/nixos/docker - - - - /mnt/docker/config"
-    "d /mnt/docker 0755 nixos users -"
-    "d /mnt/raspi-backup 0755 nixos users -"
+    "L+ /home/${vars.primaryUser}/docker - - - - ${vars.nfsShares.dockerConfig.mountpoint}"
+    "d /mnt/docker 0755 ${vars.primaryUser} 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 vars.beszelHubPort ];
+  networking.firewall.allowedTCPPorts = [
+    vars.ports.dockerHttp
+    vars.ports.dockerExtra
+    vars.ports.dockerHttps
+    vars.ports.beszelHub
+  ];
 }
@@ -1,4 +1,4 @@
-{ config, pkgs, lib, inputs, ... }:
+{ config, pkgs, lib, inputs, vars, ... }:

 {
  environment.systemPackages = with pkgs; [
@@ -65,7 +65,7 @@
  # 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.nixos.extraGroups = lib.mkIf config.networking.networkmanager.enable [ "networkmanager" ];
+  users.users.${vars.primaryUser}.extraGroups = lib.mkIf config.networking.networkmanager.enable [ "networkmanager" ];

  programs.firefox.enable = true;

@@ -1,4 +1,4 @@
-{ lib, pkgs, config, ... }:
+{ lib, pkgs, config, vars, ... }:

 {
  networking.networkmanager.enable = true;
@@ -6,7 +6,7 @@
  # 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.nixos.extraGroups = lib.mkIf config.networking.networkmanager.enable [ "networkmanager" ];
+  users.users.${vars.primaryUser}.extraGroups = lib.mkIf config.networking.networkmanager.enable [ "networkmanager" ];

  environment.systemPackages = with pkgs; [
    inetutils
@@ -155,6 +155,6 @@ in
    };
  };

-  networking.firewall.allowedTCPPorts = [ 80 ];
-  networking.firewall.allowedUDPPorts = [ 69 ];
+  networking.firewall.allowedTCPPorts = [ vars.ports.pxeBootHttp ];
+  networking.firewall.allowedUDPPorts = [ vars.ports.pxeBootTftp ];
 }
@@ -16,13 +16,13 @@
  services.nfs.server = {
    enable = true;
    exports = ''
-      ${vars.storageRoot}/docker/config ${vars.lanCidr}(rw,sync,no_subtree_check,no_root_squash)
-      ${vars.storageRoot}/docker/volumes ${vars.lanCidr}(rw,sync,no_subtree_check,no_root_squash)
-      ${vars.storageRoot}/docker/databases ${vars.lanCidr}(rw,sync,no_subtree_check,no_root_squash)
-      ${vars.storageRoot}/docker/nextcloud-data ${vars.lanCidr}(rw,sync,no_subtree_check,no_root_squash)
-      ${vars.storageRoot}/raspi/volumes ${vars.lanCidr}(rw,sync,no_subtree_check,no_root_squash)
+      ${vars.storageRoot}/${vars.nfsShares.dockerConfig.subpath} ${vars.lanCidr}(rw,sync,no_subtree_check,no_root_squash)
+      ${vars.storageRoot}/${vars.nfsShares.dockerVolumes.subpath} ${vars.lanCidr}(rw,sync,no_subtree_check,no_root_squash)
+      ${vars.storageRoot}/${vars.nfsShares.dockerDatabases.subpath} ${vars.lanCidr}(rw,sync,no_subtree_check,no_root_squash)
+      ${vars.storageRoot}/${vars.nfsShares.nextcloudData.subpath} ${vars.lanCidr}(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 ];
 }
@@ -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" ];
+}
@@ -17,6 +17,26 @@ let
      --refresh \
      --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
 {
  programs.bash = {
@@ -25,5 +45,6 @@ in
      "Switch-nix" = mySwitchCmd;
      "Test-nix" = myTestCmd;
    };
+    initExtra = buildImageFn;
  };
 }
@@ -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";
+      };
+    };
+  };
+}
@@ -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";

@@ -2,8 +2,8 @@

 {
  fileSystems = {
-    "/mnt/docker/config" = {
-      device = "${vars.nfsServerHost}:${vars.storageRoot}/docker/config";
+    ${vars.nfsShares.dockerConfig.mountpoint} = {
+      device = "${vars.nfsServerHost}:${vars.storageRoot}/${vars.nfsShares.dockerConfig.subpath}";
      fsType = "nfs";

      options = [
@@ -14,8 +14,8 @@
      ];
    };

-    "/mnt/docker/databases" = {
-      device = "${vars.nfsServerHost}:${vars.storageRoot}/docker/databases";
+    ${vars.nfsShares.dockerDatabases.mountpoint} = {
+      device = "${vars.nfsServerHost}:${vars.storageRoot}/${vars.nfsShares.dockerDatabases.subpath}";
      fsType = "nfs";

      options = [
@@ -26,8 +26,8 @@
      ];
    };

-    "/mnt/docker/volumes" = {
-      device = "${vars.nfsServerHost}:${vars.storageRoot}/docker/volumes";
+    ${vars.nfsShares.dockerVolumes.mountpoint} = {
+      device = "${vars.nfsServerHost}:${vars.storageRoot}/${vars.nfsShares.dockerVolumes.subpath}";
      fsType = "nfs";

      options = [
@@ -38,8 +38,8 @@
      ];
    };

-    "/mnt/nextcloud-data" = {
-      device = "${vars.nfsServerHost}:${vars.storageRoot}/docker/nextcloud-data";
+    ${vars.nfsShares.nextcloudData.mountpoint} = {
+      device = "${vars.nfsServerHost}:${vars.storageRoot}/${vars.nfsShares.nextcloudData.subpath}";
      fsType = "nfs";

      options = [
@@ -50,8 +50,8 @@
      ];
    };

-    "/mnt/raspi-backup" = {
-      device = "${vars.nfsServerHost}:${vars.storageRoot}/raspi/volumes";
+    ${vars.nfsShares.raspiVolumes.mountpoint} = {
+      device = "${vars.nfsServerHost}:${vars.storageRoot}/${vars.nfsShares.raspiVolumes.subpath}";
      fsType = "nfs";

      options = [
@@ -33,14 +33,11 @@
    };
  };

-  fileSystems."/" =
-    {
-      device = "/dev/sda";
-      fsType = "ext4";
-    };
-
-  swapDevices =
-    [{ device = "/dev/sdb"; }];
+  # fileSystems."/" and swapDevices are now owned by disko
+  # (../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
+  # in sync with what NixOS actually mounts.

  nixpkgs.hostPlatform = lib.mkDefault "x86_64-linux";
 }
@@ -57,25 +57,23 @@

        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/proxmox-lxc — these *are* the installer image's own
-        #                           flake targets, not deployable hosts;
-        #                           "installing" one means nixos-install-ing
-        #                           a copy of the installer into itself.
+        #   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")
-              | select(. != "proxmox-lxc")'
+              | select(. != "installer")'
        )

        if [[ ''${#options[@]} -eq 0 ]]; then
@@ -121,21 +119,12 @@
            nix_extra_opts+=(--option substituters "https://cache.nixos.org/")
        fi

-        if nix eval --refresh --json  --extra-experimental-features "flakes nix-command" "''${nix_extra_opts[@]}" "''${FLAKE_BASE_URL}#nixosConfigurations.''${choice}.config.disko.devices.disk.main.device" >/dev/null 2>&1; then
-            disko --mode destroy,format,mount \
-                --flake "''${FLAKE_BASE_URL}#''${choice}" "''${nix_extra_opts[@]}" --yes
-        else
-            # No raw disk to partition — true for every LXC container, which has
-            # no block device visible from inside it, only its already-mounted
-            # root filesystem. nixos-install defaults to installing into /mnt; if
-            # nothing points /mnt at the real root, the new system gets built and
-            # written to a disconnected empty directory, never actually becomes
-            # bootable, and the container silently keeps running this installer
-            # environment forever. Bind-mount / onto /mnt so the install actually
-            # lands on the filesystem this container boots from.
-            echo "Selected host has no Disko configuration — installing in place via bind mount."
-            mount --bind / /mnt
-        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
@@ -1,12 +0,0 @@
-{ modulesPath, ... }:
-
-{
-  imports = [
-    ./common.nix
-    (modulesPath + "/virtualisation/proxmox-lxc.nix")
-  ];
-
-  # LXC has no bootloader
-  boot.loader.grub.enable = false;
-  boot.loader.systemd-boot.enable = false;
-}
@@ -5,6 +5,14 @@
  #   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;

@@ -1,18 +1,20 @@
 { config, pkgs, vars, ... }:

 {
-  # Generate the binary cache key pair on the nix-cache host:
-  #   sudo install -d -m 0700 /etc/nix
-  #   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
+  # nix-serve's signing key has to be the *same* key on every host that
+  # ever plays the nix-cache role -- modules/nix-cache/client.nix hardcodes
+  # every client's trust in one specific public key ("cache.local-1:..."),
+  # so a freshly self-generated key here wouldn't be trusted by anyone.
+  # Managed via sops-nix like every other secret in this repo instead of
+  # the old manual `nix-store --generate-binary-cache-key` step -- see
+  # "Binary cache signing key" in docs/nix-cache.md for how to add/rotate
+  # the value in secrets/nix-cache.yaml.
+  sops.secrets."cache-priv-key".sopsFile = ../../secrets/nix-cache.yaml;
+
  services = {
    nix-serve = {
      enable = true;
-      secretKeyFile = "/etc/nix/cache-priv.pem";
+      secretKeyFile = config.sops.secrets."cache-priv-key".path;
    };

    nginx = {
@@ -28,7 +30,7 @@
    openssh.enable = true;
  };

-  networking.firewall.allowedTCPPorts = [ 80 ];
+  networking.firewall.allowedTCPPorts = [ vars.ports.nixCacheHttp ];

  users.groups.${vars.remoteBuilderUser} = { };

@@ -54,6 +56,6 @@
  nix.gc = {
    automatic = true;
    dates = "weekly";
-    options = "--delete-older-than 30d";
+    options = "--delete-older-than ${vars.nixCacheGcMaxAge}";
  };
 }
@@ -3,6 +3,7 @@
 {
  imports = [
    ../hardware-configuration/vm/linode.nix
+    ../disko/linode.nix
  ];

  networking = {
@@ -1,5 +1,44 @@
-{ lib, modulesPath, ... }:
+{ 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
 {
  # LXC containers share the host kernel — Proxmox starts them by exec'ing
  # /sbin/init directly, no bootloader/initrd involved — and Proxmox has its
@@ -35,4 +74,75 @@
  # 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
+    '';
+  };
 }
@@ -1,8 +1,8 @@
 { vars, ... }:

 {
-  fileSystems."/mnt/raspi" = {
-    device = "raspberrypi.${vars.tailnetDomain}:/home/raspi/raspi";
+  fileSystems.${vars.raspiMountpoint} = {
+    device = "${vars.raspberryPiHost}.${vars.tailnetDomain}:${vars.raspiNfsPath}";
    fsType = "nfs4";
    options = [
      "nofail"
@@ -1,12 +1,27 @@
-{ vars, ... }:
+_:

 {
-  services.tailscale = {
-    enable = true;
+  imports = [ ./enable-service.nix ];

-    extraUpFlags = [
+  services.tailscale = {
+    # Enables the sysctl forwarding settings exit nodes/subnet routers need;
+    # without this, --advertise-exit-node has no effect.
+    useRoutingFeatures = "server";
+
+    # Lets peers reach this node directly over the tailscale UDP port
+    # instead of relaying through DERP.
+    openFirewall = true;
+
+    # 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=${vars.lanCidr}"
    ];
  };
 }
@@ -1,14 +1,14 @@
-_:
+{ vars, ... }:

 {
  services.logrotate = {
    enable = true;

    settings = {
-      "/mnt/docker/volumes/traefik-data/logs/*.log" = {
+      "${vars.nfsShares.dockerVolumes.mountpoint}/traefik-data/logs/*.log" = {
        daily = true;
-        size = "100M";
-        rotate = 20;
+        size = vars.traefikLogRotate.maxSize;
+        rotate = vars.traefikLogRotate.keep;
        compress = true;
        missingok = true;
        notifempty = true;
@@ -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
@@ -122,13 +122,25 @@ Add a pre-commit hook (or a `nix flake check` step) running `gitleaks protect --

 ## Definition of done

- [ ] Milestone 1 inventory complete and reviewed
- [ ] All hosts have per-host age keys; admin key backed up outside the repo
- [ ] Every inventoried secret migrated to sops-nix, referenced via `*File`/`sops.secrets.*.path`, nothing plaintext in the working tree
- [ ] `nixos-rebuild dry-build` and at least one real `switch` verified per host
- [ ] Working-tree scanner sweep clean
- [ ] History rewritten with `git-filter-repo`, force-pushed, full-history scanner sweep clean
- [ ] All other clones deleted and re-cloned from the rewritten history
- [ ] Every credential in the original inventory rotated (not just re-encrypted)
- [ ] Pre-commit secret scanning hook added
- [ ] `secrets-inventory.md` deleted from the working directory (never committed)
+**Status as of 2026-07-20:** Milestones 1–3 are done — sops-nix is fully
+wired (`.sops.yaml`, `secrets/*.yaml`, referenced via `hashedPasswordFile`/
+`*File`/`sops.secrets.*.path` throughout), and history has been scrubbed
+with `git-filter-repo` + force-push (this removed a GitHub fine-grained PAT
+that had been committed in plaintext in `flake.nix`/`common/home.nix`
+between 2025-07-16 and 2026-02-09, later migrated to sops but never scrubbed
+from history until now). **Milestone 4 is not confirmed** — whether that PAT
+(or any other historically-plaintext credential) was actually rotated, not
+just re-encrypted, isn't something this repo can attest to; that's an
+operator action against the issuing service (GitHub, etc.), not a repo
+change. Do that before considering this fully closed.
+
+- [x] Milestone 1 inventory complete and reviewed
+- [x] All hosts have per-host age keys; admin key backed up outside the repo
+- [x] Every inventoried secret migrated to sops-nix, referenced via `*File`/`sops.secrets.*.path`, nothing plaintext in the working tree
+- [x] `nixos-rebuild dry-build` and at least one real `switch` verified per host
+- [x] Working-tree scanner sweep clean
+- [x] History rewritten with `git-filter-repo`, force-pushed, full-history scanner sweep clean
+- [ ] All other clones deleted and re-cloned from the rewritten history — every clone that existed before 2026-07-20's rewrite (any other machine, WSL instance, or CI checkout) needs this
+- [ ] Every credential in the original inventory rotated (not just re-encrypted) — **the GitHub PAT found in history specifically still needs this**
+- [x] Pre-commit secret scanning hook added (`.githooks/pre-commit`, `gitleaks protect --staged`)
+- [x] `secrets-inventory.md` deleted from the working directory (never committed)
@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+# Backs up the local sops age key (the private key that decrypts
+# secrets/*.yaml -- normally the one trusted as &admin) to an arbitrary
+# destination path, e.g. a USB drive or other offline storage, so it can
+# later be restored and handed to rotate-admin-key.sh if this machine's
+# copy is ever lost, or to run either script from a different machine.
+#
+# Usage:
+#   scripts/backup-admin-key.sh <dest-path> [--key-file <path>] [--force] [--dry-run]
+#
+# Source key resolution matches sops/age's own default order:
+#   $SOPS_AGE_KEY (inline identity text) if set, else
+#   --key-file if given, else
+#   $SOPS_AGE_KEY_FILE if set, else
+#   ${XDG_CONFIG_HOME:-$HOME/.config}/sops/age/keys.txt
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "$0")/.." && pwd)"
+sops_yaml="${repo_root}/.sops.yaml"
+
+# shellcheck source=env.sh
+source "${repo_root}/scripts/env.sh"
+
+# Pin cwd for the same reason rotate-admin-key.sh does: age/sops calls
+# below should never depend on wherever the caller's shell happened to be.
+cd "$repo_root"
+
+usage() {
+  cat <<EOF
+Usage: $0 <dest-path> [--key-file <path>] [--force] [--dry-run]
+
+  <dest-path>        Where to write the backup. Parent directories are
+                     created as needed. Written with 0600 permissions.
+  --key-file <path>  Read the key from here instead of the default
+                     sops/age resolution (\$SOPS_AGE_KEY_FILE, then
+                     \${XDG_CONFIG_HOME:-\$HOME/.config}/sops/age/keys.txt).
+                     Ignored if \$SOPS_AGE_KEY is set (that always wins,
+                     same precedence sops/age itself uses).
+  --force            Overwrite <dest-path> if it already exists.
+  --dry-run          Print what would happen; write nothing.
+EOF
+}
+
+dry_run=0
+force=0
+key_file="${SOPS_AGE_KEY_FILE:-${XDG_CONFIG_HOME:-$HOME/.config}/sops/age/keys.txt}"
+args=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run)
+      dry_run=1
+      shift
+      ;;
+    --force)
+      force=1
+      shift
+      ;;
+    --key-file)
+      key_file="${2:?--key-file requires a path}"
+      shift 2
+      ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    --*)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+    *)
+      args+=("$1")
+      shift
+      ;;
+  esac
+done
+
+if [[ "${#args[@]}" -ne 1 ]]; then
+  usage >&2
+  exit 1
+fi
+dest="${args[0]}"
+
+nix_extra_opts
+
+if [[ -n "${SOPS_AGE_KEY:-}" ]]; then
+  echo "==> Source: \$SOPS_AGE_KEY (inline identity from the environment)."
+  src_content="$SOPS_AGE_KEY"
+else
+  [[ -s "$key_file" ]] || {
+    echo "ERROR: no key found. \$SOPS_AGE_KEY is unset and ${key_file} doesn't exist or is empty." >&2
+    exit 1
+  }
+  echo "==> Source: ${key_file}"
+  src_content="$(cat "$key_file")"
+fi
+
+# Round-trip through a private scratch file (rather than trusting the
+# source string as-is) so age-keygen -y validates it's a real identity
+# before anything is written to <dest-path>.
+scratch="$(mktemp)"
+trap 'rm -f "$scratch"' EXIT
+( umask 077; printf '%s\n' "$src_content" > "$scratch" )
+
+src_pub="$(nix-shell "${NIX_OPTS[@]}" -p age --run "age-keygen -y '$scratch'")" || {
+  echo "ERROR: source doesn't look like a valid age identity (age-keygen -y failed)." >&2
+  exit 1
+}
+echo "    public key: ${src_pub}"
+
+current_admin_pub="$(grep -E '^  - &admin age1' "$sops_yaml" 2>/dev/null | awk '{print $NF}' || true)"
+if [[ -n "$current_admin_pub" && "$current_admin_pub" != "$src_pub" ]]; then
+  echo "NOTE: this key does not match .sops.yaml's current &admin entry (${current_admin_pub})."
+  echo "      Backing it up anyway -- this script doesn't require it to be the admin key."
+fi
+
+if [[ -e "$dest" && "$force" -ne 1 ]]; then
+  echo "ERROR: ${dest} already exists. Pass --force to overwrite." >&2
+  exit 1
+fi
+
+if [[ "$dry_run" -eq 1 ]]; then
+  echo
+  echo "[dry-run] would write $(wc -c <"$scratch" | tr -d ' ') bytes to ${dest} (mode 0600)"
+  [[ -e "$dest" ]] && echo "[dry-run] would overwrite existing file (--force given)"
+  echo "[dry-run] Nothing was written. Re-run without --dry-run to apply this."
+  exit 0
+fi
+
+mkdir -p "$(dirname "$dest")"
+install -m 600 "$scratch" "$dest"
+
+dest_pub="$(nix-shell "${NIX_OPTS[@]}" -p age --run "age-keygen -y '$dest'")"
+if [[ "$dest_pub" != "$src_pub" ]]; then
+  echo "ERROR: ${dest} was written but its public key doesn't match the source -- investigate before relying on this backup." >&2
+  exit 1
+fi
+
+cat <<EOF
+
+Done. Backed up to: ${dest}
+  public key: ${dest_pub}
+
+This is a private key -- store it somewhere offline/secure, not in this
+repo or anywhere it'd get committed. Restore it with:
+  scripts/rotate-admin-key.sh ${dest}
+EOF
@@ -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."
@@ -1,22 +1,14 @@
 #!/usr/bin/env bash
 set -euo pipefail

-export NIX_CONFIG="${NIX_CONFIG:-}
-experimental-features = nix-command flakes
-accept-flake-config = false
-warn-dirty = false
-"
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/nix-bootstrap.sh
+source "${script_dir}/lib/nix-bootstrap.sh"
+# shellcheck source=lib/nix-eval.sh
+source "${script_dir}/lib/nix-eval.sh"

 MODE="${1:-validate}"

-ensure_nix_profile() {
-  if [ -f /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh ]; then
-    . /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
-  elif [ -f "$HOME/.nix-profile/etc/profile.d/nix.sh" ]; then
-    . "$HOME/.nix-profile/etc/profile.d/nix.sh"
-  fi
-}
-
 ensure_nix_profile

 if ! command -v nix >/dev/null 2>&1; then
@@ -24,8 +16,7 @@ if ! command -v nix >/dev/null 2>&1; then
  exit 127
 fi

-hosts_json="$(nix eval --json --no-use-registries --no-accept-flake-config .#nixosConfigurations --apply builtins.attrNames)"
-hosts="$(echo "$hosts_json" | jq -r '.[]')"
+hosts="$(list_flake_targets .)"

 echo "Hosts:"
 echo "$hosts"
@@ -44,17 +35,41 @@ fi

 echo
 echo "Checking Nix formatting with nixpkgs-fmt..."
-nix run --no-use-registries --no-accept-flake-config github:NixOS/nixpkgs/nixos-25.11#nixpkgs-fmt -- --check .
+nix run "${NIX_EVAL_FLAGS[@]}" github:NixOS/nixpkgs/nixos-25.11#nixpkgs-fmt -- --check .

 echo
 echo "Running statix lint..."
-nix run --no-use-registries --no-accept-flake-config github:NixOS/nixpkgs/nixos-25.11#statix -- check .
+nix run "${NIX_EVAL_FLAGS[@]}" github:NixOS/nixpkgs/nixos-25.11#statix -- check .

 echo
 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"
+  nix eval --raw "${NIX_EVAL_FLAGS[@]}" ".#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 "${NIX_EVAL_FLAGS[@]}" ".#nixosConfigurations.${host}.config.system.build.tarball.drvPath"
+      ;;
+    proxmox-*)
+      echo "==> $host (diskoImagesScript)"
+      nix eval --raw "${NIX_EVAL_FLAGS[@]}" ".#nixosConfigurations.${host}.config.system.build.diskoImagesScript.drvPath"
+      ;;
+  esac
+done
+
+echo
+echo "Evaluating buildable packages..."
+packages="$(nix eval --json "${NIX_EVAL_FLAGS[@]}" .#packages.x86_64-linux --apply builtins.attrNames | jq -r '.[]')"
+for pkg in $packages; do
+  echo "==> packages.x86_64-linux.${pkg}"
+  nix eval --raw "${NIX_EVAL_FLAGS[@]}" ".#packages.x86_64-linux.${pkg}"
 done

 if [[ "$MODE" == "dry-run" ]]; then
@@ -62,7 +77,25 @@ if [[ "$MODE" == "dry-run" ]]; then
  echo "Running dry-run builds for all hosts. This will not create result symlinks."
  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"
+    nix build --dry-run --no-link "${NIX_EVAL_FLAGS[@]}" ".#nixosConfigurations.${host}.config.system.build.toplevel"
+
+    case "$host" in
+      lxc-*)
+        echo "==> Dry-run build: $host (tarball)"
+        nix build --dry-run --no-link "${NIX_EVAL_FLAGS[@]}" ".#nixosConfigurations.${host}.config.system.build.tarball"
+        ;;
+      proxmox-*)
+        echo "==> Dry-run build: $host (diskoImagesScript)"
+        nix build --dry-run --no-link "${NIX_EVAL_FLAGS[@]}" ".#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 "${NIX_EVAL_FLAGS[@]}" ".#packages.x86_64-linux.${pkg}"
  done
 fi

@@ -1,19 +1,11 @@
 #!/usr/bin/env bash
 set -euo pipefail

-export NIX_CONFIG="${NIX_CONFIG:-}
-experimental-features = nix-command flakes
-accept-flake-config = false
-warn-dirty = false
-"
-
-ensure_nix_profile() {
-  if [ -f /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh ]; then
-    . /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
-  elif [ -f "$HOME/.nix-profile/etc/profile.d/nix.sh" ]; then
-    . "$HOME/.nix-profile/etc/profile.d/nix.sh"
-  fi
-}
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/nix-bootstrap.sh
+source "${script_dir}/lib/nix-bootstrap.sh"
+# shellcheck source=lib/nix-eval.sh
+source "${script_dir}/lib/nix-eval.sh"

 install_nix_if_missing() {
  if command -v nix >/dev/null 2>&1; then
@@ -79,13 +71,13 @@ if ! command -v jq >/dev/null 2>&1; then
 fi

 echo "Available NixOS hosts:"
-hosts="$(nix eval --json --no-use-registries --no-accept-flake-config .#nixosConfigurations --apply builtins.attrNames | jq -r '.[]')"
+hosts="$(list_flake_targets .)"
 echo "$hosts"

 echo "Evaluating all host toplevel derivations..."
 for host in $hosts; do
  echo "==> Evaluating $host"
-  nix eval --raw --no-use-registries --no-accept-flake-config ".#nixosConfigurations.${host}.config.system.build.toplevel.drvPath"
+  nix eval --raw "${NIX_EVAL_FLAGS[@]}" ".#nixosConfigurations.${host}.config.system.build.toplevel.drvPath"
 done

 echo "Codex setup complete."
@@ -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
@@ -0,0 +1,682 @@
+#!/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.
+#
+# Images are built directly on the Proxmox node (PROXMOX_REMOTE_REPO_DIR /
+# --remote-repo-dir in scripts/env.sh), not on whatever machine runs this
+# script -- there's no multi-gigabyte image to transfer afterward. The first
+# time a node doesn't have that repo path yet, it's bootstrapped: cloned from
+# this checkout's own `origin` remote, then scripts/codex-setup.sh installs
+# the build tooling (Nix, etc.). Every run after that just `git pull`s it and
+# copies over the locally-managed host-keys/ (gitignored, so a git pull
+# alone wouldn't carry it) before building.
+#
+# 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"
+# shellcheck source=lib/nix-eval.sh
+source "${repo_root}/scripts/lib/nix-eval.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 (uploaded to the
+                              node via scp) instead of checking the node /
+                              building one there from the flake.
+  --force-rebuild                Skip the "does the node already have this
+                                  image" check -- always build fresh and
+                                  overwrite what's there.
+  --remote-repo-dir <path>       Where this flake repo lives (or gets
+                                  cloned) on the node, and is built from
+                                  (default: \$PROXMOX_REMOTE_REPO_DIR, ${PROXMOX_REMOTE_REPO_DIR}).
+  --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"
+remote_repo_dir="$PROXMOX_REMOTE_REPO_DIR"
+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 ;;
+  --remote-repo-dir) remote_repo_dir="$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 --------------------
+# Emits "<target>\t<hostName>" pairs for every ${platform_prefix}-* flake
+# target -- the one source both --list and the --host lookup below read
+# from, so they can never see a different set of targets from each other.
+targets_for_platform() {
+  local target
+  for target in $(list_flake_targets "$repo_root" 2>/dev/null | grep -- "^${platform_prefix}-"); do
+    printf '%s\t%s\n' "$target" "$(flake_target_hostname "$repo_root" "$target")"
+  done
+}
+
+list_hosts() {
+  local target hostname
+  while IFS=$'\t' read -r target hostname; do
+    printf '  %-12s -> %s\n' "$hostname" "$target"
+  done < <(targets_for_platform)
+}
+
+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=""
+while IFS=$'\t' read -r target hostname; do
+  if [[ "$hostname" == "$host" ]]; then
+    flake_target="$target"
+    break
+  fi
+done < <(targets_for_platform)
+
+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
+exit 0
+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}"
+
+# --- ensure the flake repo (+ tooling) exists on the node, and is current --
+# Bootstraps once (git clone from this checkout's own `origin`, then
+# scripts/codex-setup.sh installs Nix + friends) if ${remote_repo_dir}
+# doesn't exist yet on the node; otherwise just `git pull`s it, so the image
+# built there reflects what's actually committed and pushed. Only called
+# right before an actual remote build below -- reusing an image already on
+# the node, or an explicit --image, never touch the node's checkout at all.
+ensure_remote_repo() {
+  echo
+  echo "==> Ensuring ${remote_repo_dir} exists and is current on ${node}..."
+  if [[ "$dry_run" -eq 1 ]]; then
+    echo "[dry-run] would ensure ${remote_repo_dir} exists on ${node} (clone + scripts/codex-setup.sh if missing, git pull if present)"
+    return
+  fi
+
+  if ssh "$ssh_target" "test -d '${remote_repo_dir}/.git'"; then
+    echo "Repo present -- pulling latest..."
+    ssh "$ssh_target" "cd '${remote_repo_dir}' && git pull --ff-only"
+  else
+    local origin_url
+    origin_url="$(git -C "$repo_root" remote get-url origin 2>/dev/null || true)"
+    if [[ -z "$origin_url" ]]; then
+      echo "ERROR: ${remote_repo_dir} doesn't exist on ${node}, and this checkout has no" >&2
+      echo "'origin' remote to clone from. Set one (git remote add origin <url>) or create" >&2
+      echo "${remote_repo_dir} on ${node} yourself (e.g. git clone), then re-run." >&2
+      exit 1
+    fi
+    echo "Not present -- cloning from ${origin_url}..."
+    ssh "$ssh_target" "git clone '${origin_url}' '${remote_repo_dir}'"
+    echo "==> Bootstrapping build tooling on ${node} (scripts/codex-setup.sh)..."
+    ssh "$ssh_target" "cd '${remote_repo_dir}' && bash scripts/codex-setup.sh"
+  fi
+}
+
+# --- sync locally-managed host-keys/ to the node ---------------------------
+# Gitignored (see .gitignore), so `git pull` above never carries it -- both
+# build paths need it present as NIXOS_HOST_KEYS_DIR / --pre-format-files
+# input on the node itself now that the build runs there. scp (not rsync,
+# not already a dependency anywhere else in this repo) mirrors how this
+# script already transfers the --image case below.
+sync_remote_host_keys() {
+  echo
+  echo "==> Syncing host-keys/ to ${node}..."
+  if [[ "$dry_run" -eq 1 ]]; then
+    echo "[dry-run] would copy ${repo_root}/host-keys/ to ${ssh_target}:${remote_repo_dir}/host-keys/"
+    return
+  fi
+  ssh "$ssh_target" "mkdir -p '${remote_repo_dir}/host-keys'"
+  scp -pr "${repo_root}/host-keys/." "${ssh_target}:${remote_repo_dir}/host-keys/"
+}
+
+# --- 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 (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
+  ensure_remote_repo
+  sync_remote_host_keys
+
+  # Relayed into the remote build below exactly as decided by the local
+  # nix_extra_opts call earlier in this script -- that decision (whether
+  # nix-cache is reachable) is made once, locally, same as it always has
+  # been; only *where* the resulting "${NIX_OPTS[@]}" gets used as a `nix
+  # build` flag moves to the node. NIX_EXTRA_OPTS is already a %q-quoted
+  # string built for exactly this eval-based reconstruction (see env.sh).
+  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 on ${node}: NIXOS_HOST_KEYS_DIR=\$(pwd)/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"
+      echo "[dry-run] would stage the result at ${remote_path}"
+      local_image="<built-tarball>"
+    else
+      echo "==> Building LXC tarball for ${flake_target} on ${node}..."
+      # Built as a single already-%q-quoted command string, not separate ssh
+      # argv elements -- ssh joins remote command args with plain spaces and
+      # hands the result to the remote shell to re-split, which would
+      # otherwise scatter NIX_EXTRA_OPTS (itself several space-separated,
+      # %q-quoted tokens) across the wrong positional parameters below.
+      printf -v remote_cmd 'bash -s -- %q %q %q %q %q' \
+        "$remote_repo_dir" "$flake_target" "$remote_dir" "$remote_filename" "$NIX_EXTRA_OPTS"
+      ssh "$ssh_target" "$remote_cmd" <<'REMOTE_SCRIPT'
+set -euo pipefail
+repo_dir="$1"; target="$2"; dest_dir="$3"; dest_name="$4"; nix_extra_opts_str="$5"
+declare -a NIX_OPTS=()
+[[ -n "$nix_extra_opts_str" ]] && eval "NIX_OPTS=(${nix_extra_opts_str})"
+cd "$repo_dir"
+NIXOS_HOST_KEYS_DIR="$(pwd)/host-keys" nix build --impure \
+  --no-use-registries --no-accept-flake-config "${NIX_OPTS[@]}" \
+  ".#nixosConfigurations.${target}.config.system.build.tarball" \
+  --out-link "result-${target}"
+built="$(find "result-${target}/tarball" -maxdepth 1 -type f | head -1)"
+if [[ -z "$built" ]]; then
+  echo "ERROR: no tarball found under result-${target}/tarball after build." >&2
+  exit 1
+fi
+mkdir -p "$dest_dir"
+cp "$built" "${dest_dir}/${dest_name}"
+echo "Built and staged: ${dest_dir}/${dest_name}"
+REMOTE_SCRIPT
+      local_image="$remote_path"
+      echo "Built on ${node}: ${remote_path}"
+    fi
+  else
+    # PROXMOX_SSH_USER defaults to root (env.sh), which needs no sudo and
+    # can't assume it's even installed on a minimal node -- only shell out
+    # through sudo when actually running as a non-root SSH user.
+    sudo_prefix="sudo"
+    sudo_display="sudo "
+    if [[ "$PROXMOX_SSH_USER" == "root" ]]; then
+      sudo_prefix=""
+      sudo_display=""
+    fi
+    if [[ "$dry_run" -eq 1 ]]; then
+      echo "[dry-run] would build on ${node}: 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_display}./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"
+      echo "[dry-run] would stage the result at ${remote_path}"
+      local_image="<built-image>.raw"
+    else
+      echo "==> Building Disko image for ${flake_target} on ${node}..."
+      # See the LXC branch above for why this is one %q-quoted command
+      # string rather than separate ssh argv elements.
+      printf -v remote_cmd 'bash -s -- %q %q %q %q %q %q' \
+        "$remote_repo_dir" "$flake_target" "$remote_dir" "$remote_filename" "$NIX_EXTRA_OPTS" "$sudo_prefix"
+      ssh "$ssh_target" "$remote_cmd" <<'REMOTE_SCRIPT'
+set -euo pipefail
+repo_dir="$1"; target="$2"; dest_dir="$3"; dest_name="$4"; nix_extra_opts_str="$5"; sudo_prefix="$6"
+declare -a NIX_OPTS=()
+[[ -n "$nix_extra_opts_str" ]] && eval "NIX_OPTS=(${nix_extra_opts_str})"
+cd "$repo_dir"
+nix build --no-use-registries --no-accept-flake-config "${NIX_OPTS[@]}" \
+  ".#nixosConfigurations.${target}.config.system.build.diskoImagesScript" \
+  --out-link "result-${target}"
+$sudo_prefix "./result-${target}" \
+  --pre-format-files "host-keys/${target}_ssh_host_ed25519_key" /etc/ssh/ssh_host_ed25519_key \
+  --pre-format-files "host-keys/${target}_ssh_host_ed25519_key.pub" /etc/ssh/ssh_host_ed25519_key.pub \
+  --build-memory 2048
+built="$(find . -maxdepth 1 -name '*.raw' -newer "result-${target}" | head -1)"
+if [[ -z "$built" ]]; then
+  echo "ERROR: no .raw image found in ${repo_dir} after build." >&2
+  exit 1
+fi
+mkdir -p "$dest_dir"
+mv "$built" "${dest_dir}/${dest_name}"
+echo "Built and staged: ${dest_dir}/${dest_name}"
+REMOTE_SCRIPT
+      local_image="$remote_path"
+      echo "Built on ${node}: ${remote_path}"
+    fi
+  fi
+fi
+
+# --- upload -- only for an explicit --image; a build above stages its
+# result directly at ${remote_path} on the node already, and reusing an
+# image already on the node needs nothing transferred either. ------------
+echo
+if [[ -n "$image" ]]; then
+  if [[ "$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
+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
@@ -0,0 +1,156 @@
+#!/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}"
+
+# Where this flake repo lives on the Proxmox node itself.
+# scripts/create-proxmox-resource.sh builds images directly on the node
+# instead of transferring them over the network -- it clones the repo here
+# (from this checkout's own `origin` remote) the first time it doesn't
+# find it, installing build tooling via scripts/codex-setup.sh, then
+# `git pull`s it before every subsequent build.
+: "${PROXMOX_REMOTE_REPO_DIR:=/root/nixos}"
+
+# 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 \
+  PROXMOX_REMOTE_REPO_DIR
+
+# 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
+}
@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Shared Nix bootstrap for scripts/codex-setup.sh and
+# scripts/codex-maintenance.sh: the nix.conf settings both need in effect
+# before a single `nix` command runs (flakes enabled, never honor a flake
+# input's own nixConfig, no "dirty tree" warning spam), plus a helper to
+# pull an already-installed Nix's daemon/profile script onto PATH if it
+# isn't there yet. Source this instead of copying it -- see CLAUDE.md.
+export NIX_CONFIG="${NIX_CONFIG:-}
+experimental-features = nix-command flakes
+accept-flake-config = false
+warn-dirty = false
+"
+
+ensure_nix_profile() {
+  if [ -f /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh ]; then
+    . /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
+  elif [ -f "$HOME/.nix-profile/etc/profile.d/nix.sh" ]; then
+    . "$HOME/.nix-profile/etc/profile.d/nix.sh"
+  fi
+}
@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Shared flake-introspection helpers for scripts/*.sh. Source alongside
+# env.sh:
+#   source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib/nix-eval.sh"
+#
+# NIX_EVAL_FLAGS: --no-use-registries so a call here never resolves through
+# the user's global flake registry (every call targets this repo's own
+# flake, or an explicit github: ref, not a registry alias); --no-accept-flake-config
+# so a flake input's own nixConfig (e.g. a dependency's substituters) is
+# never honored -- matches accept-flake-config = false already set repo-wide
+# (see lib/nix-bootstrap.sh / CLAUDE.md). Reuse this array rather than
+# retyping the two flags at each call site.
+declare -a NIX_EVAL_FLAGS=(--no-use-registries --no-accept-flake-config)
+
+# list_flake_targets <flake_ref>
+# Prints the attribute names under <flake_ref>#nixosConfigurations, one per
+# line, e.g.:
+#   list_flake_targets .            # from inside the repo
+#   list_flake_targets "$repo_root" # from anywhere
+list_flake_targets() {
+  local flake_ref="$1"
+  nix eval --json "${NIX_EVAL_FLAGS[@]}" \
+    "${flake_ref}#nixosConfigurations" --apply builtins.attrNames \
+  | jq -r '.[]'
+}
+
+# flake_target_hostname <flake_ref> <target>
+# Prints one nixosConfigurations target's config.networking.hostName.
+# Empty (not an error under set -e) if the target doesn't exist or the
+# eval otherwise fails -- callers that need to distinguish "empty" from
+# "eval failed" should check $? themselves instead of relying on this.
+flake_target_hostname() {
+  local flake_ref="$1" target="$2"
+  nix eval --raw "${NIX_EVAL_FLAGS[@]}" \
+    "${flake_ref}#nixosConfigurations.${target}.config.networking.hostName" 2>/dev/null
+}
@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Shared SSH-host-key / age-conversion helpers for scripts/sync-host-keys.sh
+# and scripts/prepare-host-key.sh -- both generate the same kind of key
+# (ed25519, no passphrase, the sops-nix age-derivation input) and convert it
+# to an age recipient the same way; kept in one place so the two can't
+# drift apart.
+#
+# Uses NIX_OPTS (an array of extra `nix-shell` options -- see env.sh's
+# nix_extra_opts) if the caller has already set it, so a decision to avoid
+# an unreachable nix-cache is reused here instead of probed again. Falls
+# back to no extra options if the caller never sourced env.sh.
+if ! declare -p NIX_OPTS >/dev/null 2>&1; then
+  declare -a NIX_OPTS=()
+fi
+
+# generate_host_ed25519_key <hostname> <keyfile>
+# Writes <keyfile> and <keyfile>.pub. Caller is responsible for refusing to
+# overwrite an existing keyfile -- this always runs ssh-keygen fresh.
+generate_host_ed25519_key() {
+  local hostname="$1" keyfile="$2"
+  nix-shell "${NIX_OPTS[@]}" -p openssh --run \
+    "ssh-keygen -t ed25519 -N '' -C '${hostname}' -f '${keyfile}'" >/dev/null
+}
+
+# ssh_pubkey_to_age <pubkeyfile>
+# Prints the age public key derived from an ed25519 SSH public key file.
+ssh_pubkey_to_age() {
+  local pubkeyfile="$1"
+  nix-shell "${NIX_OPTS[@]}" -p ssh-to-age --run "ssh-to-age -i '${pubkeyfile}'"
+}
@@ -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()
@@ -1,9 +1,13 @@
 #!/usr/bin/env bash
-# Generates a new machine's SSH host key ahead of installing it, so
-# sops-nix has something to derive an age key from before the target
-# ever boots.
+# 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 this is needed: sops-nix derives each host's decryption key from
+# 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
@@ -19,13 +23,16 @@
 set -euo pipefail

 repo_root="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck source=env.sh
+source "${repo_root}/scripts/env.sh"
+# shellcheck source=lib/ssh-host-keys.sh
+source "${repo_root}/scripts/lib/ssh-host-keys.sh"

-hostname="${1:?usage: scripts/prepare-host-key.sh <hostname> [path-to-nixos-repo]}"
-nixos_repo="${2:-$repo_root}"
-sops_yaml="${nixos_repo}/.sops.yaml"
+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. Pass the nixos repo path as the 2nd argument." >&2
+  echo "ERROR: $sops_yaml not found — is this script still under nixos/scripts/?" >&2
  exit 1
 fi

@@ -38,9 +45,10 @@ if [[ -f "$keyfile" ]]; then
  exit 1
 fi

-nix-shell -p openssh --run "ssh-keygen -t ed25519 -N '' -C '${hostname}' -f '${keyfile}'" >/dev/null
+nix_extra_opts
+generate_host_ed25519_key "$hostname" "$keyfile"

-age_pub="$(nix-shell -p ssh-to-age --run "ssh-to-age -i '${keyfile}.pub'")"
+age_pub="$(ssh_pubkey_to_age "${keyfile}.pub")"

 cat <<EOF

@@ -55,7 +63,7 @@ Generated: ${keyfile}(.pub)
 nix-cache/server.)

 === 3. Re-encrypt every secrets file you just added it to ===
-  nix-shell -p sops --run 'sops updatekeys ${nixos_repo}/secrets/common.yaml'
+  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 ===

@@ -63,8 +71,8 @@ Generated: ${keyfile}(.pub)
  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 .#lxc / .#pxe / .#all — --impure is required since host-keys/
-     is gitignored and flakes can't see it otherwise)
+     (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/
@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+# Rotates the &admin sops age key: decrypts with a backed-up copy of the
+# key CURRENTLY trusted as &admin, replaces .sops.yaml's &admin entry with
+# a new key already present in this environment, and re-encrypts every
+# secrets/*.yaml for the new recipient set. After this runs, the old key
+# can no longer decrypt anything -- this is a real, one-way handoff of
+# trust, not a preview.
+#
+# This is the automation for the manual steps create-proxmox-resource.sh /
+# sync-host-keys.sh print when they bootstrap a brand-new, not-yet-trusted
+# age key on a machine that's never had admin access before:
+#
+#   scripts/rotate-admin-key.sh /path/to/backed-up/admin/keys.txt
+#
+# The backup key's *public* key must match .sops.yaml's current &admin
+# entry -- this script verifies that by deriving it, it doesn't just trust
+# the filename or take it on faith. The new key defaults to wherever sops
+# itself would already look ($SOPS_AGE_KEY_FILE, then the XDG default), so
+# the common case is just pointing this at the restored backup.
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "$0")/.." && pwd)"
+sops_yaml="${repo_root}/.sops.yaml"
+
+# shellcheck source=env.sh
+source "${repo_root}/scripts/env.sh"
+
+# sops resolves .sops.yaml by walking up from the process's cwd, not from
+# the target file's own path -- if this script were invoked from somewhere
+# other than the repo root (or from inside another checkout/worktree that
+# happens to have its own .sops.yaml), `sops updatekeys` would silently
+# re-encrypt against the WRONG config's recipient list instead of this
+# repo's. Pin cwd here so every sops/age call below is unambiguous
+# regardless of where the caller's shell started out.
+cd "$repo_root"
+
+usage() {
+  cat <<EOF
+Usage: $0 <path-to-backed-up-admin-key> [--new-key-file <path>] [--dry-run]
+
+  <path-to-backed-up-admin-key>  age identity file for the key CURRENTLY
+                                 trusted as &admin. Only ever read -- never
+                                 copied or modified.
+  --new-key-file <path>          age identity file for the key to promote
+                                 to &admin. Defaults to \$SOPS_AGE_KEY_FILE,
+                                 then
+                                 \${XDG_CONFIG_HOME:-\$HOME/.config}/sops/age/keys.txt
+                                 (sops/age's own default resolution order).
+  --dry-run                      Print what would change; touches nothing
+                                  (.sops.yaml untouched, no sops updatekeys
+                                  calls).
+EOF
+}
+
+dry_run=0
+new_key_file="${SOPS_AGE_KEY_FILE:-${XDG_CONFIG_HOME:-$HOME/.config}/sops/age/keys.txt}"
+args=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run)
+      dry_run=1
+      shift
+      ;;
+    --new-key-file)
+      new_key_file="${2:?--new-key-file requires a path}"
+      shift 2
+      ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    --*)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+    *)
+      args+=("$1")
+      shift
+      ;;
+  esac
+done
+
+if [[ "${#args[@]}" -ne 1 ]]; then
+  usage >&2
+  exit 1
+fi
+backup_key="${args[0]}"
+
+[[ -s "$backup_key" ]] || { echo "ERROR: backup key file not found or empty: ${backup_key}" >&2; exit 1; }
+[[ -s "$new_key_file" ]] || { echo "ERROR: new key file not found or empty: ${new_key_file}" >&2; exit 1; }
+
+nix_extra_opts
+
+age_pub() {
+  nix-shell "${NIX_OPTS[@]}" -p age --run "age-keygen -y '$1'"
+}
+
+echo "==> Deriving public keys..."
+old_pub="$(age_pub "$backup_key")"
+new_pub="$(age_pub "$new_key_file")"
+echo "    backup (old admin) key: ${old_pub}"
+echo "    new admin key:          ${new_pub}"
+
+if [[ "$old_pub" == "$new_pub" ]]; then
+  echo "ERROR: backup key and new key are identical -- nothing to rotate." >&2
+  exit 1
+fi
+
+current_admin_line="$(grep -E '^  - &admin age1' "$sops_yaml" || true)"
+if [[ -z "$current_admin_line" ]]; then
+  echo "ERROR: couldn't find a '&admin age1...' line in ${sops_yaml}." >&2
+  exit 1
+fi
+current_admin_pub="$(awk '{print $NF}' <<<"$current_admin_line")"
+
+if [[ "$current_admin_pub" != "$old_pub" ]]; then
+  echo "ERROR: ${backup_key} doesn't match the current &admin key in .sops.yaml." >&2
+  echo "  .sops.yaml &admin: ${current_admin_pub}" >&2
+  echo "  backup key pubkey: ${old_pub}" >&2
+  echo "Wrong backup file, or .sops.yaml has already moved on -- not touching anything." >&2
+  exit 1
+fi
+
+mapfile -t secrets_files < <(find "${repo_root}/secrets" -maxdepth 1 -name '*.yaml' | sort)
+if [[ "${#secrets_files[@]}" -eq 0 ]]; then
+  echo "ERROR: no secrets/*.yaml files found under ${repo_root}/secrets." >&2
+  exit 1
+fi
+
+echo "==> Confirming the backup key can actually decrypt..."
+if ! SOPS_AGE_KEY_FILE="$backup_key" nix-shell "${NIX_OPTS[@]}" -p sops --run \
+  "sops -d '${secrets_files[0]}'" >/dev/null; then
+  echo "ERROR: backup key failed to decrypt $(basename "${secrets_files[0]}") -- aborting." >&2
+  exit 1
+fi
+echo "    OK: decrypted $(basename "${secrets_files[0]}")"
+
+if [[ "$dry_run" -eq 1 ]]; then
+  echo
+  echo "[dry-run] would replace .sops.yaml's &admin line:"
+  echo "[dry-run]   - ${current_admin_pub}"
+  echo "[dry-run]   + ${new_pub}"
+  echo "[dry-run] would then re-encrypt (sops updatekeys --yes) for the new recipient set:"
+  for f in "${secrets_files[@]}"; do
+    echo "[dry-run]   secrets/$(basename "$f")"
+  done
+  echo
+  echo "[dry-run] Nothing was changed. Re-run without --dry-run to apply this."
+  exit 0
+fi
+
+echo "==> Rotating .sops.yaml's &admin key..."
+sed -i "s|^  - &admin age1[a-z0-9]*|  - \&admin ${new_pub}|" "$sops_yaml"
+grep -qF "$new_pub" "$sops_yaml" || {
+  echo "ERROR: sed edit didn't take -- .sops.yaml left unchanged, check it by hand." >&2
+  exit 1
+}
+echo "    Updated."
+
+echo "==> Re-encrypting secrets/*.yaml for the new recipient set..."
+for f in "${secrets_files[@]}"; do
+  echo "==> $(basename "$f")"
+  SOPS_AGE_KEY_FILE="$backup_key" nix-shell "${NIX_OPTS[@]}" -p sops --run \
+    "sops updatekeys --yes '${f}'"
+done
+
+echo "==> Verifying the new key can decrypt everything..."
+for f in "${secrets_files[@]}"; do
+  if ! SOPS_AGE_KEY_FILE="$new_key_file" nix-shell "${NIX_OPTS[@]}" -p sops --run \
+    "sops -d '${f}'" >/dev/null; then
+    echo "ERROR: new key failed to decrypt $(basename "$f") after rotation -- investigate before committing." >&2
+    exit 1
+  fi
+  echo "    OK: $(basename "$f")"
+done
+
+cat <<EOF
+
+Done. .sops.yaml's &admin key is now:
+  ${new_pub}
+
+The old key (${old_pub}) can no longer decrypt any secrets/*.yaml
+re-encrypted above.
+
+Review the diff, then commit:
+  git add .sops.yaml secrets/*.yaml
+  git commit -m "Rotate sops admin age key"
+EOF
@@ -0,0 +1,443 @@
+#!/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"
+# shellcheck source=lib/nix-eval.sh
+source "${repo_root}/scripts/lib/nix-eval.sh"
+# shellcheck source=lib/ssh-host-keys.sh
+source "${repo_root}/scripts/lib/ssh-host-keys.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() {
+  # 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.
+  list_flake_targets "$repo_root" | grep -v '^installer$'
+}
+
+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"
+      generate_host_ed25519_key "$host" "$keyfile"
+    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="$(ssh_pubkey_to_age "${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 "$@"
@@ -5,67 +5,85 @@ sops:
    age:
        - enc: |
            -----BEGIN AGE ENCRYPTED FILE-----
-            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBmaFVBeVp3Zk80TG1OU045
-            b204QzFYL1psVm1xdlBVYmVIWFpKVnJWbUdvCnJRVGVUbElPYVczeEdkSDU4WGYz
-            bkliK0dGcitjZnRYUXJQVVpTY2gva0kKLS0tIHBxMDBNYWJrSHAvNlZDWERmbVQ3
-            VDFscTRjdGpLUnk5VVdyTjY5MFNPSW8KX5Or/zoixFulaX8ljY4ke3jdhc3Jaw95
-            4BqrlILGapcOsmWTDkDZBtS81oNvlRnH+xaM2UJSe+nIplNcC+Cl2g==
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBaMUpxYmUzaVY4d1pRY3g3
+            empaVUJSN0JaSlNQQlJtZENwc0VMYVhJSkFvCmJQMkpSd3RoYzlKQjBSZWErQzR2
+            aG5SVndOQWpSRTBDSWJVQkg0c0hiNFUKLS0tIHhiaEdpY3gwZkpCcHl2TW5CNThn
+            aVVUQy9Qd0trb0RNdUpVTXdrdGlrTmcK1uphQAyDV+Gk5+K1YOqw1Z8ynGP5sAPF
+            q5icujja/SGexX18hPYXbkyUtOrBYjW62gCuGJinSBPROoFUJbiP7g==
            -----END AGE ENCRYPTED FILE-----
-          recipient: age10nd382a9klsn2mrs60emdtsxe43pht3a0m9p29phfrhy0wfyt3vsq9r667
+          recipient: age1njap586hc0q43kr03g6c8eqhdsmk8zcafkl3f83xwlc2gqhlmfgs4tmwad
        - enc: |
            -----BEGIN AGE ENCRYPTED FILE-----
-            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSB1ZUZ0bXRGVFMzZzg1TzhE
-            N3kwYjdEV0tmcVdacVJHZUNXRHo1aHhXczFBCm1WcW51K3NSK25uMUFNb3NRbE9J
-            UE00VWNIclhVZHdPUmlNOXI1aGlhck0KLS0tIFphckVmRXZrTmI5K3BUL3NlMTAv
-            OG9RTHNEQXVMcXVWZXZnN2NYZ3hraUUKEXrloIgmADuRpa2YN2GIRYT+YN60pxga
-            bLeVDtBYU+KA+2F8S46o43ZmRTE2MXWlMhnZ35uNR4hgE3auKlIziA==
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBKOWZxcFlhRHhKelhDS29M
+            NGRlTEhJUGUzcFV6QVFCdTNkdEN3MlljWnl3CnI3LzVxSHBwSi9TYlRUcFdyN2py
+            cVZBV0Q3Z3FhRXA0T1NFQzd2R00yeEUKLS0tIHkxL2dHV3RkVFYxZTJNTVZvVFIr
+            TXpJZzdnYlpJaXBmcjdWWUtxNkc4dWMKVsImJiavzUzSFn78pciNJPHaS3KWqJer
+            VkxF6kF3tl2HmW46eVXtsQowdu+zVR9HS35i/HvQ1r1TyP6qT5ofcQ==
            -----END AGE ENCRYPTED FILE-----
          recipient: age19gfn2yedg76dmztm4hncr7vf3r3c9j0qpt4rap7y7gersjk4m3ks2lhd0e
        - enc: |
            -----BEGIN AGE ENCRYPTED FILE-----
-            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBZdXBMY2t6U0VBWjRyWUV2
-            WS9oS0tWUnBQMWhPc3VsTVVKSnZSemxvU0FZCmFWbzFEZEZrMzJxTmpJKy9HY2F5
-            RHBjcUNYZ1R5ZHUxVmhPYjJRQkZyMU0KLS0tIGcvZ2hPQURmanJLRjRaNEJtTml3
-            dElTa2hZck1rSG1HcDBVSjZQNjhzT0EKgUylDuQBZkW1Z6AB/EsVbxcippw5XOeY
-            e+NDtqFixYR1u57+fKVl5dY281kspYIQDCUx1lBZiH7iwUPZWNtEfA==
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSAyWjdSanRRaEI4VHFZVkdw
+            NkxMODRuakFJTFNoTHZIRHptZFNxaGZ3K3lnCjJGR1FJalRsYmtLcHFxZW8yNU5W
+            MzBjWmltbzI3MTByUjB6djlEdllHNXMKLS0tIEhEOVhLVjZkRi9vUEtDWUhxT0NX
+            eUZ3bGdEaHdGbXZIYkowYUZuTWJ3d2MKMwgxOqlMH7GfLlseD4J277Dcg0KCD3d5
+            jwJDb82kRWoBMicTJZXoq/5oe5blJNa7dWYoqgkYxMA2O+0igT+I6g==
            -----END AGE ENCRYPTED FILE-----
          recipient: age1ll6hj5ggruetgjwjfnplpn5xtq35uhlcdflksx3xmnjm6s3uad9sz70jkf
        - enc: |
            -----BEGIN AGE ENCRYPTED FILE-----
-            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBHYWtBYmU2Qk0vQ2dUQjUy
-            RGs1b1BzVm82Z210MGcrbnhiS0pCVnJzbkFVCnhpZUxSVmZTd0VSM0ZvZ01tM2hP
-            QlJ4NUQ0VjBBSXJGR0VScE5zNXhjVjgKLS0tIFZyNVF2a2VPdzhyZ1MzN3dYa0xx
-            U0tqTWZNSDdHU3Z5UHNBbGR6aFZ1MDQK7z0OC0yazekxpLmiKFuqWZm1rWMZqpXb
-            FGnZFMDdEwB5wTeiy4LCXS70zyr5eVT7KPeK25EG6pXQ4qqKZ12CyA==
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBsZzdRMm9zdlJHckFoREVs
+            UkVXL3dCeWRuN2NqcnVsOWVNT1FLUHY3andrCmNFY0ZCby9SdnUyYlV6R05YNDB0
+            em43SjRCNVhYbmpRZUVWT0cxQlhGdmsKLS0tIDZHazNyck5VNHBuNVM5bmRZUlpR
+            QzBSNy84VDdLVkZZbnNlUFYydXlreEEKYZaR2b7tyRAhPdP+ytpP0veUTi7pY9Nw
+            pK0h4hcegLNYJL1AfOYwFQoW7vb256GdmwdcuuBl1YBGXWGraaBnZg==
            -----END AGE ENCRYPTED FILE-----
          recipient: age120le4a5l8dh3lyfgvmj3d9ksmej6ajs5mer5y7r0vfg3x9fn69dqf8xgzu
        - enc: |
            -----BEGIN AGE ENCRYPTED FILE-----
-            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBqSG5NemtzUXlhelpvblFl
-            TldjUGVtZFFXWGM5ei9EN3V5N2ZLY0VRV0RJCnFNN1lVNmhWckFWbUVJd0grR2Ja
-            MmdYazZLUVFpelUyMFhta3dGSEc2Mm8KLS0tIHl4TlhhVFVOcmkxaHpKVWlrdEJx
-            VlBQazd5MG1yc3E0TzQrd3FmWG8wd00K8+cAm4oWVraERb8i8EurAnsR/L085uPR
-            zzIZEYW6hHxf9Ah9vMzM+3KIsnnS0Gr5QT8ATzpd8huXCqPNiveDFQ==
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBFSnZiOGpsL1BESWVEdUxx
+            dXc5LzBHTlNodGJ1S3hOeHd5Wmgxb3BPSHl3CnBEWDNTc3NDdzN3RHQxUlNLOEs5
+            RU1SS2tVT29XbDJCWVliWnVkekN4L1kKLS0tIGFqY2pNK2h2S2ZWMndrRVN6eUdN
+            M0NLY2EvTTVIYlZvdk9XY0NwNE14ZlEKcOwgCK3g56kId/4tEt+2iCcylisn+Fca
+            5VWamsXdbwxbxmCEEUbgN3aHrdVz3mV4+8FZqA34yXz8pc45/PUcFg==
            -----END AGE ENCRYPTED FILE-----
          recipient: age1qz9d4ka4xgexujyd247s7lp737sulp5fhxl5d65fj2ykvc4j4edqrsdks8
        - enc: |
            -----BEGIN AGE ENCRYPTED FILE-----
-            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBQdDdQUEh6ejg3UG1LMi8w
-            bTJacGZQY3dUVEtJY3NGeWpxYWRITkZpN2swClVmb2F5N0phYzRXVG1RY1NsUm52
-            OWVLY3FJU0JXcGFVZDJGdVJ0dVhBN0UKLS0tIEl2b3JjV2JaS0crMnRpZElGdDZS
-            MDFyelRvcUsyUDdtai9IYnpHK3g2L2cKlvZloUKACDy9OyRI7ruPUjYqFENXzcVI
-            amFHFTbEGKVWIPwDjEwsMT+S4bHBkNWyny5dD5CrBpk7fiyQ+5U8+Q==
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBJU1cydFFuRnpCUU5mbjFu
+            TTIxREkxZ1hMalVtNjNjcHVaUXpPNWdib2tzCkRScWRTWHhxN3lhckI4UFpMSFRa
+            RGxWcldlWnd5SVJFNWxQWjB3R0pMb3MKLS0tIGdjLzlhTHgyT2hjTmRTK1RiZmxS
+            OWRWYklBWkoyUG8raFNzd3JlRUtEUEUKw+NdAp1Mz0dEOUGPbqCV8y7029I3Kye0
+            keU2T29JGCN1D6x//1NcMUYSaFZKgv0ZVSjVUCl1EnmlJ0nBdbaDXA==
            -----END AGE ENCRYPTED FILE-----
          recipient: age120whqj96g26lsgy4udvgsn8dc9lumh8jeu3a564fx79rjr5lxffqmrljuu
        - enc: |
            -----BEGIN AGE ENCRYPTED FILE-----
-            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBTZnZIa2xXM3RIYk1tbitC
-            NlRTeXFib3JDdXdhR01ZdUl6Z09vWmllRGxBCnpPalo4K0JhRlNpQ2d0b2RNcjUx
-            K3FRaXdMVHZud2FKRkw4UDREL1NrMDgKLS0tIE5CZDBHRXNscG9JK1hvWlZPVjJy
-            d0d2VnE4bXd6MGNPVzVUdFdocDYzcHcKW2Hs5oBO5ooc/uqWV/TOjq1xsxFR204s
-            GRtFUOg9tfglk3TcQbgZV0/pYlBJYzgb7iZD0qVe4XYj68q1A1bPwQ==
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBnNFlzYVBqaGFDVE9xbmt5
+            OVd4ZlZRdEVJd0JFdkRIYVA5ZUEwYjJjWVJjCnZzTExNbDlYbGN6c1dYU2ZlNEVs
+            ZUo4MXdpc0tzbDI0MHl5eXc3d09VRDQKLS0tIGs4SGMya1RZQ0hpa2NtQk9Wa29C
+            bmxIYWk1VThsaFhxRDlOOGhGQ2tYamsKs+PcOiaeNFujCWwZBr+nq1MzrGohl+ch
+            TASI7eNsiHmSVRzSMHv4mX+8yXDHIRgHbFuUty2gdgGFLRjYXe4gDA==
            -----END AGE ENCRYPTED FILE-----
-          recipient: age164px2a8e48ptsf9ngtan38aa6jls4jdl26mzrgzf6sn3vcvt49hqjrgr8w
+          recipient: age1xjst4frdh0th6q8m7p7u9g5af7ty5jqeum0p6z8a52a9q7st7ewqw8yl9j
+        - enc: |
+            -----BEGIN AGE ENCRYPTED FILE-----
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBkcmVQYXV1NzRrQ2IxTElt
+            QUJRMkhiUUJqRDdwQW03K0lCTEtkSTU5UDJrCjh6SldpQkF1NzIybTJTdnBlOHdQ
+            VlREMy9hM0ZaL21Pa0VPUzcvb0pQQjQKLS0tIFcrK0I3Z3Nhem45eHpZYmdWeit6
+            eXFtRHVxODhaNTVDdVR1a2tOb1N1U1EKZBdLHq8PRMKX2ndFr3AxFVAZRyvhFa1u
+            72R5tordo4IR3HSxG3Z06rokOITd+KKhaQ8NEWEC8qioAAMxEC9QWw==
+            -----END AGE ENCRYPTED FILE-----
+          recipient: age10at8862478urh0eeuwh8hzln6ck78jgwtztgxatwqlzwagg77y5snm4xzg
+        - enc: |
+            -----BEGIN AGE ENCRYPTED FILE-----
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSA0WjJPbXhXNTNyQUZzMmxS
+            Rkd3Yk5Ga3pPRXFtMFpXcmpBZ3RJYnJlaHhjClRDbFBHRVZ0SDdrNFdVWmUwalpT
+            WUt5a2RUTnQ4VFBGMlowR3JycDM3aXMKLS0tIERSeFd4cGdSbzRpSmpSQnB1Yng5
+            OHBma3lYeWEwQ2RvelpzZHRkN1JPWFEKLXkJfEkH3lo5Z4mj8PZXTfAfZn6B46To
+            U0G54tUh0U1EeMnI5ZPRGwDxi5K0eD68HjeE9MBvFBysOChP/ANDPQ==
+            -----END AGE ENCRYPTED FILE-----
+          recipient: age1ezk9x53zt8kcnscdm80jcyf0xq97vndv7jsn3rl8cc0cwm2jmpmq372dzs
    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
@@ -1,34 +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+IFgyNTUxOSBDbHd1Y1dpa2ZiQ2E1bXRP
-            SnkrWHI0V2U1eGFKY0RZamZQQjluS0hGeENZCmduUFQyd1Q5RkZGMGFoenJhNmZh
-            VmZ2OStNaFpJejFxQ2JUZXFpNThaMncKLS0tIEhJdGdQeXEzb25Nbk5YZktCWVUz
-            NUJDUWRoTkd5R2pFblZjS0NSbVR5dkkKDYeW+zRpha04/CasFM91K6v1PpkNGHRu
-            qAoKs9KSg9VxS7ya8RuLmylKRdpPkupm/8SXIJvQuCXp5LWmNJ4zkA==
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBmOHlPcGZvN3o5aEZCcFdz
+            WlYydFdoQ0ZHbElMdTRkZWljMmoxTHZqNjJZCnE3cmgzKzZya3FROEczbHVveDND
+            VnEzRW12cnRKdzhkZm5uTXpkTEtrNUEKLS0tIHFDbkc4Mk4wVlM2R29zZXYwR2Ri
+            ODBML1p4eUZiZldYUERQTUhTU1llV0UKxjvH6zbW6wKghzR1o34CyKPEa2FqZmo0
+            PxgqyuXkIwas9soXVAkScx7ElaV09Fjaj+mDrKwi4a+DwdoSP7czyA==
            -----END AGE ENCRYPTED FILE-----
-          recipient: age10nd382a9klsn2mrs60emdtsxe43pht3a0m9p29phfrhy0wfyt3vsq9r667
+          recipient: age1njap586hc0q43kr03g6c8eqhdsmk8zcafkl3f83xwlc2gqhlmfgs4tmwad
        - enc: |
            -----BEGIN AGE ENCRYPTED FILE-----
-            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSB4UktiUUdmd092bnZMdFMz
-            Q05xVlhnNzhPZUY4TjF5bjRCbklacTdJd1RBCnJ4bEVMaWRLZExIUFVEUDBXTnlV
-            MDU4WUk5VlJjdlhVUVpzZXlnWHhqTjQKLS0tIE9iclhGVElPcU9OLzF0bEVjMjVp
-            YzlQTGFYZEhLdTk3N3ZramVjVGRXREUKjOjqO/jX5iEKN43WiJ8qS/1mDfxdj8uO
-            K7Yyc/Yj0qMvGwLNzphjmbT29P7dXk4Ht4TedqCd+8DfhpOgLVIaSA==
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSB0VDBXYUZNbnpEZHlqV05C
+            WWxQZjVYcWlZeXlGc0RiaUpERzR0T21CWWtBCkM0dW5kYlFNK1RGSzRudFZ2Z0t3
+            aVBreElGM1BIT0RzQkxTVTA3S2NhQncKLS0tIERyTU8zWWRTRm95SmRZQ1BhalVV
+            SVdBajN1V1BuM2s4K216S3c0VHczNlkKM5jvsSEfCBA5uZRjBJNbM91lLRQkj+jK
+            rM5uSfGLTvSjPgXIMIq03OXxH1CE7GoKxAPwFrJdAFMMQcutIethhw==
            -----END AGE ENCRYPTED FILE-----
          recipient: age120le4a5l8dh3lyfgvmj3d9ksmej6ajs5mer5y7r0vfg3x9fn69dqf8xgzu
        - enc: |
            -----BEGIN AGE ENCRYPTED FILE-----
-            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBjaXpvQU9yRUc3ektPMmU5
-            Q0xLWU9mYXVOeTVBNGNsZzJPa1lkVlRUZHlvClhoSVV6YjB1Q3pTTzVvNFlNYkU4
-            Y2RrbFk5SUFKSDVjeFU0Wlc2aGFUMFUKLS0tIDlVeXM4WWRUakg4Zk5mcjdJL3VC
-            S1k5eFBpVnREQlZwYllpeTNhWW5GS1EKi2sMwyJJ0D8acjCZmxlcwdU1sglBuxR7
-            2SEMsctdGC+5E3ilPXvPpZ5RONZHbXxn6kQRBlBv6AJERpGDzsfgfA==
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSAvbk9tRE9jYkpxNThQeElH
+            dWpKYThDb1ZkUWtMWlRxc2tYbjhBbEFEcWtVCkNiK0NBRko2TkJQdUVtdGtHNGcv
+            andSaUlKSFA4THRyZXNTYmI0Yk5WbmsKLS0tIHlQTUtpWDdPeTVZL0M1RElRdFNk
+            QWlGdFo5NkZWSmY0YXdpNzNUQnlsK3MKtzC0bM7Ek+K73nMranOA1Mc98RUnYnq1
+            hAt0QEFKWK4QVKubaN/rG3AzE0U7qPKWHTzoxgnAiL3WyV9teLW+iA==
            -----END AGE ENCRYPTED FILE-----
          recipient: age164px2a8e48ptsf9ngtan38aa6jls4jdl26mzrgzf6sn3vcvt49hqjrgr8w
-    lastmodified: "2026-07-19T02:30:40Z"
-    mac: ENC[AES256_GCM,data:7+FeT6aeCGn+JFBXbPO0qP4BJ1nHPSennewv1kWkG+hOTIqs1ymuswUK1Hyfi6Z9h2umFX9HvK+o3qtmYvk6k7BUNe6w6QUHTNwm6lmNqrb7sgAE3iFVI2p9m14NGhgoTfnXx1M4JIZ1iuNYhCukpENI4+svIe+r7x5YeE5Evac=,iv:4AKAPI6upyAvHBr8BLWX7R/NupmJdcXdqiN8e0ZQ3ls=,tag:TkpfpCaLhn+Mx5cQZZuMdA==,type:str]
+    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
@@ -3,20 +3,20 @@ sops:
    age:
        - enc: |
            -----BEGIN AGE ENCRYPTED FILE-----
-            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBxaFZURjAxMGRJZEJ5MW1x
-            ZjVwWEQrQlkwNmRibVNiL2RpTTFLeUVDQ3hRCkVIamVnZkM1MnlueloxMHVFQnBF
-            RjV2bnUrZUo4WGZJTmR4Y0xITkxRUkUKLS0tIGlJdVQ5MFBubVhxRUVMWW0wSGpP
-            UGdKNUNPYW9nek1UZ0tWbXd3QVNUNDgKIHOiKelITQdH5R4Nc3WF7mzz15D1f9on
-            VaTdr5qkf8LNNvPI0fxsXA9is5cqeg+KbDRHtUumEhNp6Zrf8zWBkw==
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBURmMzN3hrSlNrUkkvVWNl
+            L3M1dEhWeW14N0RFNVRPci9QK1YyTFdqRVVJCk5WaWswT2NicldkYzZjbVhYU2xu
+            MGFsNmUzeTN2TS9wOEdvRURpVUVYZXMKLS0tIDZ6MEdPTVhCaTQ2UXFWTUFtc0pm
+            MFlJb0c2WXJtMGRLZEZYY0pZWWpFWm8K/mlYZIe8UC0QU+1mq3NtrtTF5b2m5hCK
+            +K0QiZLTKmmDcr4bRhZ32VE7R7GRwtMNnOP/mElZvPAyWyHHhRiOHg==
            -----END AGE ENCRYPTED FILE-----
-          recipient: age10nd382a9klsn2mrs60emdtsxe43pht3a0m9p29phfrhy0wfyt3vsq9r667
+          recipient: age1njap586hc0q43kr03g6c8eqhdsmk8zcafkl3f83xwlc2gqhlmfgs4tmwad
        - enc: |
            -----BEGIN AGE ENCRYPTED FILE-----
-            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSA3N0hvV01naytDSWVwK1B1
-            MXM1ZkdpaVc2Q3FPV2VBcC83WmcvSjdGUGgwClJGSXZ6YW5JeFlValNJbjVhK29u
-            bUFqN2dRQTI4ZkwyeXNWYk5JeWVJRXcKLS0tIDlMMkNBUnNUSTJwVVFmc2dlcEZS
-            VGQ1VHR2dXB0M3RsalppVWxiUUROM0UKZM/4QDTam3LDTzjnDs41Ije50R7Q7GC4
-            IZbUZjs72rBzY8IkJDbN9JidadEc4NAtMOJwXiJbpZGiCBNfc8+SXw==
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBURHlUL0RNMUtNallEcG5p
+            eG4xby8yVzdQUTBaNkl4ano0YjBMcDd0Wm5NCkZvaXNPZm9wemJkMmNSdGdOaTI4
+            Z1RwUnhiRUpCMWZaeWtlSVBmNW5KOXMKLS0tIDk0R0k3ZHczTFNCWUZxSWF0M0FJ
+            MGlZMmtuSFYrcG1meDNMWDNqSjFxcE0KDu2dAc0gqmmPkpbpBe4YohM7rYmUwEkI
+            V2FUQwjlvh50svtjCVdYbx2xuq4sQLnKelk/q1onLw60FwsVfzD8sQ==
            -----END AGE ENCRYPTED FILE-----
          recipient: age1ll6hj5ggruetgjwjfnplpn5xtq35uhlcdflksx3xmnjm6s3uad9sz70jkf
    lastmodified: "2026-07-19T02:30:40Z"
@@ -12,8 +12,22 @@
  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.
@@ -32,13 +46,114 @@

  # System
  timeZone = "Australia/Brisbane";
-  primaryUser = "nixos"; # main interactive user on every host
+
+  # 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`

-  # Well-known ports for LAN services referenced from multiple hosts
-  beszelHubPort = 8090;
-  pveWebPort = 8006;
-  pbsWebPort = 8007;
+  # 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
+  };
+
 }