Quick start
Five minutes from cargo build to driving a real cluster.
1. Authenticate
Fastest path: proxxx mints the token over SSH
If you can SSH as root to a node, proxxx token bootstrap creates the API token there with pveum, grants it a role, and stores the secret without printing it. Start from the commented template, set url, user and verify_tls, and uncomment [ssh]:
proxxx init # writes ~/.config/proxxx/config.toml (Linux); --force to overwriteurl = "https://pve1.lan:8006"
user = "root@pam"
token_id = "proxxx"
verify_tls = false # self-signed certificate
[ssh]
user = "root"
key_path = "~/.ssh/id_ed25519"proxxx token bootstrap --yes # read-only: PVEAuditor on /
proxxx token bootstrap --role PVEAdmin --yes # to start, stop and migrate guestsIt connects to the host in url on port 22 (--ssh-host <host[:port]> for another node) under the [ssh] host-key policy (tofu by default: the first connection records the key; "off" is refused). The secret goes to --secret-file <path>, else the profile's token_secret_file, else the macOS keychain, else <config dir>/secrets/<profile>.token, always mode 0600. proxxx then checks the new token against /version and /nodes and prints the lines to add to config.toml (token_id, and token_secret_file for a file); it does not edit the file. A token that already exists is refused unless you pass --rotate, which invalidates the old secret.
Without SSH: create the token in the web UI
Create an API token in the Proxmox web UI under Datacenter → Permissions → API Tokens. Untick "Privilege Separation" unless you know which roles you need. Copy the secret — Proxmox shows it only once. Then use the wizard or edit the file.
Easy path: the wizard
proxxx init --interactive5-step prompted flow that walks you through URL, TLS, auth (token or password), optional SSH layer + per-guest overrides, optional Telegram for HITL. Each input is validated against the live cluster before write — a wrong token is caught at the prompt, never lands in the TOML. Existing config triggers a backup-or-cancel prompt; new file written with mode 0600.
Manual path
If you'd rather edit the file by hand:
# ~/.config/proxxx/config.toml (Linux)
url = "https://pve1.lan:8006/"
user = "root@pam"
auth = "token"
token_id = "proxxx"
token_secret = "00000000-0000-0000-0000-000000000000"
verify_tls = false # set to true if your cluster has a real certTIP
The token secret can also come from the PROXXX_TOKEN_SECRET environment variable, a 0600-mode file referenced as token_secret_file, or your OS keychain. Resolution order is documented under Configuration → Secrets.
2. Read the cluster
proxxx ls nodes
proxxx ls guests
proxxx ls storagePipe-friendly JSON for scripting:
proxxx ls guests --format json | jq '.[] | select(.status == "running") | .vmid'3. Try the TUI
Run with no arguments:
proxxxVim-style keybindings throughout. Press ? for the keymap reference.
| Key | Action |
|---|---|
j k | move selection |
Enter l | drill in |
h Esc | back |
1–9 | switch view |
/ | fuzzy search across the cluster |
: | command palette |
R | force refresh |
q | quit |
4. Run an operation safely
Every destructive op routes through a pre-flight risk check. Try:
proxxx stop 100 --forceIf guest 100 is tagged prod, has been up for over 30 days, or has active network traffic, proxxx prints the risk summary and asks for explicit --allow-risk. The risk levels are NOTICE (advisory), WARN (advisory), and SEVERE (refuses without override).
See Pre-flight risk gate.
5. Hand off a graphical console
proxxx ssh 100 # interactive ssh (system ssh + QGA auto-discovery)
proxxx serial 100 --node pve1 # raw termproxy WebSocket
proxxx spice 100 --node pve1 # writes a 0600 .vv, launches remote-viewer
proxxx novnc 100 --node pve1 # opens browser to the web UI's noVNCspice and novnc need a graphical client on the local machine — proxxx never renders frames itself. See Console handoff.
6. Wire HITL (optional)
If you want destructive ops gated by Telegram approval:
[telegram]
bot_token = "123456:ABC..."
chat_id = "-1001234567890"
[[policies]]
action = "delete"
target = "tag:prod"
channel = "telegram"
require = 1 # approvals neededNow proxxx delete <vmid> --yes on a guest tagged prod will:
- Send an inline-keyboard approval request to your Telegram chat.
- Wait up to 120 s for a callback.
- Execute on Approve, refuse on Deny or timeout.
See HITL via Telegram.
7. Wire CI
Every CLI command is --format json capable. Exit codes are stable — see Exit codes for the full table.
proxxx reconcile run --source <git> is the GitOps drift gate: exit 2 when the live cluster has drifted from the desired state declared in git, 0 when in sync — drop it in a pipeline step. reconcile converge applies the fix, safe by default (deletes need an explicit --prune).
Next steps
- Configuration — profiles, secrets, TLS, HITL
- Pre-commit gate — for contributors
- MCP server — drive proxxx from an LLM agent