proximo-proxmox 0.24.0

The Proxmox MCP you can hand the keys — VE + Backup Server + Mail Gateway + Datacenter Manager on one clean surface: every dangerous op planned, undoable, and audited.

Quickstart · Setup · Trust layer · Demo · Tools · Install · Security · Docs

The Proxmox MCP you can hand the keys.

The others make you choose: a read-only inspector that's safe because it can't touch anything — or a loaded gun aimed at a cluster you care about. Proximo refuses the trade. Every dangerous move is planned (see the blast radius first) and proven (a tamper-evident record of every move), and undoable wherever the platform can snapshot (it snapshots before it acts) — trust built into the substrate, not bolted on after. Hand an AI agent the keys; keep the receipts.

Sovereign and agent-agnostic: your metal, your token, a ledger you own — no cloud, no phone-home, no standing server unless you opt in. Don't take our word for any of it — verify it yourself.

Verify in 60 seconds — three receipts, no trust required

# 1. The tool count is real — ask the server itself, cold (=> 715).
#    (in a clone of this repo, after `uv sync`)
uv run python -c "import asyncio; from proximo import server; \
print(len(asyncio.run(server.mcp.list_tools())))"

# 2. The container image is what the repo built — sigstore provenance (exit 0 = verified):
gh attestation verify oci://ghcr.io/john-broadway/proximo:latest --owner john-broadway

# 3. The security posture is graded by a third party, not by us:
#    https://scorecard.dev/viewer/?uri=github.com/john-broadway/proximo

The rest — forge a ledger byte and watch verify() refuse, grep the outbound surface for phone-home (there is none) — is in VERIFY.md. These checks work on any tool, from any vendor. Demand them everywhere.

---

_{Every transport enters one governed dispatch and crosses the same trust spine; the token floor beneath it all is enforced by Proxmox itself. Watch it hold, live, in the Demo.}

What it does

Ask, in plain English, "why is ct 105 thrashing?" — and an AI agent pulls node and guest status, tails the logs, and runs a diagnostic inside the container to find out. If there's a fix, it shows you the plan before it touches anything, snapshots first, applies, and hands you a signed receipt of exactly what changed.

That's the product: a hypervisor an AI can operate without being able to wreck it. Read-only by default. No mutation runs on the first call — it returns its blast radius as a plan for you to see first. A tamper-evident receipt for every change. The comparison isn't Proximo vs. the GUI — it's Proximo vs. handing an LLM your root token and hoping.

Quickstart

// your MCP client config (Claude Desktop / Claude Code / Cursor / …)
{
  "mcpServers": {
    "proximo": {
      "command": "uvx",
      "args": ["proximo-proxmox"],
      "env": {
        "PROXIMO_API_BASE_URL": "https://your-pve:8006/api2/json",
        "PROXIMO_NODE": "your-node",
        "PROXIMO_TOKEN_PATH": "/path/to/token-file"   // USER@REALM!TOKENID=SECRET — by reference, never inlined
      }
    }
  }
}

Or install with one click:

_{Both prompt for the token file path — the secret never lands in client config. No token yet? uvx proximo-proxmox mint prints the least-privilege runbook.}

Then preflight what your token can actually do (read-only):

uvx proximo-proxmox doctor

Start with a read-only token — Proximo is useful long before you grant it write. Full token-first walkthrough: docs/SETUP.md · more install paths: Install & run.

Why Proximo exists

The Proxmox MCP landscape is split: API-based servers manage nodes and VMs but structurally cannot run a command inside an LXC (the REST API has no exec endpoint); SSH-based servers can, through broad shell access with little scoping. Proximo builds the principled whole — both halves, one audited surface, least-privilege, trust by construction:

	Read-only inspector	Full-access executor	Proximo
