Proximo — the governed client for Proxmox

io.github.john-broadway由 GitHub 帳號 john-broadway 發布v0.52.0更新於 Nov 7, 2026

The governed client for Proxmox (PVE, PBS, PMG, PDM): plans, keeps the receipts, puts things back.

概覽

AI 產生的概覽

受治理的 Proxmox 用戶端:讓助理透過六個工具檢視與變更 PVE、PBS、PMG 與 PDM,並具備計畫紀錄、稽核帳本與復原能力。

可以做什麼
  • 依描述尋找四個 Proxmox 產品所發布的 API 位址
  • 讀取叢集、節點、虛擬機、儲存與備份狀態,並對異常容器執行唯讀診斷
  • 在變更前產生計畫,呈現判定、即時目標、確切變更與影響範圍
  • 確認後套用計畫變更,或透過廠商自身的寫入介面還原已擷取的變更前狀態
  • 驗證以金鑰簽署、雜湊鏈結的稽核帳本,並預檢權杖或設定
  • 在容器或節點內執行需明確開啟的 shell 通道,受失敗即拒絕的允許清單約束
適用情境
適合讓助理實際操作 Proxmox 環境(節點、虛擬機、容器、備份、郵件閘道),而不只是讀取,且希望每次變更都先預覽、留有紀錄並可回復。多節點叢集效益最大;單一節點手動處理通常更快。
執行需求
透過 uvx 或 pip 安裝 proximo-proxmox(Python)在本機執行,也可使用簽章容器映像。需要 Proxmox API 基礎位址,以及以參照方式(權杖檔案路徑)提供的受限 API 權杖,並能連線至 Proxmox 端點。選用設定可開啟 shell 通道、核准、熔斷開關與多目標遠端。
安裝前請注意
它會變更真實基礎設施:確認後變更即執行,風險評級僅為參考性啟發式判斷,並非沙箱。應先授予最小權限的唯讀權杖,再逐步放寬。權杖檔案含密鑰,不要寫入用戶端設定。選用的 exec 與 guest-agent 通道接近 root 權限,必須明確開啟。核准與熔斷控制預設關閉,需將相關路徑設定在助理無法觸及的位置。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Proximo — the governed client for Proxmox,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

[Proximo]

[CI] [CodeQL] [Release] [PyPI] [Python 3.12+] [License AGPL-3.0-or-later]

[OpenSSF Scorecard] [OpenSSF Best Practices] [Glama score] [LobeHub — grade, tools, prompts]

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 in 60 seconds: three receipts, no trust required
bash
# 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.


[Proximo architecture: MCP clients (stdio and Streamable HTTP), A2A, and HTTP/OpenAPI clients all land on one governed spine, pass the six-pillar trust spine (PLAN, PROVE, UNDO, DIAGNOSE standing by default; CONSENT and CONTAIN yours to raise), sit on the Proxmox-enforced token floor, and reach four products — PVE, PBS, PMG, PDM]

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

jsonc
// 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:

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

[Install in VS Code] [Install in Cursor]

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.

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:

A call on its ownThrough Proximo
Before it runsnothinga plan, recorded first: the verdict, the live target, the exact change, the blast radius
Record of what happenedapp logs, editablekeyed, hash-chained ledger; audit_verify catches edits, reordering and, against a pinned head, truncation
Undoby hand, if you kept notesthe record captured first, restored through the vendor's own write
Command inside an LXCbroad SSHopt-in, fail-closed allowlist, judged like any mutation
Products coveredone at a timePVE + PBS + PMG + PDM, one governed plane
Verify the artifact you runvariessigned image · PyPI provenance · SBOM · Scorecard

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:

