Hi all — sharing an open-source side project for feedback from people who actually run Proxmox in anger. It's a community project, not affiliated with Proxmox, and this isn't a support request — I'm after criticism of the approach.
What it is: Proximo is a small server that lets an AI agent (or any MCP/A2A client) manage a PVE cluster through the REST API with a scoped API token. It does not touch the hypervisor directly and is API-only by default. Safety was the design priority, because handing an LLM access to a hypervisor is obviously risky.
What that looks like in practice:
- Dry-run before every mutation. Each change first returns a preview: the exact operation, the guest's current state, and a computed "blast radius." Before deleting/disabling a storage, for instance, it reads the cluster and lists the specific guests that would lose a disk (and which won't boot vs. just degrade). The mutation can't run without that plan having been generated first.
- Tamper-evident audit log (hash-chained), kept locally — a verifiable record of what was planned and confirmed.
- Auto-snapshot before risky changes, with one-call rollback, wherever the storage supports snapshots.
- Scoped token, least privilege. I run it day-to-day against a PVEAuditor-style read-only token; mutations are refused at the API level unless the token is actually granted them. The token is never logged.
- In-container exec is opt-in and loud. The REST API has no exec-in-LXC endpoint, so that path goes over ssh -> pct exec; it's off by default, gated by a fail-closed CTID allowlist, and it warns that it grants near-root.
Maturity — stated plainly: brand new (v0.6.0), no real-world adoption yet. 145 tools and a large test suite, but a good portion of that surface still runs against mocks. What I've exercised against a real PVE 9.2 API (a single node plus a nested 3-node test cluster): the core lifecycle + the governance/dangerous plane (roles/groups/users/ACLs, storage, SDN/network, realms), offline guest migration, and HA-rule config — full create/read/delete cycles. I have not validated real HA fencing (needs a hardware watchdog), online live-migration (needs shared storage), or anything at production scale. SDN/network apply I deliberately never fire on a live host — it's unrecoverable. I'm also not claiming it's the first or only safety-minded Proxmox tool; there are others with real trust mechanisms. This is just the approach I landed on and would like critiqued.
Install (runs on your machine, on demand — no daemon, no open port):
uvx proximo-proxmox (or: pip install proximo-proxmox)
Source + docs (Apache-2.0): https://github.com/john-broadway/proximo
What I'd most value from this community: where does the trust model fall down on a real cluster? Are the blast-radius assumptions wrong for setups I haven't seen (shared storage, unusual boot configs, HA edge cases)? Is the token/permission posture sane? I'd rather hear it here than after someone points it at production.
(Full disclosure, since it's relevant: it's a human+AI project — I drove the design; an AI coding partner did much of the implementation, credited per-commit in the repo. Noting it because some folks rightly want to know.)
Thanks for any time you spend kicking the tires.
What it is: Proximo is a small server that lets an AI agent (or any MCP/A2A client) manage a PVE cluster through the REST API with a scoped API token. It does not touch the hypervisor directly and is API-only by default. Safety was the design priority, because handing an LLM access to a hypervisor is obviously risky.
What that looks like in practice:
- Dry-run before every mutation. Each change first returns a preview: the exact operation, the guest's current state, and a computed "blast radius." Before deleting/disabling a storage, for instance, it reads the cluster and lists the specific guests that would lose a disk (and which won't boot vs. just degrade). The mutation can't run without that plan having been generated first.
- Tamper-evident audit log (hash-chained), kept locally — a verifiable record of what was planned and confirmed.
- Auto-snapshot before risky changes, with one-call rollback, wherever the storage supports snapshots.
- Scoped token, least privilege. I run it day-to-day against a PVEAuditor-style read-only token; mutations are refused at the API level unless the token is actually granted them. The token is never logged.
- In-container exec is opt-in and loud. The REST API has no exec-in-LXC endpoint, so that path goes over ssh -> pct exec; it's off by default, gated by a fail-closed CTID allowlist, and it warns that it grants near-root.
Maturity — stated plainly: brand new (v0.6.0), no real-world adoption yet. 145 tools and a large test suite, but a good portion of that surface still runs against mocks. What I've exercised against a real PVE 9.2 API (a single node plus a nested 3-node test cluster): the core lifecycle + the governance/dangerous plane (roles/groups/users/ACLs, storage, SDN/network, realms), offline guest migration, and HA-rule config — full create/read/delete cycles. I have not validated real HA fencing (needs a hardware watchdog), online live-migration (needs shared storage), or anything at production scale. SDN/network apply I deliberately never fire on a live host — it's unrecoverable. I'm also not claiming it's the first or only safety-minded Proxmox tool; there are others with real trust mechanisms. This is just the approach I landed on and would like critiqued.
Install (runs on your machine, on demand — no daemon, no open port):
uvx proximo-proxmox (or: pip install proximo-proxmox)
Source + docs (Apache-2.0): https://github.com/john-broadway/proximo
What I'd most value from this community: where does the trust model fall down on a real cluster? Are the blast-radius assumptions wrong for setups I haven't seen (shared storage, unusual boot configs, HA edge cases)? Is the token/permission posture sane? I'd rather hear it here than after someone points it at production.
(Full disclosure, since it's relevant: it's a human+AI project — I drove the design; an AI coding partner did much of the implementation, credited per-commit in the repo. Noting it because some folks rightly want to know.)
Thanks for any time you spend kicking the tires.
