proxmox-ai

Servidor MCP que permite a un agente de IA administrar Proxmox VE en lenguaje natural, sin darle nunca más poder del estrictamente necesario.

"¿Qué contenedores están ejecutándose?"        → responde
"¿Cuál está consumiendo más RAM?"              → responde
"Reinicia el CT 105"                           → propone, espera confirmación, ejecuta
"Haz rollback del snapshot pre-update"         → exige una frase literal del humano
"Borra el CT 105"                              → no existe esa herramienta

El diseño parte de una idea: el modelo propone, el motor de políticas decide y el registro de auditoría lo recuerda.

Estado

Fase 1 (solo lectura) implementada y probada. Las fases 2 a 5 están implementadas pero desactivadas por defecto: se habilitan una a una con variables de entorno, y cada una necesita además su privilegio en la ACL de Proxmox. Ver docs/roadmap.md.

Instalación rápida

En el nodo Proxmox, crea el usuario y el token dedicados:

./scripts/setup-proxmox-user.sh

Copia el secreto del token: Proxmox no lo vuelve a mostrar.

En el contenedor donde vivirá el MCP (ver docs/instalacion.md para crearlo):

git clone https://github.com/dallaswk/proxmox-ai.git
cd proxmox-ai
python3 -m venv .venv && . .venv/bin/activate
pip install -e .

cp .env.example .env && chmod 600 .env
$EDITOR .env          # PROXMOX_HOST, PROXMOX_TOKEN_ID, PROXMOX_TOKEN_SECRET

Comprueba que arranca y que ve la infraestructura:

set -a && . ./.env && set +a
proxmox-ai            # habla MCP por stdin/stdout; Ctrl-C para salir

Conéctalo a tu cliente MCP (Claude Desktop, Claude Code, etc.):

{
  "mcpServers": {
    "proxmox": {
      "command": "/opt/proxmox-ai/.venv/bin/proxmox-ai",
      "env": {
        "PROXMOX_HOST": "proxmox.midominio.local",
        "PROXMOX_TOKEN_ID": "ai-agent@pve!mcp",
        "PROXMOX_TOKEN_SECRET": "...",
        "PROXMOX_AI_READ_ONLY": "true",
        "PROXMOX_AI_AUDIT_LOG": "/var/log/proxmox-ai/audit.jsonl"
      }
    }
  }
}

Cómo funciona la seguridad

Cuatro capas independientes. Cada una vale por sí sola:

1. La ACL de Proxmox. Es la frontera real. El token es un usuario dedicado con --privsep 1, nunca root@pam, y en la Fase 1 sólo tiene PVEAuditor. Un token que no puede borrar una VM no la borra ni aunque todo lo demás falle.

2. Flags de capacidad. PROXMOX_AI_READ_ONLY=true bloquea cualquier escritura sin importar el resto de la configuración. Cada fase tiene su propio flag, y las operaciones irreversibles necesitan uno adicional.

3. Confirmación en dos pasos. Una herramienta de escritura llamada sin confirm_token no toca nada: devuelve un plan y un token de un solo uso ligado a esa acción exacta. El humano ve el plan entre las dos llamadas. Para las operaciones irreversibles hay que enviar además una frase literal (CONFIRMO ROLLBACK SNAPSHOT 105); un "sí" no basta.

4. Sin shell arbitrario. No hay execute_any_command. Los comandos dentro de los guests pasan por una lista blanca de argv, con dos listas negras por delante —binarios (rm, dd, bash…) y opciones destructivas— y rechazo de metacaracteres de shell. La lista negra de opciones existe porque un binario que parece de lectura puede tener un flag que no lo es: journalctl -u nginx --vacuum-time=1s borra los logs archivados. Los argumentos se escapan además con shlex.quote, porque ssh host cmd siempre lo reinterpreta el shell remoto.

Y por debajo de todo, un registro JSONL append-only con cada intento —incluidos los rechazados— y sin un solo secreto.

Lo que esto no resuelve: un servidor MCP no puede distinguir "el humano dijo sí" de "el modelo decidió seguir". La confirmación en dos pasos garantiza que nada irreversible ocurre como efecto colateral de una sola llamada, y deja rastro de todo, pero la garantía dura es la ACL. Está explicado sin adornos en docs/modelo-de-seguridad.md.

Herramientas

Fase 1 — lectura (activa por defecto, sólo necesita PVEAuditor)

Fase 2 — encendido (PROXMOX_AI_ENABLE_POWER, priv. VM.PowerMgmt)

pve_guest_power — start, shutdown, reboot, stop. Confirmación obligatoria.

Fase 3 — snapshots (PROXMOX_AI_ENABLE_SNAPSHOT, priv. VM.Snapshot)

pve_create_snapshot (nivel 1) · pve_rollback_snapshot y pve_delete_snapshot (nivel 2: frase literal + PROXMOX_AI_ENABLE_DESTRUCTIVE)

Fase 4 — backups (PROXMOX_AI_ENABLE_BACKUP, priv. VM.Backup)

pve_create_backup — nivel 1. La restauración no está implementada a propósito: es la operación más destructiva de Proxmox. Ver docs/modelo-de-seguridad.md.

Fase 5 — diagnóstico dentro de los guests (PROXMOX_AI_ENABLE_GUEST_EXEC)

Ejemplo real de la confirmación en dos pasos

Usuario:  Reinicia el CT 105.

Agente:   [pve_guest_power vmid=105 operation=reboot]
          → confirmation_required
            "REBOOT CT 105 (web-production) on node pve1 — will request a
             clean reboot via the guest OS."
            nothing_has_changed: true
            confirm_token: "kJ8x...b2"

          Voy a reiniciar el CT 105 (web-production) en el nodo pve1.
          Es un reinicio limpio a través del sistema operativo. ¿Confirmas?

Usuario:  Sí.

Agente:   [pve_guest_power vmid=105 operation=reboot confirm_token="kJ8x...b2"]
          → status: completed

          Reiniciado. La tarea terminó con estado OK.

Si el agente intentara usar ese mismo token para el CT 101, o para un stop en lugar de un reboot, el motor lo rechazaría: el token está ligado por HMAC a la acción exacta, el guest y los parámetros.

Desarrollo

pip install -e ".[dev]"
pytest                    # 229 tests, sin red ni Proxmox real
ruff check src tests

Los tests usan httpx.MockTransport con un clúster falso (1 nodo, 2 CT, 1 VM, 2 storages). No hace falta un Proxmox para desarrollar.

Documentación

• docs/instalacion.md — instalación paso a paso

• docs/modelo-de-seguridad.md — amenazas y límites

• docs/roadmap.md — las 7 fases, con checklist

• docs/especificacion-original.md — el documento de partida

Licencia

MIT