proxmox-ai

Сервер MCP, который позволяет ИИ-агенту управлять Proxmox VE на естественном языке, никогда не давая ему больше власти, чем строго необходимо.

"¿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

Дизайн исходит из идеи: модель предлагает, движок политик решает, а журнал аудита запоминает.

Статус

Фаза 1 (только чтение) реализована и протестирована. Фазы 2–5 реализованы, но отключены по умолчанию: они включаются по одной с помощью переменных окружения, и каждая также требует своего привилегированного доступа в ACL Proxmox. См. docs/roadmap.md.

Быстрая установка

На узле Proxmox создайте выделенного пользователя и токен:

./scripts/setup-proxmox-user.sh

Скопируйте секрет токена: Proxmox больше его не покажет.

В контейнере, где будет жить MCP (см. docs/instalacion.md для его создания):

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

Проверьте, что он запускается и видит инфраструктуру:

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

Подключите его к вашему MCP-клиенту (Claude Desktop, Claude Code и т. д.):

{
  "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"
      }
    }
  }
}

Как работает безопасность

Четыре независимых уровня. Каждый работает сам по себе:

1. ACL Proxmox. Это реальная граница. Токен — это выделенный пользователь с --privsep 1, никогда не root@pam, и в Фазе 1 у него только PVEAuditor. Токен, который не может удалить ВМ, не удалит её, даже если всё остальное выйдет из строя.

2. Флаги возможностей. PROXMOX_AI_READ_ONLY=true блокирует любую запись независимо от остальной конфигурации. У каждой фазы есть свой флаг, а необратимые операции требуют дополнительного.

3. Двухэтапное подтверждение. Инструмент записи, вызванный без confirm_token, ничего не трогает: он возвращает план и одноразовый токен, привязанный к этому точному действию. Человек видит план между двумя вызовами. Для необратимых операций необходимо также отправить буквальную фразу (CONFIRMO ROLLBACK SNAPSHOT 105); простого «да» недостаточно.

4. Никакого произвольного shell. Нет execute_any_command. Команды внутри гостевых систем проходят через белый список argv, с двумя чёрными списками впереди — бинарники (rm, dd, bash…) и деструктивные опции — и отклонением метасимволов shell. Чёрный список опций существует потому, что бинарник, который выглядит как для чтения, может иметь флаг, который таковым не является: journalctl -u nginx --vacuum-time=1s удаляет архивные логи. Аргументы дополнительно экранируются с помощью shlex.quote, потому что ssh host cmd всегда переинтерпретируется удалённым shell.

А под всем этим — журнал JSONL append-only с каждой попыткой — включая отклонённые — и ни одного секрета.

Что это не решает: MCP-сервер не может отличить «человек сказал да» от «модель решила продолжить». Двухэтапное подтверждение гарантирует, что ничего необратимого не произойдёт как побочный эффект одного вызова, и оставляет след всего, но долгосрочная гарантия — это ACL. Это объяснено без прикрас в docs/modelo-de-seguridad.md.

Инструменты

Фаза 1 — чтение (активна по умолчанию, нужен только PVEAuditor)

Фаза 2 — включение (PROXMOX_AI_ENABLE_POWER, прив. VM.PowerMgmt)

pve_guest_power — start, shutdown, reboot, stop. Обязательное подтверждение.

Фаза 3 — снимки (PROXMOX_AI_ENABLE_SNAPSHOT, прив. VM.Snapshot)

pve_create_snapshot (уровень 1) · pve_rollback_snapshot и pve_delete_snapshot (уровень 2: буквальная фраза + PROXMOX_AI_ENABLE_DESTRUCTIVE)

Фаза 4 — резервное копирование (PROXMOX_AI_ENABLE_BACKUP, прив. VM.Backup)

pve_create_backup — уровень 1. Восстановление намеренно не реализовано: это самая разрушительная операция в Proxmox. См. docs/modelo-de-seguridad.md.

Фаза 5 — диагностика внутри гостевых систем (PROXMOX_AI_ENABLE_GUEST_EXEC)

Реальный пример двухэтапного подтверждения

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.

Если бы агент попытался использовать тот же токен для CT 101 или для stop вместо reboot, движок отклонил бы его: токен привязан через HMAC к точному действию, гостю и параметрам.

Разработка

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

Тесты используют httpx.MockTransport с фальшивым кластером (1 узел, 2 CT, 1 ВМ, 2 хранилища). Для разработки не нужен Proxmox.

Документация

• docs/instalacion.md — пошаговая установка

• docs/modelo-de-seguridad.md — угрозы и ограничения

• docs/roadmap.md — 7 фаз, с чек-листом

• docs/especificacion-original.md — исходный документ

Лицензия

MIT