Parker Jones Dev Blog - homelab

Nix Fleet, Part 3: Fleet-Wide Secrets with agenix

2026-06-26T00:00:00+00:00

Nix Fleet, part 3. Part 1</a> covered the architecture; Part 2</a> made builds painless. This part handles the thing you must not commit to a public config repo: secrets. </blockquote>
My whole system is declared in a Git repository, and most of it is public. But a fleet needs secrets — API keys, SMB credentials, a WireGuard config — and those obviously can't sit in plaintext next to the rest of the config. The constraint that shapes everything here: I want secrets to be versioned, shared across every machine, and reproducible, with the same Git-reviewable discipline as the rest of the system — without any secret ever appearing in plaintext, in the repo, or in the Nix store.
agenix</a> gets me there. Here's the setup.
Two repos, one boundary</h2>
The cleanest decision I made was to put secrets in their own separate repo (nix-secrets</code>) and pull it into the system flake as an input. I keep my real one private, but I've published a public example repo</a> so you can see the shape:
# flake.nix inputs.secrets = { url = "git+ssh://git@github.com/parallaxisjones/nix-secrets.git"; flake = false; }; </code></pre> That boundary pays off operationally: I can lock or revoke access to the secrets repo independently of the (public) config, rotate recipients without touching application code, and grant a machine read-only deploy access to just the secrets it needs. The public config can stay public because the sensitive bits live behind a separate door. How agenix encrypts</h2> agenix is age</code> encryption wired into Nix. You declare, per secret, which identities are allowed to decrypt it. That declaration lives in secrets.nix</code> in the private repo: let # macOS (pjones) and NixOS (parallaxis) decrypt with the # same ~/.ssh/parallaxis identity. pjones = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...oqt7Aq"; users = [ pjones ]; in { "openai-key.age".publicKeys = users; "anthropic-api-key.age".publicKeys = users; "datadog-api-key.age".publicKeys = users; "datadog-app-key.age".publicKeys = users; "smb-credentials.age".publicKeys = users; "protonvpn-wireguard.age".publicKeys = users; } </code></pre> Each .age</code> file is encrypted to the public keys listed. The matching private identity — and only that identity — can decrypt it. The encrypted files are safe to commit (to the private repo); the identity never is. One identity for the whole fleet</h2> Notice that users</code> is a single key. That's deliberate: both my macOS and NixOS machines decrypt with the same ~/.ssh/parallaxis</code> ed25519 identity. agenix can use an age</code>-native key (age-keygen</code>) or reuse an existing SSH ed25519 key via age-plugin-ssh</code>; I reuse the SSH key so there's exactly one secret-decrypting identity to manage across the fleet. The trade-off is real and worth stating: one identity is one thing to protect and one thing to rotate, but it's also a single point of compromise. For a personal fleet that's the right call — fewer keys means I actually keep the rotation story straight instead of letting five per-host keys drift. If this were a team, I'd encrypt each secret to multiple recipients (one per person/host) so revoking one doesn't force re-keying everyone. agenix supports exactly that; it's just a longer publicKeys</code> list. How decryption works at runtime</h2> This is the part that makes agenix better than "stash a .env</code> somewhere." At activation time, NixOS/nix-darwin decrypts each declared secret to a path under /run</code> (tmpfs), owned by the user/service that needs it, with the permissions you specify. The decrypted value: never lands in the Nix store (which is world-readable and gets copied to your binary cache),</li> never sits in the repo in plaintext,</li> exists only on the machine authorized to decrypt it, only while the system is running.</li> </ul> So a service reads its API key from a file at /run/agenix/...</code>, that file only exists because this machine holds the identity that can decrypt it, and the policy for who-can-read-what is reviewable in secrets.nix</code>. Secrets management becomes declarative and auditable, like the rest of the config. Bootstrapping a brand-new machine</h2> The chicken-and-egg problem: a fresh machine needs secrets to be useful, but doesn't yet have the identity to decrypt them. My flake exposes helper apps for exactly this lifecycle: nix run .#create-keys # generate keys on a new machine nix run .#copy-keys # place an identity where agenix expects it nix run .#check-keys # verify the identity can decrypt nix run .#install-with-secrets # first install WITH secrets provisioned </code></pre> install-with-secrets</code> is the interesting one. On a first NixOS install it runs disko</a> to partition, stages the repo to the new root, and installs via the flake — and crucially, it relies on SSH agent forwarding so the installer can fetch the private secrets</code> input without ever copying a key onto the installer media. Nothing persistent is left behind on the installer once it's done. The machine comes up on first boot already matching repo state, with its secrets provisioned where they're declared. Why this beats the alternatives</h2> vs. plaintext .env</code> / committed config: secrets are encrypted at rest, never in the repo, never in the store.</li> vs. a cloud secrets manager: no external dependency, no per-machine bootstrapping against a third-party API, and the policy is in Git where I review everything else.</li> vs. copying keys around by hand: the recipient list is declarative; adding or removing who-can-decrypt is a reviewable diff, not a tribal-knowledge ritual.</li> </ul> The throughline of this whole series is "manage it declaratively, in Git, reproducibly." Secrets are the case where people usually give up and do something ad-hoc. agenix is how I kept them inside the same discipline as everything else. Next, in Part 4</a>, I put all of this to work standing up an ARM NAS from bare metal — disko for the disks, agenix for the backup credentials, and nixos-anywhere</code> to tie it together. A public example secrets repo is at parallaxisjones/nix-secrets</code></a>; the fleet config that consumes it is parallaxisjones/dotfiles</code></a>. — Parker Jones, parkerjones.dev</a>



