proxmox-ai

에이전트가 자연어로 Proxmox VE를 관리할 수 있게 해주는 MCP 서버로, 필요한 권한 이상을 절대 부여하지 않는다.

"¿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단계는 구현되었지만 기본적으로 비활성화되어 있다: 환경 변수로 하나씩 활성화하며, 각 단계는 Proxmox ACL의 해당 권한도 추가로 필요하다. 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"
      }
    }
  }
}

보안 작동 방식

독립적인 4개 계층. 각각 단독으로도 유효하다:

1. Proxmox ACL. 실제 경계선이다. 토큰은 --privsep 1을 가진 전용 사용자이며, 절대 root@pam이 아니고, 1단계에서는 PVEAuditor만 가진다. VM을 삭제할 수 없는 토큰은 다른 모든 것이 실패해도 VM을 삭제하지 않는다.

2. 기능 플래그. PROXMOX_AI_READ_ONLY=true는 나머지 설정과 무관하게 모든 쓰기를 차단한다. 각 단계에는 자체 플래그가 있으며, 되돌릴 수 없는 작업은 추가 플래그가 필요하다.

3. 2단계 확인. confirm_token 없이 호출된 쓰기 도구는 아무것도 건드리지 않는다: 계획과 해당 정확한 작업에 바인딩된 일회용 토큰을 반환한다. 인간은 두 호출 사이에 계획을 본다. 되돌릴 수 없는 작업의 경우 추가로 리터럴 문구(CONFIRMO ROLLBACK SNAPSHOT 105)를 보내야 한다. "예"만으로는 부족하다.

4. 임의 셸 없음. execute_any_command는 없다. 게스트 내부의 명령은 argv 화이트리스트를 통과하며, 앞서 두 개의 블랙리스트—바이너리(rm, dd, bash…)와 옵션 파괴적 항목—가 있고 셸 메타문자는 거부된다. 옵션 블랙리스트가 존재하는 이유는 읽기 전용으로 보이는 바이너리에도 그렇지 않은 플래그가 있을 수 있기 때문이다: journalctl -u nginx --vacuum-time=1s는 보관된 로그를 삭제한다. 인자는 또한 shlex.quote로 이스케이프되는데, ssh host cmd는 원격 셸이 항상 이를 재해석하기 때문이다.

그리고 그 아래에는 모든 시도—거부된 것 포함—를 기록하고 비밀은 하나도 저장하지 않는 append-only JSONL 로그가 있다.

이것이 해결하지 못하는 것: MCP 서버는 "인간이 승인했다"와 "모델이 스스로 결정했다"를 구분할 수 없다. 2단계 확인은 단일 호출의 부수 효과로 되돌릴 수 없는 일이 발생하지 않음을 보장하고 모든 것을 추적하지만, 진짜 보장은 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)

2단계 확인의 실제 예

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에 사용하거나 reboot 대신 stop에 사용하려 하면 엔진이 거부한다: 토큰은 HMAC로 정확한 작업, 게스트 및 매개변수에 바인딩되어 있기 때문이다.

개발

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

테스트는 가짜 클러스터(노드 1, CT 2, VM 1, 스토리지 2)와 함께 httpx.MockTransport를 사용한다. 개발에 Proxmox가 필요하지 않다.

문서

• docs/instalacion.md — 단계별 설치

• docs/modelo-de-seguridad.md — 위협 및 한계

• docs/roadmap.md — 체크리스트가 있는 7개 단계

• docs/especificacion-original.md — 출발 문서

라이선스

MIT