Parker Jones Dev Blog - home-manager

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>



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>


Shipping Claude Skills with Nix: a Reproducible Agent Toolkit Across My Fleet
2026-06-26T00:00:00+00:00
A coding agent is only as good as the procedures you hand it. Out of the box, a model improvises every task from scratch; give it a skill</em> — a written procedure for "do TDD," "diagnose a hard bug," "turn this into issues" — and it stops guessing and starts following a method you trust. I've built up a collection of these, and once you have more than a handful the real problem isn't writing them, it's distribution</strong>: getting the same skills onto every machine I work from, version-pinned, without copy-pasting Markdown around.</p>
I solved that with Nix. Here's the setup.</p>
What a skill is</h2>
My skills live in a repo (a fork of Matt Pocock's skills</code></a>, credit where it's due), organized into buckets — engineering</code>, qa</code>, productivity</code>, personal</code>, misc</code>. Each skill is a directory with a SKILL.md</code>: YAML frontmatter naming it and describing when</em> to use it, then the procedure itself.</p>
---
name: diagnose
description: Disciplined diagnosis loop for hard bugs and performance
  regressions. Reproduce → minimise → hypothesise → instrument → fix →
  regression-test. Use when user says "diagnose this" / "debug this"...
---

# Diagnose
...
</code></pre>
The description</code> is load-bearing — it's what the agent matches against to decide whether the skill is relevant. A few I reach for constantly: tdd</code> (red-green-refactor), diagnose</code> (the loop above), to-prd</code> / to-issues</code> / triage</code> (turning a vague ask into tracked work), and write-a-skill</code> (the skill that writes more skills). Small, composable, model-agnostic. No framework owning my process — just procedures I can read, edit, and trust.</p>
Three ways to install them</h2>
The repo supports three distribution paths, in increasing order of how much I actually rely on them.</p>
1. npx</code>, for anyone.</strong> The zero-commitment path:</p>
npx skills@latest add parallaxisjones/skills
</code></pre>
Pick the skills and agents you want, and you're set. Great for trying them on a machine that isn't mine.</p>
2. A symlink script, for a local clone.</strong> If I've cloned the repo, link-skills.sh</code> symlinks every SKILL.md</code> into ~/.claude/skills/</code> so the CLI picks them up directly. It's idempotent — re-run after pulling — and it specifically guards against the footgun where ~/.claude/skills</code> is itself</em> a symlink back into the repo, which would write per-skill symlinks into my own working copy:</p>
if [ -L "$DEST" ]; then
  resolved="$(readlink -f "$DEST")"
  case "$resolved" in
    "$REPO"/*) echo "refusing to pollute the repo"; exit 1 ;;
  esac
fi
</code></pre>
That defensive check is the kind of thing you write after</em> the first time a script eats its own tail.</p>
3. Nix, for my actual fleet.</strong> This is the one that matters. My skills repo is a flake input in my system config</a>, and a home-manager module materializes them declaratively on every machine.</p>
The Nix wiring</h2>
Two inputs do the work — my skills repo, and agent-skills-nix</code></a>, a home-manager module that knows how to turn a skills repo into materialized files:</p>
# flake.nix
inputs = {
  agent-skills-nix = {
    url = "github:Kyure-A/agent-skills-nix";
    inputs.nixpkgs.follows = "nixpkgs";
    inputs.home-manager.follows = "home-manager";
  };
  my-skills.url = "github:parallaxisjones/skills";
};
</code></pre>
Then in home-manager I point the module at my repo, filter to the buckets I want live, and enable everything:</p>
agent-skills = {
  enable = true;
  sources.mine = {
    input  = "my-skills";
    subdir = "skills";
    filter.nameRegex = "^(engineering|misc|personal|productivity)/.*";
  };
  skills.enableAll = true;
  targets.claude.enable = true;
};
</code></pre>
That's the whole thing. On nixos-rebuild switch</code> (or darwin-rebuild</code> on the Mac), every SKILL.md</code> matching the regex gets written into Claude's skills directory. The deprecated/</code> bucket is excluded by the filter, so retiring a skill is a one-line regex change, not a manual delete on five machines.</p>
Why bother — what Nix actually buys here</h2>
You could argue the symlink script is simpler, and for one machine it is. The fleet is where Nix earns it:</p>

Pinning.</strong> flake.lock</code> records the exact skills commit each machine is on. "Which version of my triage</code> skill is the laptop running?" has an answer, not a shrug.</li>
Parity from scratch.</strong> A fresh machine reaches full skill parity as a side effect of building its system config. There's no separate "and don't forget to install your skills" step — it's the same switch</code> that installs my shell and my packages.</li>
Atomic rollback.</strong> If a skill edit makes the agent behave worse, rolling back the generation rolls back the skills with it.</li>
</ul>
There's a framing I lean on for deciding what to manage this way — think of three zones. Zone 1</em> is stable, declarative config (the home-manager module enabling skills). Zone 3</em> is runtime state that should never touch Nix (per-conversation agent memory). Skills sit in Zone 2</strong>: authored content, edited as plain files in their repo, but materialized</em> onto each machine by Nix. Nix owns where they land and which version; I own what they say.</p>
The honest caveat</h2>
Nix doesn't validate skill content</em> — a SKILL.md</code> with a bad description</code> will deploy just as reliably as a good one. This pipeline guarantees distribution and pinning, not quality. The quality comes from treating skills like code: review them, iterate on the descriptions when the agent picks the wrong one, and delete the ones that stop earning their place (that's what deprecated/</code> is for).</p>
But that's the right division of labor. Writing a good procedure is human work. Making sure that procedure is identically present on every machine I touch</em> is exactly the kind of toil Nix exists to kill. Treat your agent's skills as part of your declarative system, not as dotfiles you sync by hand.</p>
— Parker Jones, parkerjones.dev</a></em></p>

Parker Jones Dev Blog - home-manager

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>

One Flake, Every Machine: a NixOS + macOS Fleet

Shipping Claude Skills with Nix: a Reproducible Agent Toolkit Across My Fleet