Nix Fleet, Part 4: Installing a Helios64 NAS from Bare Metal with nixos-anywhere and disko
2026-06-26T00:00:00+00:00

Nix Fleet, part 4.</strong> The series so far: the one-flake architecture</a>, remote builders</a>, and fleet-wide secrets</a>. This part is where it all gets pointed at bare metal — a 5-bay ARM NAS, installed declaratively and reproducibly.</p>
</blockquote>
The Kobol Helios64</a> is a 5-bay NAS built on a Rockchip RK3399 (aarch64</code>, 4–8 GB RAM). It's a lovely, slightly cantankerous little ARM board, and it's the storage backbone of my homelab. The goal for this host was the same as every other machine in the fleet: I should be able to reinstall it from the flake and get an identical result, disks and all.</strong> No clicking through an installer, no hand-partitioning, no "what did I configure last time."</p>
That's what disko</code> and nixos-anywhere</code> make possible.</p>
The two tools</h2>

disko</a></strong> turns disk layout into declarative Nix. Instead of running fdisk</code> and mkfs</code> by hand, you describe</em> the partitions, filesystems, and pools you want, and disko makes the disks match. Partitioning becomes config you can review, version, and re-apply.</li>
nixos-anywhere</a></strong> installs a NixOS flake onto a remote machine over SSH — it can kexec into an installer, run disko to lay out the disks, and install the full system, all from my workstation.</li>
</ul>
Together they collapse "install a NAS" into one command:</p>
nix run github:numtide/nixos-anywhere -- --flake .#helios64 <ssh-host>
</code></pre>
That partitions the drives per the disko spec, installs the helios64</code> host config from my flake, and reboots into a running NixOS. The disk layout is no longer a one-time manual act I'd have to remember — it's part of the host definition.</p>
The ARM-specific bits</h2>
An ARM SBC NAS has a few wrinkles a generic x86 box doesn't, and the host config names them explicitly:</p>
# hosts/nixos/helios64.nix
{
  networking.hostName = "helios64";

  # The RK3399 needs its device tree to boot correctly
  hardware.deviceTree.enable = true;
  hardware.deviceTree.name = "rockchip/rk3399-kobol-helios64.dtb";

  services.openssh.enable = true;
  system.stateVersion = "24.11";
}
</code></pre>
The device tree</strong> is the load-bearing line — without rk3399-kobol-helios64.dtb</code>, the board doesn't come up right. The boot chain itself is U-Boot/Tow-Boot on SD/eMMC with the NixOS root on SATA. And because this is aarch64-linux</code>, the system image builds on my x86 box via the emulation I set up in Part 2</a> — I never need a native ARM build host just for the NAS.</p>

