proximo-proxmox 0.1.1

The ethical Proxmox MCP — REST API management + scoped in-container exec, behind clean native tools, least-privilege and audited.

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.1.1 "Spaniard" — public on GitHub (release, CI green). PyPI publish is in progress; until it lands, uvx proximo and the Docker image (GHCR) below don't work yet — install from source.

Proximo runs on your machine (wherever your MCP client lives), on demand — like every other Proxmox MCP.

From source (works today):

git clone https://github.com/john-broadway/proximo.git && cd proximo
uv pip install -e .        # or: pip install -e .

Wire it into your MCP client (Claude Desktop/Code, Cursor, …) as the command python -m proximo (or the proximo console script once installed), with the PROXIMO_* env vars — see packaging/proximo.env.example.

Coming as publishing completes (the pip package is proximo-proxmox; the command stays proximo): uvx proximo-proxmox and docker run -i --rm --env-file proximo.env -v ~/.ssh:/root/.ssh:ro ghcr.io/john-broadway/proximo:latest (stdio, on-demand, no daemon). v0.1.1 "Spaniard" is tagged; these ship once it's published to PyPI/GHCR. (PyPI's bare proximo is reserved, so the distribution is proximo-proxmox — import proximo and the proximo command are unchanged.)

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, not apt.)

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. LOW means "does not change state," not "safe" — a read can still exfiltrate. The absence of a HIGH flag is not a safety signal; the destructive-pattern signatures are curated, not exhaustive. Review every change yourself.

Status — the arena record

🩸 0.1.1 "Spaniard" — public on GitHub (2026-06-10); PyPI in progress. All four trust pillars (PLAN · PROVE · UNDO · DIAGNOSE) built and redteamed. 117 MCP tools. 1964 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 options dict) — full create→read→delete cycles against a real PVE 9.2 API, PROVE ledger verified throughout.
• 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 117-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 (in progress) + GHCR via a release Action — then uvx proximo is real
• Live smoke of the remaining surface (firewall · 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. ⚔️