Potencia tu agente
El comando propio del publicador. No es un endpoint de PlugMCP.
Host a copy with our keys and logs.
uvx proximo-proxmox==0.52.0Claude Code no tiene enlace de instalación para un comando local. Copia el comando de abajo y ejecútalo en una terminal.
claude mcp add john-broadway-proximo -- uvx proximo-proxmox==0.52.0Ejecútalo en una terminal.
{ "mcpServers": { "john-broadway-proximo": { "command": "uvx", "args": [ "proximo-proxmox==0.52.0" ] } }}claude_desktop_config.json
¿URL remota o un comando en tu máquina? En qué se diferencian las dos instalaciones
Ejecutar en PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDel publicador
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.
The Proxmox MCP you can hand the keys. All four products: PVE, PBS, PMG, PDM.
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.
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.
# 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.
// 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 · more install paths: Install & run.
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 spine has six pillars. Four stand by default:
Two are yours 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 doctor reports the spine: which pillars stand, which sockets are empty, and exactly how to fill them. Four more controls ship off until configured: ARM (a mutation runs only while the served token is the write token), a FORBID/RATE ENVELOPE, TAINT (the prompt-injection mitigation), and PRINCIPAL (who-asked attribution). Scope and lease are not Proximo's any more: the write token's own ACL is the scope and its own expire is the lease, both enforced by Proxmox, and proximo mint prints the commands that make such a token. What each control defends against: SECURITY.md.
Honesty note (load-bearing): risk ratings are an advisory 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.
The record defends itself:
Those backends are deliberately boring. Anyone can call them. The product is the trust layer over them.
Six tools, every address. The vendor publishes the API; Proximo serves it whole and governs each address by what it is: 1,804 published addresses across the four products, 884 reads, 785 mutations open to an armed operator each with an authored blast-radius tier, 32 opened by an operator's switch (guest agent, container and node shell), 5 on the download lane, 20 held on purpose with a sentence, 78 excluded as not JSON calls. The record is generated from the vendor's own schema and a stale copy fails the suite: docs/arena.md.
Where an operator actually starts, in the six-tool grammar:
The six tools with typed inputs: docs/TOOLS.md · the walkthrough: docs/SETUP.md.
The core alone, no model in the loop: the same install ships proximo-core pve GET /nodes/pve1/status (or --plan on any address: the verdict and the published schema, touching nothing), and the estate memory behind proximo-core learn | where 105 | uses local | changed 24h: what the governed reads have seen, answered from one file beside the ledger, no model, no network. Its import closure is httpx and nothing else (measured by a test); every published address on all four products; the same arm gate, tiers and audit ledger as the MCP door. The core has its own network doors, each the 0.44 face's perimeter with the core behind it: proximo-mcp-http (MCP over streamable HTTP), proximo-http (REST, POST /tools/{name} with an OpenAPI document) and proximo-a2a (an Agent2Agent card whose skills are the six tools).
📦
0.50.0: on PyPI, GitHub, and GHCR (signed multi-arch image).New in 0.50.0 (the estate memory is back). Proximo keeps what its governed reads have seen in one SQLite file beside the ledger, derived and never proof, and answers
proximo-core learn | where 105 | uses local | changed 24hwith no model and no network: kind, node, status, how old the answer is, and the published path that reads the thing live. A thing it has not seen is "not in memory", never "does not exist"; only a whole, unfiltered list read may mark a thing gone. The file is the operator's alone (0600, never tightened), bounded, and every answer is a row on the ledger.PROXIMO_MEMORY=0opts out and creates nothing.Recent: 0.49.1 routed shell calls across a cluster by target and node (from PR #107) and gave the operator the shell wait; 0.49.0 put every model-facing answer under a hard byte ceiling at one exit on every door, and made a rollback take a safety snapshot first. 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 core, MCP door included
# 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 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 is scoped by its own fail-closed allowlist.Smallest footprint by construction: the door advertises six schemas and nothing else. Measured on this release,
tools/listover stdio is 5,544 bytes on the wire (about 1,400 tokens at the four-bytes-a-token heuristic; 1,568 as a stock 1.5B's chat template renders it, counted by its server), and that is the whole cost of connecting; the estate behind it is searched, not loaded. There is nothing to scope: a plane you have not configured is simply not reachable, a plane you have is reachable whole, and the gates do not shrink with the doorway. PLAN and PROVE apply to every address however small the model.
The network faces (experimental, opt-in): proximo-a2a speaks Agent2Agent. proximo-http serves plain HTTP + generated /openapi.json for no-code clients. proximo-mcp-http serves MCP 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. LXC on your Proxmox host, one line: on the PVE node as root, bash -c "$(curl -fsSL https://raw.githubusercontent.com/john-broadway/proximo/main/packaging/lxc/ct/proximo.sh)" builds a Debian 13 container running proximo-mcp-http with Proximo from PyPI, its own service user, and a minted bearer on port 41243. Community-scripts engine (MIT) pointed at Proximo's own tree, their telemetry off; the same line inside the container updates it. Details: docs/SETUP.md, files: packaging/lxc/.
All three serve the full surface through the same spine 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.
One container is the demo. A cluster is the point.
proximo_read pve /cluster/resources: every VM, node, storage pool, SDN object, as lean rows with a total.Many boxes, one Proximo: register remotes in a TOML file (secrets by reference, never inlined), point PROXIMO_TARGETS at it, aim a call with target="edge-pve" (the shell door: --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.
learn, where, uses, changed on the core door with no model and no network; derived, never
proof; owner-only and bounded; three adversarial rounds closed on the branch. 4,323 tests.
Every release before it (every pillar, every redteam, every fix) lives in CHANGELOG.md.The numbers, honestly: six tools over 1,804 published addresses, governed by what each address is (its method decides read or write, total by construction; the blast-radius tier is the one human-authored column, and an untiered mutation is refused, armed or not). 4,323 in-process tests (ruff + pyright clean) pin the engine, the six pillars, the doors and the records, and a gate round neuters each pillar's gate one at a time and asks the suite to notice. This workspace administers its own Proxmox estate through Proximo daily (dogfood).
Proven live (not mocks): the governed path end to end against a real PVE 9 node through this door, plans reading the live target, receipts on the keyed chain, before-state captures and their restore. The 0.44 wrappers' live record (a 3-node cluster, PBS, PMG, PDM, a real cross-datacenter move) stays in CHANGELOG.md where it was earned; it is not re-claimed for the core.
Not yet proven — said plainly: a small local model finishing a whole task through this door. Measured and driven on 0.45: a stock 1.5B behind llama.cpp with a 4,096-token context the server enforces, against a real PVE node, read-only. Its calls landed and the door's refusals named the fix each time (an invented field, the real ones listed); the prompt peaked at 3,074 tokens; the model did not finish the task, it invented a number. The window holds; a 1.5B does not. Hardware-watchdog fencing (needs physical iTCO/IPMI), and behavior at production scale. The 20 held addresses are never fired: refused by sentence, by design, not a gap.
Apache-2.0, chosen for the patent grant that suits infrastructure tooling. Full text in LICENSE.
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. ⚔️
The Proxmox MCP you can hand the keys. All four products: PVE, PBS, PMG, PDM.
{ "mcpServers": { "john-broadway-proximo": { "command": "uvx", "args": [ "proximo-proxmox==0.52.0" ] } }}Herramientas
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
Este registro no indica ninguna variable de entorno obligatoria.
Proximo se ejecuta localmente por stdio.
Última comprobación: 2026-10-28. The Proxmox MCP you can hand the keys. All four products: PVE, PBS, PMG, PDM.