A note on honesty: the committed host config is intentionally minimal right now (it even evaluates as a container in CI to bypass boot/filesystem asserts). Storage and services are phased work. So treat this post as the design and install method</em> I'm executing against, not a claim that every service below is already live. The series documents the build as it happens.</p>
</blockquote>
Storage: ZFS, and why</h2>
The storage decision got its own ADR</a> (I keep architecture decision records in the repo — docs/adr/0001-choose-zfs-for-helios64.md</code>, accepted 2025-08-27). The short version:</p>
Decision: ZFS.</strong> End-to-end checksums, snapshots, send</code>/receive</code>, and self-healing are worth a lot for data I actually care about, and NixOS's ZFS integration is mature. The cost is memory pressure on a low-RAM ARM board and tighter kernel/module version coupling. The alternative considered — mdraid</code> + ext4</code>/btrfs</code> — is simpler and lighter but has weaker integrity guarantees. For a NAS, integrity wins.</p>
The pool config reflects the board's constraints:</p>
boot.supportedFilesystems = [ "zfs" ];
services.zfs = {
  autoScrub.enable = true;
  trim.enable = true;
};
# On a 4 GB board, cap the ARC so ZFS doesn't starve everything else:
# boot.kernelParams = [ "zfs.zfs_arc_max=1073741824" ]; # 1 GiB
</code></pre>
Sensible defaults for the pool (tank</code>): ashift=12</code>, compression=zstd</code>, autotrim=on</code>, atime=off</code> for bulk data, and a topology chosen by disk count — mirror for 2 disks, RAIDZ1 for 3–5, RAIDZ2 when I want to survive two failures. Datasets split by purpose: tank/data/shares</code> for SMB, tank/data/media</code> for streaming, tank/backups</code> for restic targets (with credentials supplied by agenix</a> — that's the payoff of Part 3).</p>
The gotchas this board taught me</h2>
Real hardware has opinions, and the runbook records them so I don't relearn them at 2am:</p>

The 2.5GbE port can be flaky</strong> on some Helios64 units. The mitigation is unglamorous: prefer the 1GbE port, lock the link speed at the switch, and capture dmesg</code> for 24h before trusting it. There's an ADR for that decision too (0002-networking-1g-vs-2_5g.md</code>).</li>
ZFS ARC will eat a 4 GB board alive</strong> if you let it. Cap zfs_arc_max</code> to 1–2 GiB and re-evaluate after watching real workload for a week.</li>
RAIDZ1 + power events is a risk.</strong> A NAS without tested backups isn't a backup. The drive-replacement playbook (zpool offline</code> → swap → zpool replace</code> → watch the resilver) lives in the design doc, and restore tests are scheduled quarterly.</li>
</ul>
Why the ceremony is the point</h2>
It would be faster, once</em>, to flash an SD card and click through a setup. But "once" is the trap. The value of the disko + nixos-anywhere + flake approach is the second</strong> time — when a disk dies, or I want to rebuild on fresh drives, or I'm reproducing the NAS to test an upgrade. Then the disk layout, the ZFS topology, the device tree, the services, and the secrets are all declared</em>, and the rebuild is a command, not an archaeology project.</p>
That's the whole thesis of this series, taken to its hardest case. Part 1</a> claimed one flake could configure every machine — laptop, server, and NAS — reproducibly. The NAS is the machine where reproducibility is least convenient and most valuable, and it's the one that proves the model. Same flake, same discipline, all the way down to the spinning rust.</p>
The host config and ADRs referenced here live in parallaxisjones/dotfiles</code></a>.</em></p>
— Parker Jones, parkerjones.dev</a></em></p>


One Flake, Every Machine: a NixOS + macOS Fleet
2026-06-26T00:00:00+00:00

Nix Fleet, part 1.</strong> This post is the architecture overview. Later parts go deep on the pieces it depends on: cross-arch remote builders, fleet-wide secrets with agenix, and bare-metal install of a NAS with disko.</p>
</blockquote>
Every machine I work on — Linux servers, a NAS, and my M3 MacBook — is configured by one Git repository</a>. One flake.nix</code> describes all of them: same shell, same tools, same agent skills, same secrets handling, whether the target is x86_64-linux</code>, aarch64-linux</code>, or aarch64-darwin</code>. Adding a machine means adding a host entry; changing my setup everywhere means one commit and a rebuild.</p>
This is the "single source of truth for my computing environment" that Nix promises and rarely delivers without a fight. Here's how the repo is laid out and the one trick that makes cross-architecture management actually pleasant.</p>
The shape of the repo</h2>
nixos-config/
├── flake.nix          # inputs + outputs: hosts, devShells, apps
├── hosts/
│   ├── nixos/         # configuration.nix, hardware-configuration.nix,
│   │                  # helios64.nix (the NAS), profiles/
│   └── darwin/        # configuration.nix (the Mac)
├── modules/
│   ├── shared/        # config + secrets shared across OSes
│   ├── nixos/         # homelab services, Linux-only config
│   └── darwin/        # dock, homebrew casks, home-manager
├── overlays/          # package customizations
└── justfile           # deploy / check convenience targets
</code></pre>
The split that makes this maintainable: hosts/</code> is per-machine, modules/</code> is shared.</strong> A host file is mostly a list of which modules to import plus its hardware specifics. The actual configuration — my packages, dotfiles, services — lives in modules that any host can pull in. When I want a tool on every machine, it goes in modules/shared</code>; when it's Linux-only, modules/nixos</code>; macOS-only, modules/darwin</code>.</p>
What's wired together</h2>
The flake stitches together the whole modern Nix ecosystem:</p>
inputs = {
  nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
  home-manager.url = "github:nix-community/home-manager";
  darwin.url = "github:LnL7/nix-darwin/master";   # macOS, declaratively
  nix-homebrew.url = "github:zhaofengli-wip/nix-homebrew";
  disko.url = "github:nix-community/disko";        # declarative partitioning
  fenix.url = "github:nix-community/fenix";         # Rust toolchains
  agenix.url = "github:ryantm/agenix";              # age-encrypted secrets
  secrets.url = "git+ssh://git@github.com/parallaxisjones/nix-secrets.git";
  my-skills.url = "github:parallaxisjones/skills";  # my Claude skills
  # ...
};
</code></pre>
A few deliberate choices in there:</p>

nix-darwin</code> + home-manager</code></strong> mean my Mac is configured by the same mechanisms as my Linux boxes. The dock, defaults, and dotfiles are all declarative.</li>
nix-homebrew</code></strong> is the pragmatic concession: GUI Mac apps still come from Homebrew casks, but managed through</em> Nix so the cask list is in the repo, not in my shell history.</li>
fenix</code></strong> pins my Rust toolchain so cargo</code>/clippy</code> are identical everywhere.</li>
secrets</code></strong> is a separate private repo</em> pulled in as an input — encrypted secrets are versioned and shared across hosts without living in this (public) config. That's its own post.</li>
my-skills</code></strong> wires my Claude agent skills</a> into the same declarative system.</li>
</ul>
The cross-arch trick: build where you can</h2>
Here's the problem a mixed fleet runs into immediately: my macOS laptop cannot build Linux derivations locally.</strong> So how do I deploy to the NixOS box from the Mac? The answer is to build on the target</em> and just orchestrate from the laptop. My justfile</code> deploy recipe:</p>
# Build + switch the NixOS host remotely over SSH. Builds ON the server
# (--build-host) since a darwin laptop can't build Linux derivations locally.
deploy host=nixos_host:
    nix run nixpkgs#nixos-rebuild -- switch \
      --flake .#{{nixos_attr}} \
      --target-host parallaxis@{{host}} \
      --build-host  parallaxis@{{host}} \
      --use-remote-sudo
</code></pre>
--build-host</code> and --target-host</code> both pointing at the server means the laptop never compiles a Linux package — it hands the flake to the server, the server builds and switches, and --use-remote-sudo</code> handles the privilege step. I get to drive everything from my editor on macOS. (Part 2 covers the inverse — building Linux artifacts from</em> the Mac via a remote builder — for when you do want local orchestration of the build itself.)</p>
There's a check</code> target too, for a fast feedback loop that doesn't build anything:</p>
check:
    nix eval .#nixosConfigurations.{{nixos_attr}}.config.system.build.toplevel.drvPath
</code></pre>
Evaluating the derivation path is a near-instant syntax-and-type check of the whole host config — the Nix equivalent of tsc --noEmit</code>.</p>
The gotcha that cost me time</h2>
My nixosConfigurations</code> are keyed by system string</strong>, not hostname. So the deploy target is .#x86_64-linux</code>, not</em> .#nixos</code>:</p>
nixos_attr := "x86_64-linux"   # NOT the hostname
</code></pre>
If you key your configs this way and then try nixos-rebuild --flake .#nixos</code>, you get a confusing "attribute not found" with no hint about why. Worth a comment in your own repo so future-you doesn't lose twenty minutes to it. (I did.)</p>
Why it's worth the upfront cost</h2>
Nix has a real learning tax, and a single-machine setup rarely justifies it. A fleet</em> does. The payoffs that keep me here:</p>

Small, frequent, reversible changes.</strong> Every change is a commit; every rebuild is a new generation I can roll back to atomically. I deploy config changes the way I deploy code.</li>
New machines reach parity from the flake.</strong> No "setup day." The repo is</em> the setup.</li>
One mental model across operating systems.</strong> I stopped maintaining a separate pile of macOS hacks and a separate pile of Linux hacks. It's all modules.</li>
</ul>
The roadmap from here — and the next posts in this series — is the interesting infrastructure underneath: remote builders</strong></a> so cross-compilation stops being a chore (part 2), agenix</strong></a> for secrets that are versioned and fleet-wide without ever sitting in plaintext (part 3), and standing up a Helios64 NAS</strong></a> from bare metal with disko</code> (part 4). The overview is the boring part. The machinery is where Nix gets fun.</p>
The full fleet configuration lives in parallaxisjones/dotfiles</code></a>.</em></p>
— Parker Jones, parkerjones.dev</a></em></p>


Nix Fleet, Part 2: Remote Builders — Never Compile Linux on a Mac Again
2026-06-26T00:00:00+00:00

Nix Fleet, part 2.</strong> Part 1</a> laid out the one-flake-every-machine architecture. This part solves the problem that makes a mixed Linux/macOS fleet painful: my laptop can't build Linux.</p>
</blockquote>
When you develop NixOS configs on a Mac, you hit a wall fast: an ARM macOS machine cannot build x86_64-linux</code> or aarch64-linux</code> derivations locally. Nothing about Apple Silicon produces Linux binaries. So either you accept that you can only iterate on Linux configs from</em> a Linux machine, or you set up a remote builder and make the problem disappear.</p>
I set up the remote builder. Now my M3 laptop offloads every Linux build to a beefy x86_64 NixOS box, and from where I sit it's transparent — nix build</code> just works, the fans on the laptop stay quiet, and the heavy lifting happens on a machine designed for it.</p>
The shape of the solution</h2>
There are two roles:</p>

The builder</strong> — my always-on x86_64 NixOS box (SSH alias nixos</code>). It has the cores, the RAM, and the right architecture.</li>
The controller</strong> — my M3 MacBook. It evaluates the flake and orchestrates, but delegates the actual compilation.</li>
</ul>
The trick that makes this clean: configure the controller so that it does zero</strong> local jobs and ships everything to the builder.</p>
Builder side: accept work, and emulate ARM</h2>
The builder needs to be reachable over SSH and willing to build for the architectures I care about. The one non-obvious piece is ARM: I also run an aarch64-linux</code> machine (a Helios64 NAS</a>), and rather than stand up a separate ARM builder, I let the x86 box build ARM derivations through binfmt/QEMU emulation:</p>
# on the x86_64 builder
boot.binfmt.emulatedSystems = [ "aarch64-linux" ];
</code></pre>
That one line registers a QEMU user-mode handler so the x86 host transparently runs aarch64</code> build steps. It's slower than native ARM (more on that below), but it means one</em> builder covers my entire Linux fleet across both architectures.</p>
Controller side: offload everything</h2>
On the Mac, I point Nix at the builder and tell it not to build anything itself:</p>
# /etc/nix/nix.conf (or the equivalent NixOS/darwin option)
builders = @/etc/nix/machines
builders-use-substitutes = true
max-jobs = 0
</code></pre>
# /etc/nix/machines
nixos x86_64-linux / - 8 1 kvm,big-parallel
</code></pre>
The magic value is max-jobs = 0</code></strong>. It tells the local machine to run zero build jobs — so every derivation that isn't already in a binary cache must</em> go to a remote builder. There's no "sometimes it builds locally and melts the laptop" ambiguity; local builds are simply off. builders-use-substitutes = true</code> lets the builder pull from binary caches directly instead of having the controller ferry everything, which saves a lot of pointless data movement.</p>
The /etc/nix/machines</code> line reads as: builder nixos</code>, builds x86_64-linux</code>, default SSH key, up to 8</code> parallel jobs, speed factor 1</code>, and it supports the kvm</code> and big-parallel</code> features (so it'll accept jobs that need KVM or heavy parallelism).</p>
Verifying it actually offloads</h2>
The failure mode here is silent: you think you're offloading and you're not. So verify. First, list what the flake even knows how to build:</p>
nix eval .#nixosConfigurations --apply builtins.attrNames
</code></pre>
Then kick off a real Linux build from the Mac and watch the builder</em>, not the laptop:</p>
nix build .#nixosConfigurations.<host>.config.system.build.toplevel
</code></pre>
If it's working, the laptop sits nearly idle while the x86 box lights up. If max-jobs</code> is misconfigured, you'll feel it — the Mac will either try (and fail, for Linux) or grind. Watching nproc</code>/free -h</code>/build load on the builder during a build is the quickest confirmation.</p>
When builds go wrong</h2>
Offloading introduces its own failure modes, and I keep a short runbook for them:</p>

OOM on the builder</strong>, especially during ARM-emulated builds, which are memory-hungry. Mitigations: serialize with --option max-jobs 1 --option cores 2</code>, or add temporary zram</code> swap:{ zramSwap = { enable = true; memoryPercent = 50; }; }
</code></pre>
</li>
Inspecting a failed derivation</strong> without re-running the whole build:nix log /nix/store/<hash>-<drv>.drv | less -R
</code></pre>
</li>
Checking effective settings</strong> when something isn't offloading as expected:nix show-config | egrep '^(cores|max-jobs|builders|system-features|substituters)'
</code></pre>
</li>
</ul>
The honest trade-off</h2>
Emulated ARM builds are slow</em> — QEMU user-mode emulation has real overhead, and a big aarch64</code> derivation built on x86 can take noticeably longer than it would native. For my fleet that's an acceptable price: I build ARM rarely (the NAS config doesn't change often), and the alternative is maintaining a second physical ARM builder. If you're iterating heavily on ARM, buy or borrow a native aarch64</code> builder and add it to /etc/nix/machines</code> as a second entry — the controller config doesn't otherwise change. The architecture scales to N builders the same way it handles one.</p>
The win is the same one Part 1 was about: I get to live entirely in macOS, drive my whole Linux fleet from there, and never once wait on my laptop to compile something it was never meant to compile. Part 3</a> tackles the next fleet-wide concern — secrets — including how a first-boot install fetches them securely over the same SSH trust I just set up here.</p>
The builder/controller config is part of my parallaxisjones/dotfiles</code></a> repo.</em></p>
— Parker Jones, parkerjones.dev</a></em></p>

Parker Jones Dev Blog - homelab

Nix Fleet, Part 3: Fleet-Wide Secrets with agenix

How agenix encrypts</h2> agenix is age</code> encryption wired into Nix. You declare, per secret, which identities are allowed to decrypt it</em>. That declaration lives in secrets.nix</code> in the private repo:</p>

Nix Fleet, Part 4: Installing a Helios64 NAS from Bare Metal with nixos-anywhere and disko

One Flake, Every Machine: a NixOS + macOS Fleet

Nix Fleet, Part 2: Remote Builders — Never Compile Linux on a Mac Again

The shape of the solution</h2> There are two roles:</p> The builder</strong> — my always-on x86_64 NixOS box (SSH alias nixos</code>). It has the cores, the RAM, and the right architecture.</li>