Can mutate	no — that's the safety	yes	yes — plan recorded first, then confirm=true
Preview before a change	n/a	rarely	default — blast radius + live state, every mutation
Record of what happened	no	app logs, editable	keyed hash-chained ledger, tamper-evident, on by default
Undo	n/a	rare	snapshot-first, wherever the platform can snapshot
Command inside an LXC	no	broad SSH	opt-in, fail-closed CTID allowlist
Products covered	usually PVE	usually PVE	PVE + PBS + PMG + PDM — one audited plane
Verify the artifact you run	varies	varies	signed image · PyPI provenance · SBOM · Scorecard

(The archetype columns describe the split above, not any specific project. There is no official Proxmox MCP; Proximo is a community project, standing on its own.)

The trust layer — what makes Proximo different

Four controls on by default:

Control	What it does
PLAN	Every mutation first returns a recorded preview — the exact change, live state, blast radius, an advisory risk rating. Nothing mutates without its plan recorded; one confirm=true call records and performs.
PROVE	Keyed (HMAC-SHA256), hash-chained audit ledger — audit_verify catches edits, reordering, insertion. Pin the head off-box (expected_head) to catch truncation too: that's the strong guarantee, and it's opt-in.
UNDO	Snapshot-first, fail-closed where the platform can snapshot: auto-snapshot before risky exec, config-revert, pve_rollback. Planes with no snapshot primitive (firewall/SDN/ACL) have no rollback — said plainly.
DIAGNOSE	Read-only evidence battery + node health → advisory flags that surface incompleteness too, so an empty list never reads as a false clean bill.

Six more ship off until you configure them — per-plan CONSENT, a CONTAIN kill-switch, an arm-LEASE, an arm-time SCOPE, a FORBID/RATE ENVELOPE, and TAINT (the prompt-injection mitigation). What each one actually defends against: SECURITY.md.

Honesty note (load-bearing): risk ratings are an advisory heuristic, not a sandbox — LOW means "no state change," not "safe," and the absence of a HIGH flag is not a safety signal. Review every change yourself. The floor beneath it all is the token you mint: Proxmox RBAC holds even if Proximo's process is fully compromised — a stronger guarantee than anything Proximo's own code provides. Scope it to exactly what you mean to grant: SECURITY.md.

Hold any tool to this — including this one: The Keys Test — ten questions to ask before you hand an AI agent real infrastructure, Proximo's own scorecard published, partials included. And watch the spine hold, live:

_{41 seconds, recorded live with a write-scoped token on a throwaway guest — real mutations, real receipts, nothing staged. Reproduce it: scripts/demo/hand_the_keys.py --live.}

Demo

The record defends itself:

_{Three agent moves land in the ledger; one entry gets edited in place — audit_verify() breaks at the exact line, ok=False; the truncation a forward walk would miss is caught against the pinned head. Source: docs/demo/ledger-tamper.cast · run the checks yourself: VERIFY.md.}

A second cut — doctor preflight, a destructive delete answered with a PLAN, the ledger verifying clean — recorded live against real PVE 9.2 with a read-only token: docs/demo/demo.svg · scripts/demo/demo.py.

Surfaces & tools — one control plane

Surface	Backend	For
Proxmox VE	REST API + scoped token	node/guest lifecycle, storage, SDN, identity, HA, firewall
Proxmox Backup Server	REST API + scoped token	datastores, namespaces, snapshots, sync, GC, verify, tape
Proxmox Mail Gateway	Ticket auth	mail flow, quarantine, filtering rules, domains, services
Proxmox Datacenter Manager	API token	federated fleet — reads plus governed control (power/snapshot/migrate, dry-run-first)
Container exec	ssh → pct exec	run-command-in-container, psql, log tailing — what the API structurally can't do

Those backends are deliberately boring — anyone can call them. The product is the trust layer over them.

715 tools is an estate, not a starting point. Where an operator actually starts:

