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>

Reproducible, Secret-Safe AI Agents with Nix Flakes, agenix, and Magentic-One

2025-02-07T00:00:00+00:00

Most "I built an AI agent" posts skip the unglamorous parts: how the environment gets set up identically on another machine, where the API key actually lives, and what breaks when you try to make it reproducible. Those are the parts I find interesting, so this post is about the plumbing of Lab Agency</a> — a multi-agent app wired together with Microsoft's Magentic-One</a> — built on a Nix flake with secrets managed by agenix</a>.

The agents are the fun part. Getting them to start the same way every time, with a decrypted key and the right Python deps, is the part that actually took the work.

The flake: one entry point, several jobs</h2>
The whole project is defined by a flake.nix</code> with a few inputs and a flake-utils</code> wrapper so it builds across systems:
inputs = { nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; flake-utils.url = "github:numtide/flake-utils"; agenix.url = "github:ryantm/agenix"; }; </code></pre> From there it exposes four targets, each a different way into the same project:devShell</code> — an interactive shell for hacking on the code.</li> run-surfer</code> (default) — boots the Chainlit app.</li> inspect-embeddings</code> — pokes at the vector store.</li> index-documents</code> — loads documents into the knowledge base.</li> </ul> The point of doing it this way is that "clone and run" is true. There's no README step that says "first, set these five environment variables and install these packages." The flake target is the setup. Secrets that decrypt themselves, in the shell</h2> The piece I'm proudest of is how the OpenAI key is handled: it's never on disk in plaintext and never pasted into a shell. It lives age-encrypted at secrets/openai.txt</code>, and the flake decrypts it into the environment as the shell starts up: devShell = pkgs.mkShell { buildInputs = [ agenixCli pkgs.python3 ]; shellHook = '' echo "Decrypting OpenAI secret..." export OPENAI_API_KEY=$(agenix --decrypt secrets/openai.txt \ --identity ~/.ssh/parallaxis) if [ ! -d venv ]; then python3 -m venv venv source venv/bin/activate pip install --upgrade pip pip install -r requirements.txt else source venv/bin/activate fi ''; }; </code></pre> agenixCli</code> here is just agenix.packages.${system}.default</code> pulled from the input. Decryption keys off my SSH identity (~/.ssh/parallaxis</code>), so the encrypted secret can sit in the repo and only someone holding the right key can read it. The encrypted file is safe to commit; the key never is. The run-surfer</code> target repeats the same decrypt-and-venv dance inside a writeShellScriptBin</code> so the app launches with one command: runSurfer = pkgs.writeShellScriptBin "run-surfer" '' # ...ensure venv, then: export OPENAI_API_KEY=$(agenix --decrypt secrets/openai.txt \ --identity ~/.ssh/parallaxis) exec chainlit run clapp.py -w ''; </code></pre> An honest caveat: there's a Python venv</code> living inside a Nix flake here, which is not pure Nix and a purist would wince. I made that trade deliberately — the AI ecosystem moves fast and pinning everything through nixpkgs would mean fighting the toolchain instead of building the product. Nix gives me a reproducible shell (right Python, right agenix</code>, right secret); pip install -r requirements.txt</code> handles the fast-moving libraries. It's a pragmatic seam, not a principled one, and I'd reconsider it the moment the dependency set stabilizes. Magentic-One's CLI does get the full Nix treatment, though — it's packaged in its own autogen-flake/magentic-one-cli.nix</code> rather than left to pip. The agents: a Magentic-One team plus a RAG layer</h2> The app itself (clapp.py</code>) is a Chainlit</a> chat front-end over a Magentic-One group chat. Magentic-One ships a roster of specialist agents, and Lab Agency assembles them through AutoGen's extensions: from autogen_agentchat.teams import MagenticOneGroupChat from autogen_ext.agents.file_surfer import FileSurfer from autogen_ext.agents.web_surfer import MultimodalWebSurfer from autogen_ext.agents.magentic_one import MagenticOneCoderAgent from autogen_ext.code_executors.local import LocalCommandLineCodeExecutor </code></pre> So the team can read files (FileSurfer</code>), browse the web (MultimodalWebSurfer</code>), write code (MagenticOneCoderAgent</code>), and execute it locally (LocalCommandLineCodeExecutor</code>) — Magentic-One's orchestrator decides who does what for a given task. On top of that roster I added two custom agents to give the team a memory. A KnowledgeAgent</code> does retrieval-augmented generation against a Chroma</a> collection: async def retrieve_knowledge(self, query): query_embedding = self.embedding_function([query])[0] results = self.collection.query( query_embeddings=[query_embedding], n_results=5, ) return results['documents'][0] </code></pre> …and an EmbeddingAgent</code> writes back to it, so research the team produces during a session can be folded into the knowledge base for the next one: async def add_to_knowledge_base(self, content): embedding = self.embedding_function([content])[0] doc_id = f"doc_{self.collection.count()}" self.collection.add(documents=[content], ids=[doc_id], embeddings=[embedding]) return doc_id </code></pre> The store itself is just a local chroma_db/chroma.sqlite3</code> — no managed vector database, no extra service to stand up. That keeps the whole thing runnable on a laptop, which was the goal. Loading the knowledge base</h2> The index-documents</code> target runs a standalone script that chunks documents by token count using tiktoken</code>, embeds them through AsyncOpenAI</code>, and stores them in the agent_knowledge_base</code> Chroma collection. Chunking on tokens rather than characters matters here — it's what keeps each chunk inside the embedding model's window instead of getting silently truncated, which is the kind of bug that doesn't error, it just quietly makes your retrieval worse. What I'd carry forward</h2> Stepping back, the parts of this project I'd reuse on the next one aren't the agents — those libraries will have moved on by next quarter. It's the scaffolding: A flake target per task turns documentation into executable setup. "How do I run this?" has a literal command as the answer.</li> agenix in a shellHook</code> means a real API key is present in the environment without ever being plaintext on disk or in shell history. This is the pattern I'll copy into everything.</li> Local Chroma over SQLite is enough vector store for a single-node agent app, and skipping the managed service kept the project laptop-runnable.</li> </ul> The honest roadmap item is the same one every project like this has: containerize it and put it somewhere it can run unattended. The flake makes that a smaller leap than it would otherwise be — the build is already declarative. The code, secrets-handling, and flake are all on GitHub: parallax-labs/lab-agency</a>. — Parker Jones, parkerjones.dev</a>

Parker Jones Dev Blog - agenix

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>

Reproducible, Secret-Safe AI Agents with Nix Flakes, agenix, and Magentic-One