convez.ai
MCP ServerDevOps & InfraestruturaAvançado
JEFF7712

nix-agent

JEFF7712/nix-agent

Operações NixOS controladas por IA: eval, lint, format, build, diff, switch

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor 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-agent

1 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

Estrelas
18
Forks
2
Acompanhando
0
Saúde
42%
Último commit
há 1 dia
Versão
v0.15.0
Issues abertas
1
Contribuidores
1

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-agent handles operations on your actual configuration — evaluating, linting, formatting, building, diffing, switching
  • mcp-nixos handles 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.

ToolWhat 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

  1. Discovery: query mcp-nixos for packages/options; use eval_config to see what the user's machine currently resolves.
  2. Edit .nix files with the agent's native file tools (Read/Edit/Write).
  3. format() then check("lint") — fix findings worth fixing.
  4. check("dry-build") — catches eval/build errors cheaply.
  5. diff() — show the user what will change.
  6. switch() — activate; reports rollback_generation.
  7. 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_target and the exact command run — 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/
Ver o original no GitHub

Bom para

Relacionados