I didn't trust an AI with my Proxmox cluster — so I built one that can't surprise me

John Broadway (Broadway) — Fri, 19 Jun 2026 21:00:43 +0000

I wanted an AI agent that could actually run my Proxmox cluster — create VMs, fix storage, tail logs inside a container — not just read it back to me. Then I pictured it deleting a storage pool and learning, at the exact second I did, which VMs just lost their boot disks. That image is why I never wired one up.

So I built the version I'd actually trust: Proximo, an open-source (Apache-2.0) Proxmox MCP + A2A server. The whole design goal is one sentence — the AI has to show me what it's about to do before it does it, and I keep the receipts.

The two things on offer, and the third I wanted

Go looking for a Proxmox MCP server today and you find two shapes: a read-mostly "safe inspector" (the most-starred one is exactly this — a handful of read tools, popular because it doesn't hold the knives), or a feature-rich mutator you trust on faith. I wanted the third thing — full management I could point at a hypervisor I care about, with trust built into the substrate instead of bolted onto the door.

Four pillars, by construction

Every tool inherits these; they aren't per-tool flags you can forget to set:

PLAN — every mutation is dry-run first. It returns the exact change, the guest's live state, and a computed blast radius. Delete a storage and it doesn't just warn "this is dangerous" — it reads the cluster and names the guests that lose a disk:

$ (dry-run) pve_storage_delete storage=local-zfs
PLAN — RISK_HIGH
  affected (cluster-wide):
    - vm/104  won't-boot   (boot disk scsi0 on local-zfs)
    - vm/210  won't-boot   (only copy of scsi0)
    - ct/301  degraded     (mp1 data volume on local-zfs)
  recorded to ledger: chain ok (#1438)
  -> you cannot mutate without this plan existing first

In 0.6.0 that blast-radius reasoning spans the destructive surface — storage, disk-move, firewall rules (reach + lockout), network-apply, guest-destroy, ACL changes, migrations.

PROVE — a hash-chained, tamper-evident audit ledger. Plans and confirmations both land in it; the trail is verifiable after the fact, and it lives on your box, not a SaaS dashboard.
UNDO — auto-snapshot before a risky change (fail-closed if the storage can't snapshot), one-call rollback.
DIAGNOSE — a read-only evidence battery where an empty findings list never reads as a false clean bill.

Safe by default, honest about the sharp edge

Proximo is API-only out of the box — the hypervisor itself is never touched; management goes over the Proxmox REST API with a scoped token. The one genuinely sharp edge is running a command inside an LXC: the REST API has no container-exec endpoint at all (it lives in lxc-attach), so most API-based servers structurally can't do it. Proximo can — over your existing ssh — but it's opt-in (PROXIMO_ENABLE_EXEC=1), gated by a fail-closed CTID allowlist, and it says plainly that it grants near-root. The token is never read or logged.

The honesty section (because the tool is about trust)

I'd rather you trust the project than the marketing:

It's v0.6.0, days old, zero adoption.
145 tools, 2394 tests — but most of that surface still runs against mocks. Live-proven against a real PVE 9.2 API: the trust spine end-to-end, the governance/dangerous plane (roles/groups/users/ACLs, storage, SDN/network, realms), offline guest migration, HA-config — full create→read→delete with the ledger verified. Not proven: HA fencing (needs a hardware watchdog), online live-migration (needs shared storage), production scale.
Risk ratings are an advisory heuristic, not a sandbox. LOW means "no state change," not "safe."
I'm not claiming first, most tools, or "the only one with trust." proxxx (a Rust cockpit with a pre-flight risk gate, an HMAC-keyed audit chain, and Telegram human-in-the-loop) and RekklesNA's ProxmoxMCP-Plus (command policy + approval tokens) both have real trust mechanisms. Proximo's specific bet is trust by construction across the whole control plane, plus auto-UNDO and exposing the governance plane to the agent at all.

There's a tailwind that isn't just my opinion: the OWASP MCP Top 10 now lists "Lack of Audit and Telemetry," and the official MCP security guidance explicitly names "blast radius" and "irrecoverable data loss on the host." PROVE is that recognized need, built; PLAN and UNDO go a step beyond what the spec has codified — ahead of the standard, not blessed by it.

How it was built (the honest version)

The direction, the design calls, and the trust model are mine — but I didn't build it alone, and I'd rather say so than have you wonder. It's an open human+AI partnership: Claude (Anthropic's model) did much of the actual implementation, and Maude (my own Claude-helper plugin) is the gates and second-lens that watched the work. Every commit carries its co-author trailer. For a tool whose whole pitch is transparency, telling you exactly how it was made felt like part of the deal.

Try it / break it

uvx proximo-proxmox
# or: pip install proximo-proxmox
# A2A face: pip install 'proximo-proxmox[a2a]' && proximo-a2a

Wire it into your MCP client (Claude Desktop/Code, Cursor, …) as the proximo command with PROXIMO_* env vars.

GitHub: https://github.com/john-broadway/proximo
PyPI: https://pypi.org/project/proximo-proxmox/

It's early, and I'd genuinely rather find the holes now than after someone trusts it with a real cluster. The blast-radius logic, the trust model, whether the honesty holds up — tear it apart in the comments or in an issue.