Quick start

Five minutes from cargo build to driving a real cluster.

1. Authenticate

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.

Easy path: the wizard

proxxx init --interactive

5-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 cert

TIP

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 storage

Pipe-friendly JSON for scripting:

proxxx ls guests --format json | jq '.[] | select(.status == "running") | .vmid'

3. Try the TUI

Run with no arguments:

proxxx

Vim-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 --force

If 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 noVNC

spice 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"
require_approval = true

Now proxxx delete <vmid> --yes on a guest tagged prod will:

1. Send an inline-keyboard approval request to your Telegram chat.
2. Wait up to 120 s for a callback.
3. 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.

Next steps

• Configuration — profiles, secrets, TLS, HITL
• Pre-commit gate — for contributors
• MCP server — drive proxxx from an LLM agent