john-broadway/proximo

*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**: see the blast radius first. Every move is **proven**: a tamper-evident record. And **undoable wherever the platform gives us a primitive**: a config change hands back the exact prior state, and 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 runs a diagnostic *inside* the container to find out.
If there's a fix, it shows you the plan before it touches anything. Takes a snapshot first if you ask it to, and won't run if it can't. Applies. 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.**
**Don't take our word for any of it. Verify it yourself.**
Verify in 60 seconds : three receipts, no trust required
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
Claude Code, one line:
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):
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
The spine has six pillars. Four stand 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. |