Proximo

by john-broadway

447 downloads
Not rated
GitHub Website

About

Proxmox VE, Backup Server, Mail Gateway, and Datacenter Manager on one audited MCP surface — 365 tools; every mutation dry-run planned, snapshot-backed undoable where the platform allows, and recorded in a tamper-evident audit ledger.

Details

Author
john-broadway
Downloads
447
Categories
Cloud Service, Infrastructure, AI, API

- Integrates Proxmox VE, Backup Server, and Mail Gateway
- Audited trust core for planning, proving, undoing, diagnosing
- 900 tools available
- Supports both MCP and A2A protocols

Proximo — the Proxmox MCP you can hand the keys

Proxmox VE, Backup Server, Mail Gateway, and Datacenter Manager on one audited MCP surface — 365 tools; every mutation dry-run planned, snapshot-backed undoable where the platform allows, and recorded in a tamper-evident audit ledger.

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

Named for Proximo, the lanista ofGladiator.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 isplanned: see the blast radius first. Every move isproven: a tamper-evident record. Andundoable 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.

Ask, in plain English:"why is ct 105 thrashing?"An AI agent pulls node and guest status, tails the logs, and runs a diagnosticinsidethe 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'sProximo vs. handing an LLM your root token and hoping.

Don't take our word for any of it.Verify it yourself.

# 1. The tool count is real. Ask the server itself, cold (=> 906). # (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 is inVERIFY.md: forge a ledger byte and watchverify()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 entersone governed dispatchand crosses thesame trust spine; the token floor beneath it all is enforced by Proxmox itself.
Watch it hold in the
Demo.

// 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_NODE": "your-node", "PROXIMO_TOKEN_PATH": "/path/to/token-file" // USER@REALM!TOKENID=SECRET, by reference, never inlined } } } }
claude mcp add proximo --env PROXIMO_API_BASE_URL=https://your-pve:8006/api2/json \ --env PROXIMO_NODE=your-node --env PROXIMO_TOKEN_PATH=/path/to/token-file -- uvx proximo-proxmox

Both prompt for the token filepath; the secret never lands in client config. No token yet?uvx proximo-proxmox mintprints the least-privilege runbook.

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

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

The Proxmox MCP landscape is split.API-based serversmanage nodes and VMs but structurallycannotrun a command inside an LXC: the REST API has no exec endpoint.SSH-based serverscan, through broad shell access with little scoping.

Proximo builds the principled whole. Both halves, one audited surface, least-privilege.Trust by construction:

