proxxx

One binary, three callers

CLI, TUI, and MCP server 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 10-tool registry for LLM agents.

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.

Six-stage commit gate, no skip flags

cargo fmt, cargo clippy --all-targets at deny tier, cargo audit against a pinned advisory policy, the full test suite, 88 read-only probes against a live cluster, and a full mutation lifecycle covering LXC, cluster-level CRUD, 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, locked, HA-managed, tagged prod, listening on service, no recent backup — 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.

By the numbers

Surface	Today
Source	~28 KLOC Rust · ~5 KLOC tests
Quality gate	6 stages · ~80–260 s wall time
Live cluster coverage	88 read probes + full mutation lifecycle per gate run
Mutation lifecycle	LXC create→start→snapshot→stop→delete · cluster-level CRUD (pool / firewall-cluster / backup-jobs / notifications / storage-defs) · QEMU 9998 from alpine ISO · opt-in QGA round-trips
Binary	6–9 MB stripped depending on target · single static · no installer
Supply chain	`cargo audit --deny warnings` per push + nightly cron
System dependencies	0 — rustls only, no native-tls, no openssl
MCP tool registry	10 tools · SHA-256 pinned · compile-time fixed

Surface

Today

Source

~28 KLOC Rust · ~5 KLOC tests

Quality gate

6 stages · ~80–260 s wall time

Live cluster coverage

88 read probes + full mutation lifecycle per gate run

Mutation lifecycle

LXC create→start→snapshot→stop→delete · cluster-level CRUD (pool / firewall-cluster / backup-jobs / notifications / storage-defs) · QEMU 9998 from alpine ISO · opt-in QGA round-trips

Binary

6–9 MB stripped depending on target · single static · no installer

Supply chain

cargo audit --deny warnings per push + nightly cron

System dependencies

0 — rustls only, no native-tls, no openssl

MCP tool registry

10 tools · SHA-256 pinned · compile-time fixed

A taste

bash

# Read the cluster
proxxx ls nodes
proxxx ls guests --format json | jq '.[] | select(.status == "running")'
proxxx ha preview --node pve1
proxxx hw conflicts --node pve1
proxxx perms root@pam --node pve1

# Operate it (with consent)
proxxx start 100 101 102
proxxx delete 100 --yes
proxxx migrate 100 pve2 --yes
proxxx snapshot create 100 --name pre-upgrade
proxxx disk move 100 --disk scsi0 --storage ceph-rbd --yes
proxxx patch apply --reboot=auto --dry-run

# Hand off to a graphical client
proxxx ssh    100                       # interactive SSH into the guest (system ssh)
proxxx serial 100 --node pve1           # raw termproxy WebSocket
proxxx spice  100 --node pve1           # writes .vv (0600), launches remote-viewer
proxxx novnc  100 --node pve1           # opens browser to web UI's noVNC

# Drive it from an LLM
proxxx mcp serve                        # stdio JSON-RPC server
proxxx mcp tools --checksum             # registry hash for audit

What it is not

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.

Where to start

First time? Read the installation guide, then quick start.

Setting up a cluster? Configuration covers profiles, secret resolution, TLS, and HITL policies.

Wiring an LLM agent? MCP server describes the deterministic stdio tool surface.

Running in CI? CLI reference plus exit codes plus error categories.

Threat-modelling? Security model and pre-commit gate.

proxxxTerminal cockpit for Proxmox VE & PBS.

One binary, three callers

No agent on the cluster

Six-stage commit gate, no skip flags

Pre-flight risk gate plus HITL

By the numbers ​

A taste ​

What it is not ​

Where to start ​

By the numbers

A taste

What it is not

Where to start