Como usar
- Copie o comando e verifique o pacote antes de instalar no seu ambiente de agente.
- Consulte no original as ferramentas, credenciais e ambientes necessários.
- Descreva os dados de entrada e a entrega esperada; confira a saída com as fontes.
npx skills add https://github.com/olafkfreund/nix-skills --skill nixos-coding-agentsAntes de começar
- A instalação não inclui assinatura de modelo, franquia API ou acesso aos seus arquivos.
- Estrelas e instalações indicam atividade, não um teste independente de qualidade ou segurança.
Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.
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.