(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:

Two areyours to raise, by design, off until their state paths exist, because both are only worth having if those paths sit outside the agent's reach. A pillar Proximo raised for you would be a pillar the agent could lower for itself:

proximo doctorreports the spine: which pillars stand, which sockets are empty, and exactly how to fill them. Five more controls ship off until configured: an arm-LEASE, an arm-timeSCOPE, a FORBID/RATEENVELOPE,TAINT(the prompt-injection mitigation), andPRINCIPAL(who-asked attribution). What each one defends against:SECURITY.md.

Honesty note (load-bearing):risk ratings are anadvisory heuristic, not a sandbox —LOWmeans "no state change,"not"safe," and the absence of aHIGHflag 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.

Three agent moves land in the keyed 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. Real code, real crypto, nothing staged, recorded on 0.30.0. Run it yourself anywhere:scripts/demo/hand_the_keys.py(needs only the pip package) · against your own host:--live· verify by hand:VERIFY.md.

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

906 tools is an estate, not a starting point, and you only carry the part you use. Since 0.30 the floor IS the default: a bare install serves the search-and-call facade (~1,449 tokens of context) with every tool this box serves still callable; one domain likepve.guestsruns ~9,123, a whole plane ~97,432,PROXIMO_TOOLSETS=catalogthe classic auto-scoped catalog.The estate is 906. The doorway is yours to size.Coverage and context stopped being the same number.

Every tool with typed inputs:docs/TOOLS.md· sizing the surface to your model:docs/SETUP.md.

📦0.35.0: onPyPI,GitHub, andGHCR(signed multi-arch image).

New in 0.35.0 (the sibling planes, on measured vocabulary).pbs_tasks_list,pmg_tasks_listandpdm_tasks_listreturn the same{returned, by_outcome, tasks}envelope PVE got in 0.34.0, classified server-side from each raw row. Every plane's vocabulary was live-probed first, and they disagree: PBS and PDM name their columnsworker_type/worker_idwhere PVE and PMG saytype/id, so the lean field set is per plane. PMG never produced a failing row across four honest attempts, so its vocabulary is documented as unobserved rather than known. Details in the CHANGELOG.

Recent:0.34.0gavepve_tasks_listthat envelope first, and put one task-outcome classifier repo-wide.

Proximo runson 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: pip install "proximo-proxmox[mcp-http]" + the optional MCP-over-streamable-HTTP 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 commandproximo, with thePROXIMO_env vars; seepackaging/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 is scoped by its own fail-closed allowlist.

Smallest footprint by design:you don't have to load the whole estate: what a boxservesis autoscoped to what it configures. A PBS-only box gets that plane's tools plus the always-on audit trail;PROXIMO_SURFACES=pve,execscopes the searchable catalog to that pair (316 tools); a typo'd surface refuses startup rather than serving a surprise. Surfaces choosewhich planes are searchable, neverhow many schemas load; the doorway stays the default unless you name another withPROXIMO_TOOLSETS. Scoping is context hygiene, not an authorization control: it changes what is advertised, never what a token is allowed to do. The default doorway (dynamic mode) keeps three search-and-call tools resident plus the two ledger tools (audit_verifyproves the chain,audit_entriesreads who did what) andproximo_recallwhile estate memory is on (the default;PROXIMO_MEMORY=0opts out), with the full catalog reachable by name. That narrowing is guarded at every entry point (0.27.0 closed a path where an opt-in flag could silently cut the registry to 5 tools), and the gates don't shrink with the doorway: PLAN and PROVE apply however small the visible surface gets.

The network faces (experimental, opt-in):proximo-a2aspeaks Agent2Agent.proximo-httpserves plain HTTP + generated/openapi.jsonfor no-code clients.proximo-mcp-httpservesMCP itself over Streamable HTTP(the SDK's native transport) for networked MCP clients: no third-party stdio→HTTP bridge, so the perimeter stays Proximo's.

All three serve the full surface through thesame spineas 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.

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, auditedagent earns its keep.

Many boxes, one Proximo:register remotes in a TOML file (secrets by reference, never inlined), pointPROXIMO_TARGETSat it, aim any tool withproximo_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.

- 🩸0.35.0:the sibling planes, on measured vocabulary.PBS, PMG and PDM task lists return the classified envelope PVE got in 0.34.0. Each plane was live-probed before its classifier existed, so the lean field set is per plane and asking for the wrong plane's column names is refused with the available ones listed. Where a plane refused to fail (PMG, four honest attempts), the docs say unobserved rather than known.

Every release before it (every pillar, every redteam, every fix) lives inCHANGELOG.md.

The numbers, honestly:906 MCP tools, proved in two deliberate layers.11,000+ in-process tests(ruff + pyright clean) pin every tool's shape. A separatelive-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). Theblast-radius enginecarries 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 (SDNapply, etc.) are deliberately never fired live: proven by plan, held back by design, not a gap. Per-surface detail:CHANGELOG.md.

Apache-2.0, chosen for the patent grant that suits infrastructure tooling. Full text inLICENSE.

Built byJohn BroadwaywithClaudeandMaude: a human-AI partnership, and the first thing we made on this box to give away to the world.Claude Opus 4.8built the trust pillars and the original tool surface and has carried the work since;Claude Fable 5ran 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.⚔️

Navigate your Aiven projects and interact with the PostgreSQL®, Apache Kafka®, ClickHouse® and OpenSearch® services

Yunxiao MCP Server provides AI assistants with the ability to interact with the Yunxiao platform.

Get prescriptive CDK advice, explain CDK Nag rules, check suppressions, generate Bedrock Agent schemas, and discover AWS Solutions Constructs patterns.

This AWS Labs Model Context Protocol (MCP) server for CloudTrail enables your AI agents to query AWS account activity for security investigations, compliance auditing, and operational troubleshooting.

Core AWS MCP server providing prompt understanding and server management capabilities.

Analyze CDK projects to identify AWS services used and get pricing information from AWS pricing webpages and API.

Query and analyze your Axiom logs, traces, and all other event data in natural language

Manage and interact with Microsoft Azure services.

Bastion: External Attack Surface Monitoring

Ask your AI assistant about your attack surface: run scans, catch expiring certificates and domains, triage findings, and generate reports.

Agent-ready global image CDN that AI agents can install and operate through MCP.

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.