Proximo — the governed client for Proxmox

Enter the ludus ↗ · Quickstart · Setup · Trust layer · Demo · Tools · Install · Security · Docs

*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. He answered for every move in the arena. A lanista, not a jailer. The Spaniard earns his name by conduct, on the record, and the helmet comes off: truth said plainly, at cost. 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."*

The others make you pick: a read-only toy, or full keys and pray. Proximo won't. Every dangerous move is planned: the verdict, the live target and the change, before anything runs. Every move is proven: a tamper-evident record. And undoable wherever the platform gives us a primitive: a mutation captures the record it is about to change and puts it back through the vendor's own write; a risky in-container command can take a snapshot first, and refuses to run if it can't.

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.

What it does

Ask, in plain English: *"why is ct 105 thrashing?"* An AI agent pulls node and guest status, tails the logs, and (if you opened that lane) runs a diagnostic *inside* the container to find out.

If there's a fix, it shows you the plan before it touches anything: the verdict, the target as it stands, the exact change. Takes a snapshot first if you ask it to, and won't run if it can't. Applies. Hands you a keyed receipt of exactly what changed, with the before-state captured so it can be put back.

It does all of that with six tools, over every address the four Proxmox products publish. No wrappers, no catalog to page through, no tool per endpoint: find the address, plan it, read or call it, and prove the record. The whole surface fits a small local model's window.

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.

Don't take our word for any of it. [Verify it yourself](VERIFY.md).

Verify in 60 seconds : three receipts, no trust required

# 1. The tool count is real. Ask the door itself, cold (=> 6).

(in a clone of this repo, after uv sync)

uv run python -c "import asyncio; from proximo.core.doors.mcp import build_server; \ print(len(asyncio.run(build_server().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 is in VERIFY.md: forge a ledger byte and watch verify() refuse, grep the outbound surface for phone-home (there is none). 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 in the Demo .

Quickstart

// your MCP client config (Claude Desktop / Claude Code / Cursor / …)

{ "mcpServers": { "proximo": { "command": "uvx", "args": ["proximo-proxmox"], "timeout": 60, // startup is ~3.5s; a 3s client default drops the server silently "env": { "PROXIMO_API_BASE_URL": "https://your-pve:8006/api2/json", "PROXIMO_TOKEN_PATH": "/path/to/token-file" // USER@REALM!TOKENID=SECRET, by reference, never inlined } } } }

Claude Code, one line:

claude mcp add proximo --env PROXIMO_API_BASE_URL=https://your-pve:8006/api2/json \

--env PROXIMO_TOKEN_PATH=/path/to/token-file -- uvx proximo-proxmox

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 pve 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](docs/SETUP.md) · more install paths: Install & run.

Why Proximo exists

Everything that touches a Proxmox product is a call: the web UI, pct and qm on a host, curl against the API, an agent's tool. Most of those calls leave no plan behind them, no receipt, and no way back. Proximo is the one client that governs the call before it runs, records it, and can put the record back, whichever door it came in by. Trust by construction:

Proximo is a community project, standing on its own. MCP, A2A, REST and a shell with no model in the loop are its doors; the governance is the product.

The trust layer: what makes Proximo different

The spine has six pillars. Four stand by default:

Two are **yours to raise, by d