Nix Agent

Nix Agent

Overview

nix-agent MCP tools do NOT read or write files. They build, diff, switch, and manage generations (the operational core), and evaluate, locate, and check the live config (introspection), handing every result back as a compact JSON envelope. Read the envelope: it already holds what you would otherwise re-fetch by hand.

Division of labor:

• Your native tools (Read/Edit/Write) edit .nix files.
• mcp-nixos discovers packages and options (what exists, what it means).
• nix-agent operates on the user's actual configuration (what their machine resolves, whether it builds, what a switch would change).

Default is apply: after a config change, diff() then switch() without waiting. Wait only when the user asked to preview or check, not activate.

Tool Surface

Seven tools in two tiers. All auto-resolve the target when flake_uri is omitted and echo back what they resolved and ran (resolved_target and command, or commands for check("lint")).

Operational core:

• build(flake_uri?, mode?): build the closure, no activation. A failed build carries failed_derivation.
• diff(flake_uri?, mode?): what a switch would change (adds/removes/ version bumps), plus a structured packages object when it parses. Include this in the reply and switch unless the user asked only to preview or check.
• switch(flake_uri?, mode?, validate?, full_log?): activate. Records rollback_generation, returns a summary (units changed, derivations built, packages vs the rollback generation, health), and trims the log to a tail on success. validate=True gates on check("dry-build"). Remote refs and pin mismatches exit as remote_ref_rejected / target_locked before sudo or dry-build. . / ./ resolve to the pin when $NIX_AGENT_FLAKE is set. Newly failed units after activation are status: "degraded"; report summary.health and roll back unless the user asked to leave those units failed. Privileged argv uses sudo -n.
• generations(action="list"|"rollback", mode?, generation?): list or roll back. NixOS list entries include path when the profile link exists. After switch, call generations(action="rollback", generation=<rollback_generation or id>). Bare generations(action="rollback") is previous-generation only. Unknown ids return unknown_generation and run no command.

Config introspection:

• eval_config(attr, flake_uri?, mode?): final merged value of any config attribute on THIS machine, after all modules/overlays. mcp-nixos says what an option means; this says what it is. Pass a list for attr to evaluate many in one call (per-attr results). All attrs ok or mixed → ok (failures in results); every attr failed → failed with first_error from the first failed entry that has one. Values above ~2 KB degrade to attr names / length / a head slice, marked truncated: true. A missing hostname attr falls back to a unique flake host or returns unknown_host with hosts. In NixOS mode, a missing option is retried as home-manager.users.<user>.<attr> (hm_rewritten: true).
• locate_option(attr, flake_uri?, mode?): which file sets an option, as declarations and definitions ({file, value} per file). Earns its slot as that which-file answer, not as a cap (measured environment.systemPackages is 24 KB → 20 KB). Use this instead of grepping the tree. status is not_an_option for plain config values (use eval_config there). For integrated HM, spell the attr home-manager.users.<user>.<attr> with mode="nixos"; if you pass the unprefixed attr, the tool retries that spelling (hm_rewritten). Missing hostname → unknown_host with hosts.
• check(level, flake_uri?, mode?): validation ladder, fast to slow: "lint" (statix + deadnix, structured findings), "dry-build", "dry-activate" (NixOS only). Dry-activate uses the same remote/pin classifier as switch and attaches privilege on sudo auth failure.

Formatting is not a tool: format edited files with the flake's own formatter (nix fmt, or nixfmt on the files) via your Bash tool. Repo onboarding is the nix-agent inspect-flake CLI subcommand, not a tool; the nix-agent-init skill drives it.

Picking mode (read before any HM change)

mode defaults to "nixos". Do NOT reflexively switch to "home-manager" just because the task touches Home Manager options. That is the most common way to operate on the wrong config.

• Integrated HM (wired in as a NixOS module via home-manager.nixosModules.home-manager + home-manager.users.*): no separate home-manager switch. HM is built and activated as part of the system closure, so use mode="nixos" (the default) and switch the whole system. The common laptop/desktop layout.
• Standalone HM (its own flake exposing homeConfigurations.*, applied with home-manager switch): use mode="home-manager".

If both a NixOS flake and a standalone ~/.config/home-manager flake exist on the machine, the standalone one is often vestigial. Confirm which is actually active (eval_config against each, or check what the running generation was built from) before mutating. When in doubt, mode="nixos" is the safer guess.

For nonstandard or multi-flake layouts, do not rely on auto-resolution: set NIX_AGENT_FLAKE once (or NIX_AGENT_HM_FLAKE for standalone HM, which falls back to NIX_AGENT_FLAKE), or pass an explicit flake_uri like /home/you/nixos#host. Either pins the target exactly.