You want to…	Start with	Worth knowing
See the whole cluster at once	pve_cluster_resources, pve_list_guests	one call, every node
Find out why a container is sick	ct_diagnose, ct_logs, pve_guest_status	read-only evidence battery
Preflight a token / config	proximo doctor (CLI) or pve_doctor, pve_overbroad_grants	run this before wiring an agent
Power / lifecycle	pve_guest_power	returns a PLAN first — nothing moves without confirm=true
Snapshot before touching anything	pve_snapshot_create, pve_rollback	UNDO's foundation
Check backups are actually fresh	pve_backup_freshness, pbs_snapshots_list	walks real archives — "task OK" is never evidence
Run a command in a container	ct_exec	opt-in (PROXIMO_ENABLE_EXEC=1), fail-closed allowlist
Trace / release mail	pmg_tracker_list, pmg_quarantine_spam	full PMG plane behind it
Operate the federated fleet	pdm_resources_list, pdm_pve_lxc_list	governed control, dry-run-first
Prove the record wasn't touched	audit_verify	registered on every surface, always

Every tool, grouped by surface, with typed inputs: docs/TOOLS.md.

Install & run

📦 0.24.0 — on PyPI, GitHub, and GHCR (signed multi-arch image).

New in 0.24.0 — Ceph + SDN deep. 603 → 715 tools. The full Ceph plane (OSD/mon/mgr/mds lifecycle, pools, CephFS — destroy previews quote Ceph's own cmd-safety verdict) and the deep SDN surface (controllers, DNS, IPAMs, fabrics, vnet firewall, prefix-lists, route-maps — with SDN dry-run in apply previews, the global lock as a never-ledgered capability token, and rollback as a real undo for staged SDN config). Both planes closed by exit-code-gated audits (48/48 + 90/90 methods, 0 undocumented). Schema-built, not yet live-proven — docstrings say which.

Recent: 0.23.0 — the PBS plane closed: 493 → 603, tape/S3/metrics/pull-push, coverage proven by audit (349 endpoints, 0 gaps). See SECURITY.md for what each control honestly holds.

Proximo runs on your machine, on demand — no daemon, no open port.

uvx proximo-proxmox            # zero-install run (PyPI package: proximo-proxmox; command stays `proximo`)
# or: pip install proximo-proxmox            the MCP core
# or: pip install "proximo-proxmox[a2a]"     + the optional A2A face
# or: pip install "proximo-proxmox[http]"    + the optional HTTP/OpenAPI face
# or, from source:  git clone https://github.com/john-broadway/proximo.git && cd proximo && uv pip install -e .

Wire it into your MCP client as the command proximo, with the PROXIMO_* env vars — see packaging/proximo.env.example.

Docker (GHCR): docker run -i --rm … ghcr.io/john-broadway/proximo:latest — multi-arch, SBOM, sigstore-signed provenance (gh attestation verify oci://ghcr.io/john-broadway/proximo --owner john-broadway). Mirrored to Docker Hub (docker.io/jebroadway/proximo, identical digest); GHCR stays the signed primary.

Safe by default: API-only out of the box. The two near-root edges are opt-in and say so loudly — LXC exec (PROXIMO_ENABLE_EXEC=1, near-root on the host) and the qemu-guest-agent edge (PROXIMO_ENABLE_AGENT=1, near-root in a guest) — each scoped by its own fail-closed allowlist.

Big surface, scoped context: you don't have to load the whole estate. PROXIMO_SURFACES=pve,exec registers only those planes (that pair = 202 tools) — unpicked planes never touch your context window; audit_verify always stays; a typo'd surface refuses startup.

The network faces (experimental, opt-in): proximo-a2a speaks Agent2Agent; proximo-http serves plain HTTP + generated /openapi.json for no-code clients. Both serve the full surface through the same governed dispatch as MCP — no second code path, trust spine and token scope inherited. Fail-closed perimeter: loopback, bearer-token required off-localhost, DNS-rebind and CSRF defended. Details: SECURITY.md.

At scale

One container is the demo. A cluster is the point.

• The whole cluster in one call — pve_cluster_resources: every VM, node, storage pool, SDN object.
• One tamper-evident record across every node — "show me every state-changing action this month, and prove the log wasn't touched" becomes a query you can actually answer. No human at the CLI walks away with that.
• Where the time comes back — on one node a senior at the CLI is faster, and that's fine; across a dozen nodes and hundreds of guests, a bounded, audited agent earns its keep.

Many boxes, one Proximo: register remotes in a TOML file (secrets by reference, never inlined), point PROXIMO_TARGETS at it, aim any tool with proximo_target="edge-pve". The target travels with the call — PLAN and EXECUTE hit the same box, the ledger records which, cross-plane calls error. Config shape: packaging/targets.example.toml.

Status — the arena record

• 🩸 0.24.0 — Ceph + SDN deep: 603 → 715 tools — the full Ceph plane (destroys quote Ceph's own cmd-safety verdict in the preview) and deep SDN (fabrics, vnet firewall, routing policy, plus dry-run/lock/rollback as first-class governance). Both closed by exit-code-gated audits (48/48 + 90/90, 0 undocumented). Every chunk adversarially reviewed; the reviews caught real defects every time — including a lock-token echo — all fixed before ship.

Every release before it — every pillar, every redteam, every fix — lives in CHANGELOG.md.

The numbers, honestly: 715 MCP tools, proved in two deliberate layers — 9,100+ in-process tests (ruff + pyright clean) pin every tool's shape, and a separate live-smoke harness drives real Proxmox hardware: a 3-node PVE 9.2 cluster, PBS 4.2, PMG 9.1, PDM 1.1.4, a real cross-datacenter move. The two are kept apart on purpose — passing shape tests never gets to masquerade as "works on a real host." And this workspace administers its own Proxmox estate through Proximo daily (dogfood). The blast-radius engine carries the destructive surface: across eleven op-classes it names the specific guests, nodes, principals, or disks at risk — nothing falls back to a bare confirm.

Proven live (not mocks): the trust spine end-to-end; identity/storage/SDN/firewall/HA create→read→delete with the ledger verified throughout; offline + online live-migration and HA fencing (softdog) on a real 3-node cluster; full PBS/PMG/PDM planes including a real cross-datacenter move. Not yet proven — said plainly: hardware-watchdog fencing (needs physical iTCO/IPMI) and behavior at production scale. The unrecoverable ops (SDN apply, etc.) are deliberately never fired live — proven by plan, held back by design, not a gap. Per-surface detail: CHANGELOG.md.

Documentation

Document	What it answers
Setup	Token-first walkthrough: mint a least-privilege token, verify it, widen deliberately.
Verify	Every trust claim paired with the command that proves it — run them cold.
Security	The two-deployment trust model, all ten controls, what each honestly holds, reporting.
Threat model	What Proximo defends against, what it doesn't, where the boundaries sit.
Tools	All 715 tools, grouped by surface, typed inputs.
Agents	The page written for the agent itself — Proximo's sharp edges, stated first.
Known issues	What's broken or odd right now, said plainly.
Contributing	Dev setup, the CI gates, what a PR is expected to keep intact.
Changelog	Every release, every redteam, every fix — the full build history.

License

Apache-2.0 — chosen for the patent grant that suits infrastructure tooling. Full text in LICENSE.

Credits

Named for Proximo, the lanista of Gladiator — the story is the design, joint for joint. He armed his fighter with exactly what he needed, never more, and answered for every move in the arena: a lanista, not a jailer. The Spaniard doesn't get his name up front — he earns it, by conduct, on the record: the helmet that comes off (truth said plainly, at cost — the "not yet proven, said plainly" section, and AGENTS.md leading with Proximo's own sharp edges). His last act opened the cages, holding the wooden sword of his own freedom. A tool should hope to end that well.

"Win the crowd and you will win your freedom."

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 Opus 4.8 built the trust pillars and the original tool surface and has carried the work since; Claude Fable 5 ran the 101-agent release audit and the first publish. Every commit carries its co-author trailer.

---

"Are you not entertained?" — stars, issues, and sparring partners welcome. Strength and honor. ⚔️