ControlWhat it does
PLANEvery 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.
PROVEKeyed (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.
UNDOOne rule: every mutation with a GET twin captures the record before it runs, and the receipt carries an undo.id; the restore is the vendor's own write at the same path, with the captured record, as a governed mutation (planned, armed, receipted, itself undoable). A container command can take a snapshot first and then fail closed if it can't. Where the vendor publishes no write to put a record back (a delete, a collection, a path with no PUT) the answer is a sentence, never a guessed reverse call.
DIAGNOSERead-only evidence battery + node health → advisory flags that surface incompleteness too, so an empty list never reads as a false clean bill.

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:

Pillar (off until configured)What it holds
CONSENTIndependent, out-of-band approval per plan: an agent (compromised, confused, or steered by injected text) cannot confirm its own mutation. Grants live in a directory only you write (PROXIMO_CONSENT_DIR), expire on a TTL, and never clear a taint.
CONTAINThe kill-switch: one trip file halts every mutation immediately, mid-incident, no redeploy and no restart. Checked fresh on every mutation; fails closed. Put the trip path where only you can write (PROXIMO_CONTAIN_TRIP_PATH).

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 — 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.

Demo

The record defends itself:

[Hand-the-keys demo: three agent moves land in the keyed hash-chained ledger and audit_verify answers ok=True keyed=True; an in-place edit breaks the chain at the exact line (ok=False); a truncation that fools the forward walk is caught by the pinned head]

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. Forge a byte yourself and watch the chain refuse: VERIFY.md, section 2.

Surfaces & tools: one control plane

SurfaceBackendFor
Proxmox VEREST API + scoped tokennode/guest lifecycle, storage, SDN, identity, HA, firewall
Proxmox Backup ServerREST API + scoped tokendatastores, namespaces, snapshots, sync, GC, verify, tape
Proxmox Mail GatewayTicket authmail flow, quarantine, filtering rules, domains, services
Proxmox Datacenter ManagerAPI tokenfederated fleet: reads plus governed control (power/snapshot/migrate, dry-run-first)
Container and node shellssh → pct exec, a fixed host batteryrun-command-in-container, psql, log tailing, a host health read: what the API structurally can't do. Opt-in lanes, each behind its own switch and allowlist, judged like any mutation

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:

You want to…SayWorth knowing
Find the addressproximo_find "list datastores"verbs pick the method; the vendor's own words match
See the whole cluster at onceproximo_read pve /cluster/resourceslean rows (names, states, ids) and a total; fields=all for the vendor's rows
Find out why a container is sickproximo_read pve /nodes/{node}/lxc/{vmid} diagnose=truethe battery: status, storage, failed tasks, and the shell probes if that lane is open
Power / lifecycle, any mutationproximo_plan, then proximo_call … confirm=truethe plan reads the target first; nothing moves without confirm=true, an arm and a tier
Put it backproximo_call pve undo <undo.id>the captured record, written back through the vendor's own PUT
Preflight a token / configproximo doctorrun this before wiring an agent
Prove the record wasn't touchedaudit_verifyon every door, always

The six tools with typed inputs: docs/TOOLS.md · the walkthrough: docs/SETUP.md.

Install & run

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.52.0: on PyPI, GitHub, and GHCR (signed multi-arch image).

New in 0.52.0 (the ticket is the arm; the vendor's door answers on every product). A person arms by logging in: proximo-core arm prompts in a terminal of their own and serves the vendor's ticket, dead on its own at the vendor's two hours; a job with nobody at a keyboard keeps its token pair. A plan now says what the vendor's own permission check would answer the served credential on PVE, PBS and PDM, read from the vendor's rule and the vendor's own account of what the credential holds with nothing inferred between them: may, never with the missing privilege named, unknown, or in words (PMG names the roles its rule wants). The vendor's digest is the write lock: a plan carries the record's digest into the write, so a record that moved since the plan is the vendor's own 400. Proved in the lab under exactly the credentials proximo mint installs. SECURITY.md says what a ticket is: the user's whole ACL, and a user may mint its own tokens.

Recent: 0.51.0 moved the license to AGPL-3.0-or-later and kept a read under its cap; 0.50.1 let the operator raise the exit ceiling (PROXIMO_EXIT_MAX_BYTES, up to 64 KiB, from alexdelprete's measurements on #114). 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/list over 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.

At scale

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

  • The whole cluster in one call. proximo_read pve /cluster/resources: every VM, node, storage pool, SDN object, as lean rows with a total.
  • 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 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.

Status: the arena record

  • 🩸 0.52.0: the ticket is the arm; the vendor's door answers on every product. A person arms by login, the vendor's two hours; a plan on PVE, PBS and PDM says what the vendor's own door would answer the served credential, proved in the lab under the credentials proximo mint installs; the vendor's digest is the write lock. One whole-diff lens per lane, folded by reading the vendor's source. 5,164 tests.

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). 5,164 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.

Documentation

DocumentWhat it answers
SetupToken-first walkthrough: mint a least-privilege token, verify it, widen deliberately.
The JunctionWhy Proximo exists: two roots on two planes, and the door that governs both lanes.
VerifyEvery trust claim paired with the command that proves it. Run them cold.
SecurityThe two-deployment trust model, every control, what each honestly holds, reporting.
Threat modelWhat Proximo defends against, what it doesn't, where the boundaries sit.
ToolsThe six tools, typed inputs: find, plan, read, call, and the two ledger reads.
AgentsThe page written for the agent itself: Proximo's sharp edges, stated first.
Known issuesWhat's broken or odd right now, said plainly.
ContributingDev setup, the CI gates, what a PR is expected to keep intact.
ChangelogEvery release, every redteam, every fix: the full build history.

License

AGPL-3.0-or-later, so nobody can take it closed. Full text in LICENSE. Every release through 0.50.1 was Apache-2.0 and stays Apache-2.0. The code Alessandro Del Prete (@alexdelprete) and RavenLiao contributed came in under Apache-2.0; their copyright stays theirs, and those portions remain available under Apache-2.0 as well (LICENSES/Apache-2.0.txt).

Credits

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. Outside contributors: Alessandro Del Prete (@alexdelprete), MCP over Streamable HTTP; RavenLiao (@RavenLiao), PVE SSH routed by target and node.


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

來源:README.md,提交 bb3c9d2

工具

0
SourceWeft 曾在隔離沙箱中以無憑證方式啟動該軟體包一次,以列出其工具,但未能完成:軟體包安裝失敗。

版本歷史

14
  1. v0.52.0最新Nov 7, 2026
  2. v0.51.0Nov 3, 2026
  3. v0.50.1Oct 29, 2026
  4. v0.48.1Oct 25, 2026
  5. v0.46.2Oct 22, 2026
  6. v0.46.1Oct 21, 2026
  7. v0.46.0Oct 20, 2026
  8. v0.45.1Oct 19, 2026
  9. v0.45.0Oct 19, 2026
  10. v0.44.2Oct 10, 2026
  11. v0.44.1Oct 3, 2026
  12. v0.44.0Sep 21, 2026
  13. v0.42.0Sep 17, 2026
  14. v0.41.1Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分