olafkfreund/nix-skills/nixos-coding-agents

NixOS coding agents

Three upstream projects form one pipeline. Use as many layers as the user needs:

This skill links to upstream rather than copying it; the examples were checked against upstream on 2026-09-23. Upstream changes daily, so confirm flags and parameters there before relying on them.

Establish the setup first

• Find out how the system is built: a flake with nixosConfigurations, or

channels. Check whether Home Manager is standalone or a NixOS module.

• Check whether the system's nixpkgs follows nixpkgs-unstable or a stable

release. llm-agents.nix is tested only against unstable.

• The images and agent-box are Linux only. On nix-darwin and standalone Home

Manager, offer only the packages layer.

Decision tree

1. Trying an agent once? Run nix run github:numtide/llm-agents.nix#<agent>,

or nix run github:numtide/llm-agents.nix for an interactive picker. Nothing is installed.

1. Keeping it? Add llm-agents.nix as a flake input and install the chosen

agents declaratively. They are then pinned in flake.lock and rolled back with the generation. See setup.

1. Keeping it away from secrets? An agent on the host can read everything

the user can, including ~/.ssh, cloud credentials and .env files. Run it from an agent-images container that mounts only the project. See setup.

1. Several agents in parallel, or throwaway branches? Use agent-box

worktree mode. Each session gets its own workspace with tracked files only. See setup.

1. Team standard? Build one image with mkAgentImage and commit an example

.agent-box.toml. See story 5.

Choosing an agent

The generated package list in the llm-agents.nix README shows each agent's licence and whether it is built from source or shipped as a binary. Compare:

• Licence. llm-agents.nix marks unfree agents free = true for

evaluation, so allowUnfree neither gates nor is needed for them. Read meta.license.shortName instead.

• Source. A source build can be audited; a binary cannot.
• Provider. Which model provider it talks to, which key it needs, and what

that costs. Some agents support several providers or local models.

• Cache. Using the flake's own packages hits the Numtide cache. The overlay

builds against the user's nixpkgs and may compile locally.

Recommend a short list with the trade-offs, not a single winner.

Rules

• Do not suggest inputs.nixpkgs.follows for llm-agents.nix on a stable

release. It breaks eventually and loses cache hits.

• Never suggest home-manager switch to someone who uses Home Manager as a

NixOS module; they rebuild through nixos-rebuild.

• Never add a secret or socket to env_passthrough or -e without saying

what it gives the agent. Never forward SSH_AUTH_SOCK, cloud credentials or the Nix daemon socket by default.

• Do not add substituters or trusted keys, rebuild, build images, load images

or start containers without the user's authorization. Propose the exact change or command instead.

• Say what the sandbox does not protect. Read security

before advising on isolation.

Nix style

• Never search /nix/store (for example find /nix/store/*foo-* -name libfoo.so)

and never copy a literal store path. Find the providing package with nix-locate, and refer to it through Nix: ${pkgs.foo}/lib or lib.makeLibraryPath [ pkgs.foo ].

• Do not quote attribute names that are valid identifiers

([A-Za-z_][A-Za-z0-9_'-]*, dashes included). Write pkgs.foo-bar and packages.x86_64-linux, not pkgs."foo-bar". Quote only other names (".config/foo", "2.0"), the keywords assert else if in inherit let or rec then with, and interpolations ("${name}"). Upstream examples in references sometimes quote needlessly; do not copy that style.

References

• User stories: a guide of six stories, each

with a configuration, a check and how to undo it.

• Setup: llm-agents.nix, rootless Podman on NixOS,

agent-images, agent-box, Portal, and nix-darwin or standalone Home Manager.

• Security: what each layer protects and what it

does not.

Report what you actually ran, and which advice you could not verify on the user's release.