Mode d’emploi
- Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
- Consultez le document original pour les outils, identifiants et environnements requis.
- Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/olafkfreund/nix-skills --skill nixos-coding-agentsAvant de commencer
- L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
- Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.
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>,
or nix run github:numtide/llm-agents.nix for 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.lock and 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 .env files. 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, 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.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 through nixos-rebuild.
- Never add a secret or socket to
env_passthroughor-ewithout 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 examplefind /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.