nix-agent
JEFF7712/nix-agent
Operações NixOS controladas por IA: eval, lint, format, build, diff, switch
Ver no GitHubServidor MCP que fornece operações compostas para gerenciar sistemas NixOS via agentes de IA. Expõe ferramentas para avaliar, validar, formatar, construir, comparar e ativar configurações Nix de forma segura e estruturada.
Instalação
npx convez-ai JEFF7712/nix-agent1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Gerenciar configurações NixOS programaticamente via agentes Claude
- Validar e formatar arquivos de configuração Nix antes de ativar
- Explorar e comparar mudanças de geração de sistema sem risco
Veredito

Ferramenta especializada para usuários NixOS que querem automação inteligente de gerenciamento de sistema. Ainda experimental, mas com suporte a Home Manager e integração fluida com o MCP, exigindo conhecimento técnico sólido de Nix e NixOS para máxima utilidade.
README
A tradução para o português deste README ainda está na fila.
nix-agent
nix-agent is a local MCP server that gives AI agents composable NixOS
operations: eval, lint, format, build, diff, switch, generations.
It works alongside mcp-nixos:
nix-agenthandles operations on your actual configuration — evaluating, linting, formatting, building, diffing, switchingmcp-nixoshandles package and option discovery
NOTE: This is experimental and a work in progress. Feedback and contributions are very welcome.
What you get
- a runnable stdio MCP server
- a Nix flake package and app (wrapper bundles statix/deadnix/nixfmt/nvd)
- a NixOS module at
nixosModules.default - a companion agent skill in
skills/nix-agent/ - example MCP host configs in
examples/
One-shot agent install
Paste this to a coding agent (Claude Code, opencode, etc.) and it will do the install for you:
Read https://raw.githubusercontent.com/JEFF7712/nix-agent/main/docs/agent-install.md and follow every step to install nix-agent on this NixOS system, install the companion skill, and register nix-agent in my MCP settings for this machine.
Fast install
Add this flake input and module to your NixOS config:
{
inputs.nix-agent.url = "github:JEFF7712/nix-agent";
outputs = { nixpkgs, nix-agent, ... }: {
nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
nix-agent.nixosModules.default
({ ... }: {
programs.nix-agent.enable = true;
})
];
};
};
}
Then rebuild:
sudo nixos-rebuild switch --flake .#my-host
That installs the nix-agent binary.
MCP host config
Point your MCP host at:
{
"mcpServers": {
"nix-agent": {
"command": "nix-agent",
"args": []
}
}
}
See examples/claude-code-mcp.json and examples/opencode-mcp.json.
Companion skill
Install or copy skills/nix-agent/ into your agent's skill directory.
Quick install:
./install-skill.sh opencode
The MCP exposes the tools. The skill teaches the correct workflow.
Tool surface
All tools auto-resolve the target when flake_uri is omitted. Resolution
order: $NIX_AGENT_FLAKE (or $NIX_AGENT_HM_FLAKE for HM), then the first
existing flake.nix among /etc/nixos, ~/nixos, ~/.config/nixos,
~/nix-config, ~/nixos-config for NixOS (~/.config/home-manager,
~/.config/nixpkgs for Home Manager). The hostname / user@host attribute is
picked automatically. Every result echoes back resolved_target and the exact
command run. Exception: calling format with explicit paths returns
per-file results instead. Pass mode="home-manager" for HM configs.
| Tool | What it does |
|---|---|
eval_config(attr, flake_uri?, mode?) | Final merged value of any config attribute on this machine (after all modules/overlays). mcp-nixos tells you what an option means; this tells you what it resolves to. |
check(level, flake_uri?, mode?) | Validation ladder, fast to slow: "lint" (statix + deadnix, structured findings list), "flake", "dry-build", "dry-activate" (NixOS only). |
format(paths?, flake_uri?, mode?) | nix fmt / nixfmt. With explicit paths, returns per-file results. |
build(flake_uri?, mode?) | Build the closure, no activation. |
diff(flake_uri?, mode?) | What a switch would change (package adds/removes/version bumps). Show this to the user before switching. |
switch(flake_uri?, mode?, validate?, full_log?) | Activate. Records rollback_generation. Returns a structured summary (units changed, derivations built) and trims the log to a tail on success (full_log=True for all of it). validate=True gates on check("dry-build") first; a sudo auth failure returns a privilege diagnosis. |
generations(action="list"|"rollback", mode?) | List or roll back generations. |
Basic workflow
- Discovery: query
mcp-nixosfor packages/options; useeval_configto see what the user's machine currently resolves. - Edit
.nixfiles with the agent's native file tools (Read/Edit/Write). format()thencheck("lint")— fix findings worth fixing.check("dry-build")— catches eval/build errors cheaply.diff()— show the user what will change.switch()— activate; reportsrollback_generation.- On regret:
generations(action="rollback").
Steps 3–5 are judgment calls, not gates — for a trivial change, going straight
to switch is fine.
On failure, the response includes a first_error field with the first
actionable error line from Nix's output, alongside the full log.
Design notes
- nix-agent does no file I/O. The host agent's own file tools are better at reading and editing; nix-agent only provides the Nix operations around them.
- No in-MCP approval gates. Path restrictions belong to the host's permission system; rollback safety belongs to Nix generations.
- Every response echoes
resolved_targetand the exactcommandrun — nothing is silently implicit. - Do not write secret payloads into configs — reference secrets via sops-nix or agenix.
- Fully non-interactive switch requires privileged automation; see
docs/privileged-automation.md.
More detail
- skill docs:
skills/nix-agent/SKILL.md - examples:
examples/