# Proxxx > Terminal cockpit for Proxmox VE & PBS — Rust TUI + CLI, single static binary, six-stage commit gate, no agent on the cluster. - **Type:** MCP server - **Install:** `agentstack add mcp-fabriziosalmi-proxxx` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [fabriziosalmi](https://agentstack.voostack.com/s/fabriziosalmi) - **Installs:** 0 - **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [fabriziosalmi](https://github.com/fabriziosalmi) - **Source:** https://github.com/fabriziosalmi/proxxx - **Website:** https://fabriziosalmi.github.io/proxxx/ ## Install ```sh agentstack add mcp-fabriziosalmi-proxxx ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About proxxx Terminal cockpit for Proxmox VE & Proxmox Backup Server. Rust · async · single static binary · no installer · no agent. Talks to the things that already exist on your cluster — REST against PVE and PBS, SSH for the rest — instead of asking you to deploy a new daemon. --- ## Who is this for? Pick the row that matches you and jump straight to the right page. | If you are… | …you'll care about | Start here | | :--- | :--- | :--- | | **Homelab solo** running 1-3 nodes | wizard, fast TUI, single binary, no daemons | [5-min homelab quickstart](https://fabriziosalmi.github.io/proxxx/guide/quickstart-homelab) | | **Platform / SRE** on 10-50 nodes with on-call | HITL Telegram gate, alert daemon, `--format json` for CI, `--profile` for multi-cluster | [Production checklist](https://fabriziosalmi.github.io/proxxx/guide/production-checklist) · [HITL](https://fabriziosalmi.github.io/proxxx/integrations/hitl) | | **DevOps** scripting Proxmox in pipelines | typed exit codes, deterministic JSON, pre-flight risk gate, batch ops with `--yes` | [CLI reference](https://fabriziosalmi.github.io/proxxx/reference/cli) · [Exit codes](https://fabriziosalmi.github.io/proxxx/reference/exit-codes) | | **LLM / agent integrator** wiring Claude/Cursor to a cluster | MCP server (stdio + Streamable HTTP), compile-time-fixed 25-tool registry, SHA-256 pinned for supply-chain audit | [LLM/MCP quickstart](https://fabriziosalmi.github.io/proxxx/guide/quickstart-llm-mcp) | | **Security / compliance** evaluating before deploy | typed errors, HITL replay protection, sigstore-signed releases, CycloneDX SBOM, gate on every commit | [`THREAT_MODEL.md`](THREAT_MODEL.md) · [`SECURITY.md`](SECURITY.md) · [Production checklist](https://fabriziosalmi.github.io/proxxx/guide/production-checklist) | | **EU-regulated ops** (NIS2 / ISO 27001 / GDPR) | append-only SQLite audit log with HMAC-SHA256 chain, `proxxx audit verify`, zero telemetry, fully self-hosted | [EU & compliance](#eu--compliance) | | **Contributor** sending a PR | 8-stage commit gate (fmt + clippy + audit + cargo-deny + test+proptest + live cluster + mutation lifecycle), no-skip-flags policy | [`ARCHITECTURE.md`](ARCHITECTURE.md) · [`CONTRIBUTING.md`](CONTRIBUTING.md) · [Pre-commit gate](https://fabriziosalmi.github.io/proxxx/guide/pre-commit-gate) | --- ## What you get - **One binary** — `proxxx`. CLI, TUI, MCP server, unified daemon (alerts + HITL + schedule) all in the same executable. - **Cluster-wide read in a second** — `proxxx ls nodes`, `proxxx ls guests`, fuzzy search across the whole cluster from `/`. `--all-profiles` fans the read across every configured cluster in parallel. - **GitOps for Proxmox** — `proxxx state {export,diff,apply}` produces a byte-stable TOML across **ten state families** (pools, ACL grants, storage definitions, backup jobs, cluster firewall, notification matchers, HA rules, HA resources, and PCI + USB device mappings — **passthrough-as-code**), diffs against live, converges via dispatched API calls. Pre-flight risk gates refuse Severe changes (non-empty pool delete, root-role ACL delete, shared-storage delete, HA-rule strict-flip, passthrough-mapping delete) unless `--allow-risk`; `--interactive` adds per-Severe `[y/N]` stdin prompts. The **`reconcile` controller** runs that loop continuously: `reconcile run` (CI-gateable drift check) and `reconcile converge` (push-mode apply, same safety gate), plus an opt-in **unmanned `auto_converge`** daemon that self-heals drift on a timer — and **never** auto-applies a Severe change (it alerts for human review instead). - **Pipeline writes** — start, stop, migrate, snapshot, clone, backup, patch, disk-move, with `--format json` for jq. `migrate --stream` shows live per-disk progress. - **Pre-flight risk gate** — both per-guest (Locked/Running/LongUptime/TaggedProd/ActiveNetTraffic/HaManaged + 5 more) and state-change (PoolDeleteNonEmpty/AclDeleteRootRole/StorageDeleteShared/BackupJobDelete/NotificationMatcherDelete/HaRuleDelete/HaRuleStrictChange/HaResourceDelete/HaResourceStateChange/BulkChangeCount) — refuses destructive ops without explicit override. - **HITL** — Telegram-mediated human approval gate, deny-on-timeout (120 s), policy-driven by tag / vmid / wildcard. - **Incident lockdown** — `proxxx incident freeze --reason X --ttl 4h` halts every mutation cluster-wide (`POST`/`PUT`/`DELETE` refuse with exit 8); `thaw` lifts it. Reads keep working for investigators. - **Console handoff + recording** — SSH/serial/SPICE/noVNC, all from `proxxx `. `proxxx serial --record` writes asciinema cast v2; `proxxx play-cast` replays. - **Cross-cluster** — `proxxx find ` answers "which cluster owns this guest?" without manual profile-switching. - **Fleet view** — `proxxx fleet` aggregates **every** configured profile (clusters + standalone hosts, mixed) into one read-only TUI: per-cluster health summary + an aggregated guest table. `↑↓` select a cluster, `Tab` toggle the guest pane (selected vs whole fleet), `Enter` drill into a cluster's full TUI, `q` quit. - **Read-only profiles** — `read_only = true` on a profile makes proxxx refuse *every* mutation on it client-side (reads still work); pair with a `PVEAuditor` PVE token for a server-enforced lock too. Observe production safely, write only on your test cluster. - **PBS browse + restore** — REST browse plus `proxmox-backup-client` restore with `kill_on_drop` supervision. `proxxx backup-verify` does metadata-level integrity probing. - **Observability** — `proxxx logs tail` (cross-node journalctl fanout via SSH), `proxxx heatmap` (per-node API RTT), `proxxx anomaly` (z-score outliers), `proxxx accounting --timeframe month` (CPU-hours/GiB·h/net-GiB from per-guest RRD). - **Upgrade pre-flight** — `proxxx upgrade-check --target 9.x` scans cluster + config against bundled rules; exit code 1 on any block-severity finding (CI-gateable). - **Bundled error knowledge base** — `proxxx explain ` for every typed error proxxx can emit (15 entries; ships with the binary, no network needed). - **Cluster digest for LLMs** — `proxxx describe --output llm-context` emits a token-compact prose+key:value paste-pronto for AI chats. - **MCP server** — stdio JSON-RPC + HTTP/SSE for LLM agents, compile-time-fixed tool registry, surface SHA-256 pinned. Server-sent `notifications/cluster-event` on both transports (task lifecycle + freeze/thaw events). - **Verifiable releases** — every tarball ships with three layers: SHA-256 sidecar, sigstore keyless cosign signature pinned to this exact workflow path (offline-verifiable; transparency-log inclusion proof embedded), and a CycloneDX SBOM generated from `Cargo.lock`. Audit with `cosign verify-blob` + `grype` / `trivy`. ## EU & compliance proxxx is designed for operators who need auditability, data sovereignty, and supply-chain transparency — requirements increasingly mandated under NIS2, ISO 27001, and GDPR in the EU. | Requirement | How proxxx addresses it | | :--- | :--- | | **No telemetry** | Zero outbound connections except to your configured PVE/PBS endpoints and, if you opt in, your own Telegram bot. No analytics, no crash-reporting, no version-check pings. | | **Data sovereignty** | All state — config, cache, audit log, HITL keys — lives on-prem, under paths you control (`~/.config/proxxx/` / `~/.local/share/proxxx/` on Linux). Nothing leaves your environment unless you push it there. | | **Append-only audit log** | `proxxx audit log` — every mutation (start, stop, delete, snapshot, patch, create) is written to a local SQLite database with a per-entry HMAC-SHA256 chain. Tampering any record breaks the chain. | | **Cryptographic chain verification** | `proxxx audit verify` walks every entry, recomputes the HMAC chain from the keyed root, and reports the first broken link. CI-friendly: exits 0 on pass, 1 on violation — wire it into your compliance pipeline. | | **Export for SIEM** | `proxxx audit export --format json` or `--format csv` — pipe into Splunk, Elastic, Wazuh, or any log aggregator without an agent. | | **Supply-chain** | Every release ships: SHA-256 sidecar, sigstore keyless cosign signature (pinned to the exact workflow path, offline-verifiable, transparency-log proof embedded), and a CycloneDX SBOM from `Cargo.lock`. Audit with `cosign verify-blob` + `grype` / `trivy`. | | **Self-diagnostic** | `proxxx doctor` validates config, cluster connectivity, auth, Telegram HITL, PBS, SSH key, and audit log integrity in one pass. Exits 0 if all critical checks pass. | | **Secrets hygiene** | All secret values live in `Zeroizing` (heap-wiped on Drop). HMAC and audit keys are stored at 0600 paths; proxxx refuses to start if a key file has world-readable permissions. | > **Note:** proxxx is a management tool, not a compliance product. `proxxx audit verify` provides integrity assurance for the local mutation log; it does not replace a SIEM or a formal audit trail required by a certification body. Use it as one control layer in a broader NIS2 / ISO 27001 implementation. --- ## Install Pre-built binaries for **macOS Apple Silicon**, **Linux x86_64-musl**, and **Linux aarch64-musl** (Pi 4/5, Ampere, Graviton, Oracle Free Tier) are attached to each [tagged release](https://github.com/fabriziosalmi/proxxx/releases). All Linux artefacts are statically linked — no glibc, drops onto Alpine through RHEL. ### Homebrew (macOS & Linux) ```bash brew install fabriziosalmi/proxxx/proxxx ``` The fastest path on a workstation. For a Proxmox VE node (Debian) use the [`.deb`](#debian--ubuntu--proxmox-ve--deb) below; for air-gapped installs or full supply-chain verification, download + verify the trio manually: ```bash TARGET=x86_64-unknown-linux-musl # or aarch64-apple-darwin VERSION=$(gh release view --repo fabriziosalmi/proxxx --json tagName -q .tagName | sed 's/^v//') gh release download v${VERSION} --repo fabriziosalmi/proxxx \ --pattern "*-${TARGET}.tar.gz" \ --pattern "*-${TARGET}.tar.gz.sha256" \ --pattern "*-${TARGET}.tar.gz.cosign.bundle" # 1. Checksum shasum -a 256 -c proxxx-${VERSION}-${TARGET}.tar.gz.sha256 # 2. Sigstore keyless signature (offline; cert pinned to release.yml) cosign verify-blob \ --bundle proxxx-${VERSION}-${TARGET}.tar.gz.cosign.bundle \ --certificate-identity-regexp 'https://github.com/fabriziosalmi/proxxx/.github/workflows/release.yml@.*' \ --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \ proxxx-${VERSION}-${TARGET}.tar.gz # 3. (optional) Audit the CycloneDX SBOM gh release download v${VERSION} --repo fabriziosalmi/proxxx \ --pattern "*.cdx.json" --pattern "*.cdx.json.sha256" shasum -a 256 -c proxxx-${VERSION}.cdx.json.sha256 grype sbom:proxxx-${VERSION}.cdx.json # or trivy / cyclonedx-cli tar xzf proxxx-${VERSION}-${TARGET}.tar.gz ./proxxx-${VERSION}-${TARGET}/proxxx --version ``` If you only want the binary fast (no verification), skip steps 2–3 and run just `shasum -a 256 -c …` from the snippet above. Production deployments should run all three — see the [Production checklist](https://fabriziosalmi.github.io/proxxx/guide/production-checklist). Or build from source (needs Rust 1.95+): ```bash git clone https://github.com/fabriziosalmi/proxxx.git cd proxxx && cargo build --release ./target/release/proxxx --version ``` The Linux musl artifact is statically linked — runs on every distro from RHEL 6 to Alpine 3.x without GLIBC drama. ### Debian / Ubuntu / Proxmox VE — `.deb` Each release also ships a `.deb` for **amd64** and **arm64**, signed with the same sigstore bundle. The binary is static-musl, so the package declares **no runtime dependencies** — drop it straight onto a Proxmox VE node (which is Debian): ```bash VERSION=$(gh release view --repo fabriziosalmi/proxxx --json tagName -q .tagName | sed 's/^v//') gh release download v${VERSION} --repo fabriziosalmi/proxxx \ --pattern "proxxx_${VERSION}-1_amd64.deb" # or _arm64.deb sudo apt install ./proxxx_${VERSION}-1_amd64.deb # or: sudo dpkg -i proxxx_*.deb proxxx --version ``` Verify its signature exactly like the tarball — `cosign verify-blob --bundle proxxx_${VERSION}-1_amd64.deb.cosign.bundle …` with the same `--certificate-identity-regexp` / `--certificate-oidc-issuer` as above. ## Quick start ```bash proxxx init --interactive # 5-step wizard: prompts for URL, auth, TLS, optional # SSH + Telegram, validates each input against the # live cluster before write. Recommended for first # run — wrong field caught here, never lands in TOML. proxxx init # non-interactive variant: writes a commented # starter config.toml; refuses to overwrite — pass # --force if you mean it. Edit url / user / # token_id / token_secret manually after. proxxx ls nodes # validates the connection. proxxx # TUI (no args). Press ? for the keymap; the # bottom-row footer shows contextual binds always. proxxx --help # full subcommand list. proxxx version --json # build + capability metadata. ``` The starter `config.toml` carries inline comments for every secret-resolution path (CLI flag → env var → 0600 file → OS keychain). Optional sections — HITL via Telegram, SSH layer, PBS, alerts, policies — are commented out so the API-only operator doesn't have to delete anything. ## Daily-driver TUI Run with no arguments. Vim keys, fuzzy search across the cluster (`/`), command palette (`:`), quick-open palette (`Ctrl+K`). 18 views over the same Elm-pattern reducer: | `1` Dashboard | `2` Nodes | `3` Guests | `4` Storage | | :---: | :---: | :---: | :---: | | `H` Heatmap | `B` Backup board | `G` Config grep | `Q` Operation queue | | `T` Audit timeline | `Z` Snapshot tree | `D` Drift compare | `W` Hardware passthrough | Plus a read-only **fleet view** (`proxxx fleet`) that aggregates every configured profile into one screen — `↑↓` select cluster, `Tab` toggle guest pane, `Enter` drill into a cluster, `q` quit. Multi-select + bulk ops with pre-flight risk preview. Operation queue with dry-run, diff preview, replay-as-script export (proxxx CLI / pvesh / curl / Ansible), and HITL approval gate (Telegram, policy-driven). The terminal is restored on every exit path — happy, `?` early-return, panic. RAII `TerminalGuard` plus a flight-recorder panic hook installed in `main()` before the runtime starts. ## Pipeline-friendly CLI ```bash # Read proxxx ls guests --format json | jq '.[] | select(.status == "running") | .vmid' proxxx ha preview --node pve1 # failover what-if proxxx hw conflicts --node pve1 # PCI passthrough audit proxxx perms root@pam --node pve1 # effective permissions ``` ```bash # Write — every destructive op routes through the pre-flight risk gate 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 ``` ```bash # Console handoff proxxx ssh 100 # interactive ssh into guest (system ssh + # QGA / lxc-interfaces auto-discovery; falls # back to [ssh.guests."100"] when explicit) proxxx serial 100 --node pve1 # raw termproxy WebSocket proxxx spice 100 --node pve1 # writes 0600 .vv, launches remote-viewer proxxx novnc 100 --node pve1 # opens browser to web UI's noVNC ``` ```bash # GitOps loop — export, diff, apply with safety on top proxxx state export > state.toml … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [fabriziosalmi](https://github.com/fabriziosalmi) - **Source:** [fabriziosalmi/proxxx](https://github.com/fabriziosalmi/proxxx) - **License:** MIT - **Homepage:** https://fabriziosalmi.github.io/proxxx/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-fabriziosalmi-proxxx - Seller: https://agentstack.voostack.com/s/fabriziosalmi - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.