CLI, TUI, MCP server (stdio + Streamable HTTP/SSE with server-sent cluster-event notifications), and a unified `daemon serve` mode in the same executable. Same risk gate, same HITL gate, same API client. The TUI is for interactive operations; the CLI is the same operations, scriptable, JSON-friendly, and CI-ready; the MCP surface is a deterministic 25-tool registry for LLM agents where destructive tools are fail-closed by default — refused unless a matching policy routes them through the HITL gate — and the HTTP transport binds loopback-only unless an `mcp_token` is set; the daemon folds alerts + HITL listener + interval scheduler into one SIGTERM-clean process.
No agent on the cluster
Direct REST against PVE (token or password) and PBS (token only), with typed error categories so callers match on the failure shape instead of grepping prose. SSH only for the paths PVE never exposed over REST — patch apply, full effective-permissions, per-guest interactive sessions, per-node journalctl tailing, GPU/IOMMU readiness probing.
Eight-stage commit gate, no skip flags
secret-shape scan, cargo fmt, cargo clippy --all-targets at deny tier, cargo audit against a pinned advisory policy, cargo deny check (license whitelist + banned crates + crates.io-only sources + wildcard ban), the full test suite (745 lib tests + 478 integration tests including ~25 proptest properties at 256 random cases each, ~6 400 invariant checks total), 67 read-only probes against a live cluster, and a full mutation lifecycle covering LXC, cluster-level CRUD across 8 of the 10 state families, QEMU, and opt-in QGA agent-required round-trips. Every commit on main passes locally and in CI.
Pre-flight risk gate plus HITL
11 risk variants — running, long-uptime, locked, HA-managed, tagged prod, active net traffic, listening on service, many snapshots, backup age warning, no backup found, deep-check skipped — refuse destructive operations on guests that look like production unless overridden explicitly. Above that, a real Telegram round-trip with deny-on-timeout for any op marked destructive by policy. The same gate fires on `state apply` for non-empty pool deletes, root-role ACL deletes, shared-storage removal, and batches ≥ 50.
GitOps loop for Proxmox
`proxxx state export` → `proxxx state diff` → `proxxx state apply` over ten state families — pools, ACL grants, cluster storage definitions, backup jobs, cluster firewall (options + aliases + IP sets + security groups), notification matchers, HA rules, HA resources, and PCI + USB passthrough device mappings. Byte-stable TOML snapshots, structural diff with exit code 2 on drift (CI-gateable), and a converge step with `--dry-run`, `--prune`, `--continue-on-error`, `--allow-risk`, and `--interactive` per-Severe stdin prompts.
Incident lockdown
`proxxx incident freeze` raises a cluster-wide write kill-switch with TTL + audit log. Every `POST`/`PUT`/`DELETE` is refused with typed `FreezeRefusal` → exit code 8 until `proxxx incident thaw` or the TTL fires. Reads keep working. Designed for the "stop the bleeding" minute.
8 stages · ~340–480 s wall time (live cluster path)
Live cluster coverage
67 read probes + 34 mutation probes per gate run
Property testing
~25 proptest properties × 256 random cases = ~6 400 invariant checks per cargo test
Mutation lifecycle
LXC create→start→snapshot→stop→delete · cluster-level CRUD across 8 of the 10 state families (pools / ACL / storage-defs / backup-jobs / firewall-cluster / notifications / HA rules / HA resources) · QEMU 9998 from alpine ISO · opt-in QGA round-trips
Binary
6–9 MB stripped depending on target · single static · no installer
proxxx does not replace the Proxmox web UI. It is built for the workflows where the web UI is slow, repetitive, or unreachable from a terminal-only context. It does not render graphical SPICE or VNC frames — those hand off to remote-viewer and the system browser. It is not a Perl rewrite — when ground truth lives in pveum, proxxx shells out, parses, and stays out of the way.
