nixos-coding-agents
Skill9 starsChanged 55 days agoMITView on GitHub
Choose, install and sandbox AI coding agents on NixOS with llm-agents.nix packages, agent-images containers and agent-box disposable workspaces.
- Reads credentials
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- devenv-projectSkill
- home-managerSkill
- microvm-nixSkill
- nix-darwinSkill
- nix-languageSkill
- nixos-operationsSkill
- nixos-wikiSkill
- nixpkgs-developmentSkill
- nix-workflowSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 3 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 25
Check whether the system's nixpkgs follows nixpkgs-unstable or a stable release.
- Very specific: line 32
Trying an agent once?: Run nix run github:numtide/llm-agents.nix#<agent>, or nix run github:numtide/llm-agents.nix for an interactive …
- Very specific: line 35
Keeping it?: Add llm-agents.nix as a flake input and install the chosen agents declaratively.
- Distinctive: line 42
Several agents in parallel, or throwaway branches?: Use agent-box worktree mode.
- Very specific: line 68
Do not suggest inputs.nixpkgs.follows for llm-agents.nix on a stable release.
- Very specific: line 70
Never suggest home-manager switch to someone who uses Home Manager as a NixOS module.
- Very specific: line 72
Never add a secret or socket to env_passthrough or -e without saying what it gives the agent.
- Distinctive: line 75
Do not add substituters or trusted keys, rebuild, build images, load images or start containers without the user's authorization.
- Very specific: line 83
Never search /nix/store (for example find /nix/store/*foo-* -name libfoo.so) and never copy a literal store path.
- Very specific: line 87
Do not quote attribute names that are valid identifiers ([A-Za-z_][A-Za-z0-9_'-]*, dashes included).
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
NixOS coding agents
Three upstream projects form one pipeline. Use as many layers as the user needs:
| Layer | Project | Gives |
| Packages | numtide/llm-agents.nix | About 200 agents (Claude Code, Codex, Gemini CLI, OpenCode and others) as flake packages and an overlay, with a binary cache and daily updates |
| Images | nothingnesses/agent-images | A Nix-built OCI image per agent, running as a non-root user in /workspace |
| Orchestration | 0xferrous/agent-box | ab, which creates a disposable Git worktree or Jujutsu workspace and runs the agent in a container |
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
- Trying an agent once? Run
nix run github:numtide/llm-agents.nix#<agent>, ornix run github:numtide/llm-agents.nixfor an interactive picker. Nothing is installed. - Keeping it? Add llm-agents.nix as a flake input and install the chosen
agents declaratively. They are then pinned in
flake.lockand rolled back with the generation. See setup. - Keeping it away from secrets? An agent on the host can read everything
the user can, including
~/.ssh, cloud credentials and.envfiles. Run it from an agent-images container that mounts only the project. See setup. - Several agents in parallel, or throwaway branches? Use agent-box worktree mode. Each session gets its own workspace with tracked files only. See setup.
- Team standard? Build one image with
mkAgentImageand 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 = truefor evaluation, soallowUnfreeneither gates nor is needed for them. Readmeta.license.shortNameinstead. - 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.followsfor llm-agents.nix on a stable release. It breaks eventually and loses cache hits. - Never suggest
home-manager switchto someone who uses Home Manager as a NixOS module; they rebuild throughnixos-rebuild. - Never add a secret or socket to
env_passthroughor-ewithout saying what it gives the agent. Never forwardSSH_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 examplefind /nix/store/*foo-* -name libfoo.so) and never copy a literal store path. Find the providing package withnix-locate, and refer to it through Nix:${pkgs.foo}/liborlib.makeLibraryPath [ pkgs.foo ]. - Do not quote attribute names that are valid identifiers
(
[A-Za-z_][A-Za-z0-9_'-]*, dashes included). Writepkgs.foo-barandpackages.x86_64-linux, notpkgs."foo-bar". Quote only other names (".config/foo","2.0"), the keywordsassert 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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