Wrong-host symptom: unknown_host lists hosts from the flake. A failed envelope whose first_error names a missing nixosConfigurations."<hostname>" means auto-resolution could not recover; pass an explicit flake_uri (.../repo#realhost) or $NIX_AGENT_FLAKE, not by retrying the same hostname.

Workflow

1. Discovery (if needed): query mcp-nixos for packages/options; eval_config for what the machine currently resolves; locate_option for which file to open.
2. Edit .nix files with your native file tools.
3. Format with the flake's formatter (nix fmt, or nixfmt on the edited files) via Bash, then check("lint"): fix findings worth fixing.
4. check("dry-build"): catches eval/build errors cheaply.
5. diff(): include the changeset in the reply and switch unless the user asked only to preview or check.
6. switch(): report the result and rollback_generation. Keep that value. status: "degraded" means activation succeeded but units newly failed — report summary.health and roll back unless the user asked to leave those units failed.
7. On failure at any step: read first_error, then error_detail, then failed_derivation.log_tail; fix and retry. status: "preflight_failed" means switch(validate=True) never activated — fix the nested preflight dry-build, do not retry activation. A privilege field means sudo auth failed, not a Nix error. unknown_generation, unknown_host, target_locked, and remote_ref_rejected are early exits: no command ran. On regret after a switch: generations(action="rollback", generation=<rollback_generation or id>). Bare generations(action="rollback") is previous-generation only, and is only the right default when nothing else has switched since.

Steps 3 through 5 are judgment calls, not gates. For a trivial change, going straight to switch is fine.

Token discipline: the envelope is the interface

This server pre-digests Nix's firehose. An agent that re-runs nix log or systemctl after every operation throws that away. Read the fields; do not re-fetch.

• On failure, read three fields in order and stop. first_error is the actionable line. error_detail is {message, file, line, column, trace} when Nix emitted an eval error: a direct file:line:column edit target. failed_derivation.log_tail is the failing builder's log, already fetched. Do NOT run nix log or re-run with full_log=True unless these fields are absent.
• After a switch, read summary, do not re-probe. status: "degraded" means units newly_failed; treat that as a problem, not success, and roll back with generations(action="rollback", generation=<rollback_generation>) unless the user asked to leave those units failed. summary.health reports units newly_failed/resolved/still_failed with journal tails for the first five newly failed units; summary.packages reports changes vs the rollback generation. These replace running systemctl --failed or a second diff().
• Batch attr checks. eval_config([...]) answers N questions in one call. Mixed results stay ok with failures in results; if every attr failed, top-level status is failed with first_error from the first failed entry that has one. A truncated: true value means eval a child attr for the part you need, NOT retry for full output.
• locate_option before grepping. It answers "which file sets this" in one call; a tree-wide grep does not. That is why it has a slot, not because it caps a firehose (24 KB → 20 KB on environment.systemPackages).
• Byte accounting is off the envelope. raw_bytes / returned_bytes live in the usage log (NIX_AGENT_USAGE_LOG=1, then nix-agent usage), not on the tool response. Do not look for them in MCP results.
• Escape hatches are deliberate last resorts. full_log=True and the raw output field exist for the rare case the trimmed view genuinely lacks what you need; reaching for them by default defeats the server.

Onboarding a repo

First time in an unfamiliar config? Run /nix-agent-init: it runs nix-agent inspect-flake once and generates AGENT_MAP.md, CLAUDE.md (+ an AGENTS.md symlink), and .mcp.json from the observed facts, never boilerplate.

Hard Rules

• Never write secret payloads into config files; reference secrets via sops-nix/agenix and only edit references.
• Never call switch when the user asked only to check or preview; diff is the preview. Otherwise the default is apply: switch after diff() without waiting.
• status: "degraded" means activation succeeded but units newly failed; report summary.health and roll back unless the user asked to leave those units failed.
• Host allowlists cannot see flake_uri. Privileged tools reject remote refs and honor $NIX_AGENT_FLAKE / $NIX_AGENT_HM_FLAKE as an anti-footgun (the HM lock does not fall back to the NixOS pin). Do not treat the pin as a security boundary. Sudoers must be narrowed to that directory. Default install is unprompted activation plus passwordless sudo for this flake. Do not re-ask for confirmation. Lower trust (host prompts, sudo password) only if the user asked.
• After switch, undo with generations(action="rollback", generation=<rollback_generation>). Bare rollback is previous-only.