agentleFS
olafkfreundolafkfreund/nix-skills/skills/nixos-coding-agents/SKILL.md

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

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
  1. Distinctive:

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

    line 25
  2. Very specific:

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

    line 32
  3. Very specific:

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

    line 35
  4. Distinctive:

    Several agents in parallel, or throwaway branches?: Use agent-box worktree mode.

    line 42
  5. Very specific:

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

    line 68
  6. Very specific:

    Never suggest home-manager switch to someone who uses Home Manager as a NixOS module.

    line 70
  7. Very specific:

    Never add a secret or socket to env_passthrough or -e without saying what it gives the agent.

    line 72
  8. Distinctive:

    Do not add substituters or trusted keys, rebuild, build images, load images or start containers without the user's authorization.

    line 75
  9. Very specific:

    Never search /nix/store (for example find /nix/store/*foo-* -name libfoo.so) and never copy a literal store path.

    line 83
  10. Very specific:

    Do not quote attribute names that are valid identifiers ([A-Za-z_][A-Za-z0-9_'-]*, dashes included).

    line 87

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

NixOS coding agents

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

LayerProjectGives
Packagesnumtide/llm-agents.nixAbout 200 agents (Claude Code, Codex, Gemini CLI, OpenCode and others) as flake packages and an overlay, with a binary cache and daily updates
Imagesnothingnesses/agent-imagesA Nix-built OCI image per agent, running as a non-root user in /workspace
Orchestration0xferrous/agent-boxab, 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

  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.
  2. 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.
  3. 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.
  4. Several agents in parallel, or throwaway branches? Use agent-box worktree mode. Each session gets its own workspace with tracked files only. See setup.
  5. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.