Four Surfaces

Four Surfaces

Proximo covers the whole Proxmox ecosystem through one control plane — the same trust spine, the same audit ledger, the same plan-before-mutate discipline, whichever surface a tool touches.

Surface	What it manages	Auth
PVE — Virtual Environment	Guests (VM/LXC), storage, SDN, firewall, ACLs/roles/realms, HA, backups, cluster, container exec	Scoped API token
PBS — Backup Server	Datastores, sync/verify/prune jobs, namespaces, remotes, traffic control, GC	Scoped API token
PMG — Mail Gateway	Domains, rule database, quarantine, statistics, transport, who/what/when object groups	Ticket-based login
PDM — Datacenter Manager	Cross-datacenter resource views and status (read-oriented federation)	Scoped API token

The governance/dangerous plane — firewall, SDN, ACLs, roles, realms, PBS writes — is exposed to the agent, over MCP, every operation carrying PLAN + PROVE + UNDO where applicable. That combination is the differentiator: coverage of the plane most servers keep off the agent surface, wrapped in trust by construction rather than a bare confirm.

One instance, many boxes (multi-target)

A single Proximo instance can reach many Proxmox boxes — internal or external — via a target registry. Each tool call takes an optional proximo_target= naming which box to act on; the default target is unchanged when it's omitted. Every target carries its own credentials (by reference, never inlined), its own TLS settings, and its own Certificate Pinning.

See Configuration for the registry format.

Scoping the surface you expose

PROXIMO_SURFACES (e.g. pve,pbs) registers only the planes you name — the rest never load into your MCP client's context. Handy when you only use one or two surfaces and want to keep the tool list (and the attack surface) tight. It's context hygiene, not an authorization control; the token's ACL is still the real boundary.

Honest maturity note

The trust spine and the core mutate cycle are live-proven against real hardware. Breadth is wide, but a portion of the full tool surface still runs against mocks for shape, not live behavior — the by-hand live-smoke proofs are a separate harness, not the test count. Check CHANGELOG.md for what's proven in the version you installed.