# 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](docs/roadmap.md).

| | |
|---|---|
| Herramientas MCP | 27 |
| Tests | 229 (`pytest`) |
| Dependencias | `mcp`, `httpx` |
| Python | ≥ 3.11 |

---

## Instalación rápida

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

```bash
./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](docs/instalacion.md) para crearlo):

```bash
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:

```bash
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.):

```json
{
  "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](docs/modelo-de-seguridad.md).

---

## Herramientas

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

| Herramienta | Para qué |
|---|---|
| `pve_policy_status` | Qué está permitido ahora mismo |
| `pve_list_nodes` | Nodos con CPU, RAM y disco raíz |
| `pve_list_guests` | LXC y VMs con su consumo; de aquí salen los VMID |
| `pve_top_consumers` | Ranking por RAM, CPU o disco |
| `pve_guest_status` | Estado detallado de un guest |
| `pve_guest_config` | Configuración: cores, memoria, discos, red |
| `pve_guest_metrics` | Históricos RRD: distingue pico de problema sostenido |
| `pve_storage_status` | Espacio libre, con alertas al 85% y 92% |
| `pve_recent_tasks` | Tareas recientes y cuáles fallaron |
| `pve_task_log` | Log completo de una tarea |
| `pve_list_snapshots` | Snapshots de un guest |
| `pve_list_backups` | Backups disponibles |
| `pve_health_report` | Revisión completa: nodos, guests, storage, tareas |

### 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](docs/modelo-de-seguridad.md#lo-que-falta-a-proposito).

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

| Herramienta | Para qué |
|---|---|
| `guest_list_allowed_commands` | Qué puede ejecutar el agente |
| `guest_check_service` | ¿Está nginx arriba? |
| `guest_read_logs` | journalctl, opcionalmente sólo errores |
| `guest_resources` | `df`/`free`/`uptime` vistos desde dentro |
| `guest_docker_ps` · `guest_docker_logs` | Estado y logs de contenedores Docker |
| `guest_run_command` | Un comando de la lista blanca |
| `guest_diagnose_web` | Diagnóstico completo del stack web |
| `guest_restart_service` | Reinicia un servicio. Nivel 1 |

---

## 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

```bash
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](docs/instalacion.md) — instalación paso a paso
- [docs/modelo-de-seguridad.md](docs/modelo-de-seguridad.md) — amenazas y límites
- [docs/roadmap.md](docs/roadmap.md) — las 7 fases, con checklist
- [docs/especificacion-original.md](docs/especificacion-original.md) — el documento de partida

## Licencia

MIT