Proximo — Controle Ético de Proxmox para Agentes IA
john-broadway/proximo
Controle Proxmox ético: API + exec em contêiner, auditado e least-privilege
Ver no GitHubMCP server que oferece controle completo do Proxmox VE para agentes IA com princípios de confiança por construção. Combina API REST para gerenciamento de nós e VMs com execução de comandos em contêineres LXC via SSH, tudo com escopo mínimo de privilégio, auditoria e gates de confirmação para operações mutantes.
Instalação
npx convez-ai john-broadway/proximo1 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
Casos de uso
- Automação de ciclo de vida de máquinas virtuais e contêineres Proxmox
- Orquestração de infraestrutura com agentes IA confiáveis
- Execução remota segura de comandos dentro de LXC com rastreamento completo
Veredito

Proximo resolve um vazio real no ecossistema Proxmox + MCP: integra API management com execução em contêiner (que a API REST não cobre), tudo com rigor em segurança e auditoria. Implementação sólida, bem documentada, testada e production-ready para quem precisa controlar Proxmox via agentes IA de forma confiável.
README
A tradução para o português deste README ainda está na fila.
Proximo
The ethical Proxmox MCP. API management and scoped in-container execution — behind clean, native tools, least-privilege by default, every action audited.
Named for Proximo, the lanista in Gladiator who equips the fighter and gives him his shot at freedom — Proximo hands the operator the means to act on the machine, no more than needed, accountable for every move.
"Win the crowd and you will win your freedom." — Proximo
Strength and honor. — the creed: solid, strong, accountable.
Why Proximo exists
Proxmox VE has a full REST API and a terse, powerful CLI — but the MCP landscape around it is split, and neither half is whole:
- API-based MCP servers give rich management (nodes, VMs, storage) but cannot run a command inside an LXC — that's a structural gap: the Proxmox REST API has no container-exec endpoint (it lives in
lxc-attach, kernel namespaces, no REST surface). - SSH-based MCP servers can exec in containers, but lean on broad shell access with little scoping.
Few build the principled one — both halves, on one clean surface, least-privilege, audited, trustworthy enough to point at a hypervisor you care about. That's the bar Proximo aims at. (Others work the trust angle too — notably fabriziosalmi/proxxx; see LANDSCAPE.md. Proximo's specific bet is trust by construction across the whole control plane.)
There is no official Proxmox MCP (and likely won't be soon — Proxmox ships the API+CLI and leaves integrations to the community, the same way there's no official Terraform provider). Proximo is a community project, standing on its own.
What it does
Two backends behind one tool surface:
| Backend | Mechanism | For |
|---|---|---|
| Management | Proxmox REST API + scoped token | node status, list/inspect guests, lifecycle (start/stop/reboot) |
| Exec | ssh → pct exec | run-command-in-container, psql convenience, log tailing — the things the API structurally can't do |
Principles (the mantra, baked in — not bolted on)
- Ethical — least-privilege by default, every action audited, mutations confirm-gated, secrets never read or logged.
- Solid — real tests (unit + a live smoke against a throwaway CTID), typed, documented, no silent failures.
- Strong — does the hard thing (container exec) cleanly and least-privileged (fail-closed CTID allowlist, opt-in). (Container exec isn't unique — the field leader has it too; the differentiator is the trust layer below, not the exec.)
- Passion + craft — redteamed and linted before it's called done; shipped proud — docs, license, community-ready.
Install & run
📦
0.2.0— published. On PyPI (proximo-proxmox), GitHub (CI green), and GHCR (signed multi-arch image) — all three live.
Proximo runs on your machine (wherever your MCP client lives), on demand — like every other Proxmox MCP.
The pip package is
proximo-proxmox(PyPI's bareproximois reserved); the command and import stayproximo. With the[a2a]extra you also get theproximo-a2aserver.
Install:
uvx proximo-proxmox # zero-install run, on demand
# or: pip install proximo-proxmox (adds the `proximo` + `proximo-a2a` commands)
# or: pip install "proximo-proxmox[a2a]" (also installs the optional A2A face)
Wire it into your MCP client (Claude Desktop/Code, Cursor, …) as the command proximo (or python -m proximo),
with the PROXIMO_* env vars — see packaging/proximo.env.example.
From source:
git clone https://github.com/john-broadway/proximo.git && cd proximo
uv pip install -e . # or: pip install -e .
Docker (GHCR): docker run -i --rm … ghcr.io/john-broadway/proximo:latest runs the stdio MCP server on demand — no daemon, no open port. Multi-arch (amd64 + arm64), shipped with an SBOM and a sigstore-signed build-provenance attestation (gh attestation verify oci://ghcr.io/john-broadway/proximo --owner john-broadway).
Safe by default: Proximo is API-only out of the box. The in-container exec edge is opt-in (
PROXIMO_ENABLE_EXEC=1) and tells you plainly that it grants near-root on the host.The hypervisor is never touched in either mode. Management goes over the Proxmox API (scoped token); the in-container exec edge goes over your existing ssh to PVE.
(A Debian package is deferred/optional — the MCP world installs via
uvx/pip/Docker, notapt.)
The trust layer — what makes Proximo different
Safe-exec for Proxmox already exists elsewhere. Proximo's distinct angle is the trust layer for AI-driven infrastructure — four pillars (see POSITIONING.md):
| Pillar | What it does | Status |
|---|---|---|
| PLAN | Dry-run by default: every mutation first returns a preview — the exact change, the guest's live state, blast radius, and an honest (advisory, heuristic) risk rating — recorded to the ledger. You can't mutate without the plan existing first. | ✅ built + redteamed |
| PROVE | Hash-chained, tamper-evident audit ledger; plans and confirmations both land in it, so the approval trail is verifiable after the fact. | ✅ built + redteamed |
| UNDO | Auto-snapshot before a risky change (waited-on, fail-closed if storage can't snapshot) + revert via pve_rollback; full snapshot lifecycle tools. Undo points aren't auto-pruned — delete with pve_snapshot_delete. (Snapshot/rollback are async — they submit a task you poll with pve_task_status.) | ✅ built + redteamed |
| DIAGNOSE | Read-only evidence battery (failed units, disk, errors, memory, listening ports) + node health (storage/tasks) → advisory flags. Flags surface incompleteness too, so an empty list never reads as a false clean bill. | ✅ built + redteamed |
Honesty note (load-bearing): PLAN's risk ratings are an advisory heuristic, not a sandbox.
LOWmeans "does not change state," not "safe" — a read can still exfiltrate. The absence of aHIGHflag is not a safety signal; the destructive-pattern signatures are curated, not exhaustive. Review every change yourself.
Status — the arena record
🩸 0.2.0 — published on PyPI (pip install proximo-proxmox), GitHub, and GHCR (signed multi-arch image). (0.1.1 "Spaniard" was the first public cut, 2026-06-10.)
All four trust pillars (PLAN · PROVE · UNDO · DIAGNOSE) built and redteamed. 144 MCP tools. 2126 tests,
0 skipped, ruff clean — CI runs the full suite on GitHub's own runners.
Proven against real Proxmox (not mocks):
- The trust spine end-to-end, the core provisioning/config mutate cycle, and PBS read shapes.
- The governance/dangerous plane — identity (roles/groups/users/ACLs), storage, SDN apply,
network-interface apply, realm create (LDAP/AD/OpenID via an
optionsdict) — full create→read→delete cycles against a real PVE 9.2 API, PROVE ledger verified throughout. - The 0.2.0 object planes — firewall objects (aliases/IP-sets/security-groups/options), HA rules (the PVE 9 replacement for HA groups), and SDN zones/VNets/subnets (pending, pre-apply) — create→read→delete live-proven against a real PVE 9.2 node; TFA admin reads proven (TFA mutation is ticket-gated by PVE, not token-accessible).
- Offline guest migration (including local-disk) and the HA-config lifecycle on a 3-node PVE 9.2 test cluster.
- Both protocol faces driven by real clients end-to-end: MCP over stdio, and A2A by the official a2a-sdk.
Not yet proven — said plainly: most of the 144-tool surface still runs against mocks; real HA
fencing (needs a hardware watchdog), online live-migration (needs shared storage), and behavior at
production scale. The full, unflattering field comparison lives in LANDSCAPE.md.
The A2A face (experimental, opt-in): pip install 'proximo[a2a]', then proximo-a2a — a curated
16-skill slice over Agent2Agent that routes through the same trust core (PLAN/PROVE/UNDO inherited;
there is no second code path to bypass). Fail-closed perimeter: non-localhost binds are refused without a
bearer token (PROXIMO_A2A_TOKEN_FILE); Host-header allowlist defends against DNS rebinding. Ledger note:
an opt-in HMAC-keyed chain is available (PROXIMO_AUDIT_KEY_PATH); the default is unkeyed —
tamper-evident, not tamper-proof — and an off-box head() anchor is the strong guarantee either way.
What's next
- PyPI —
proximo-proxmoxpublished 2026-06-10;uvx proximo-proxmoxworks - GHCR — signed multi-arch image (
ghcr.io/john-broadway/proximo:0.2.0/latest) via a release Action - Firewall objects · HA rules · SDN object CRUD — live-proven on PVE 9.2 (0.2.0)
- Live smoke of the remaining surface (PBS-mutate); HA fencing + online migration when the hardware exists
- PBS certificate-fingerprint wire-enforcement
- (optional) Debian package for the Debian-native crowd
The full build history — every pillar, every redteam, every fix — lives in CHANGELOG.md.
License
Apache-2.0 — chosen for the patent grant that suits infrastructure tooling. Full text in LICENSE.
Credits
Built by John Broadway with Claude and Maude — a human–AI partnership, and the first thing we made on this box to give away to the world.
Claude's contribution spans eras, credited honestly: Claude Opus 4.8 built the trust pillars and the tool surface (2026-06-07 → 06-09); Claude Fable 5 ran the 101-agent release audit and the publish (2026-06-10). Every commit carries its co-author trailer.
"Are you not entertained?" — stars, issues, and sparring partners welcome. Strength and honor. ⚔️