Quickstart: Homelab in 5 minutes
You have one Proxmox node (or two or three), a few VMs, a router that doesn't fight you, and 5 minutes. By the end you'll be running proxxx against the cluster from your laptop.
TIP
This is the homelab path. If you're deploying for a team, start at Production checklist instead — it's stricter on TLS, secret storage, and HITL.
One static binary, no agent on the cluster — by the end of this page, the commands above are showing your cluster.
1. Install the binary (1 min)
TARGET=aarch64-apple-darwin # macOS Apple Silicon
# TARGET=x86_64-unknown-linux-musl # Linux
gh release download \
--repo fabriziosalmi/proxxx \
--pattern "*-${TARGET}.tar.gz" \
--pattern "*-${TARGET}.tar.gz.sha256"
shasum -a 256 -c proxxx-*-${TARGET}.tar.gz.sha256
tar xzf proxxx-*-${TARGET}.tar.gz
sudo mv proxxx-*/proxxx /usr/local/bin/
proxxx --versionIf you'd rather build from source: cargo install --path . from a clone.
2. Mint a token on the node (1 min)
If your laptop can SSH as root to the node, let proxxx do it. Write the template, set url and verify_tls = false, and uncomment [ssh] with your key:
proxxx init
$EDITOR ~/.config/proxxx/config.toml # macOS: ~/Library/Application Support/dev.proxxx.proxxx/config.toml
proxxx token bootstrap --role PVEAdmin --yestoken bootstrap runs pveum on the node over SSH, grants the role on / (PVEAuditor without --role, which is read-only), stores the secret in the macOS keychain or a 0600 file without printing it, checks the token against the API, and prints the config.toml lines to add. Then skip the wizard and go to step 4.
Without SSH, in the PVE web UI: Datacenter → Permissions → API Tokens → Add. Untick "Privilege Separation" (homelabs rarely need it), copy the secret immediately — PVE shows it once.
Or from the node's shell:
ssh root@<node>
pveum user token add root@pam proxxx --privsep=0
# → full-tokenid: root@pam!proxxx
# → value : <uuid> # save this3. Run the wizard (2 min)
proxxx init --interactiveFive prompts:
| Step | Pick | Why |
|---|---|---|
| 1. URL | https://<node>:8006 | Your PVE host |
| 2. Verify TLS | n | Self-signed cert in homelabs is normal |
| 3. Auth method | 1 (token) | Pasta the full user!id=secret string |
| 4. SSH | skip (n) | Add later only if you'll run proxxx perms |
| 5. Telegram HITL | skip (n) | Solo operator = implicit consent |
The wizard probes the cluster live at each step — wrong token gets caught at the prompt, never lands in TOML.
4. Drive it (1 min)
proxxx ls nodes
proxxx ls guests
proxxx # TUI mode — vim keys, ? for helpIn the TUI:
g→ guest listj/k→ up/downEnter→ details/S/r→ start / stop / restart selectedc→ SSH session (needs[ssh.guests."<vmid>"]or QGA agent)Esc→ back,q→ quit?→ keymap reference
Bottom row footer shows the relevant binds for the current view.
5. Where next
| You want to… | Read… |
|---|---|
| Snapshot before risky changes | proxxx snapshot create <vmid> --name pre-upgrade |
| Migrate a VM between nodes | proxxx migrate <vmid> <target> --yes |
| Watch migration progress live | proxxx migrate <vmid> <target> --stream |
| Move a disk to NFS | proxxx disk move <vmid> --disk scsi0 --storage <nfs> --yes |
| Snapshot the whole cluster's pools / ACLs / storage definitions | proxxx state export > cluster.toml |
| Check what's drifted before a change | proxxx state diff cluster.toml |
| Get the cluster's most-recent backup status at a glance | proxxx backup-verify --max-age-days 7 |
| See per-pool / per-node resource usage | proxxx accounting --group-by pool |
| Find anomalies across the cluster | proxxx anomaly |
| Spin up an Ubuntu/Debian cloud-init VM | proxxx cloud-img list && proxxx cloud-img download ubuntu/24.04 |
| Browse PBS backups | PBS integration |
| Hook Claude / Cursor in | MCP server (5-min setup) |
| Get Telegram approvals | HITL (more involved) |
Common stumbles
| Error | Fix |
|---|---|
Token secret not found | Re-run wizard; the inline token_secret = is the simplest. |
Identity file not accessible (SSH wizard) | The wizard auto-discovers keys in ~/.ssh/ from v0.1.3 — pick the right one from the list. |
proxxx ssh <vmid> says "no [ssh.guests…]" | Either install qemu-guest-agent in the guest (auto-discovery resolves IP) or pin the host in [ssh.guests."<vmid>"]. |
Full list at Troubleshooting.