Skip to content

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.

proxxx terminal recording against a live Proxmox VE 9.1 lab cluster: ls nodes, ls guests, ls storage, describe, and ls guests --format json piped to jq

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) ​

bash
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 --version

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

bash
proxxx init
$EDITOR ~/.config/proxxx/config.toml     # macOS: ~/Library/Application Support/dev.proxxx.proxxx/config.toml
proxxx token bootstrap --role PVEAdmin --yes

token 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:

bash
ssh root@<node>
pveum user token add root@pam proxxx --privsep=0
# → full-tokenid: root@pam!proxxx
# → value       : <uuid>     # save this

3. Run the wizard (2 min) ​

bash
proxxx init --interactive

Five prompts:

StepPickWhy
1. URLhttps://<node>:8006Your PVE host
2. Verify TLSnSelf-signed cert in homelabs is normal
3. Auth method1 (token)Pasta the full user!id=secret string
4. SSHskip (n)Add later only if you'll run proxxx perms
5. Telegram HITLskip (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) ​

bash
proxxx ls nodes
proxxx ls guests
proxxx                  # TUI mode — vim keys, ? for help

In the TUI:

  • g → guest list
  • j/k → up/down
  • Enter → detail
  • s / S / r → start / stop / restart selected
  • c → 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 changesproxxx snapshot create <vmid> --name pre-upgrade
Migrate a VM between nodesproxxx migrate <vmid> <target> --yes
Watch migration progress liveproxxx migrate <vmid> <target> --stream
Move a disk to NFSproxxx disk move <vmid> --disk scsi0 --storage <nfs> --yes
Snapshot the whole cluster's pools / ACLs / storage definitionsproxxx state export > cluster.toml
Check what's drifted before a changeproxxx state diff cluster.toml
Get the cluster's most-recent backup status at a glanceproxxx backup-verify --max-age-days 7
See per-pool / per-node resource usageproxxx accounting --group-by pool
Find anomalies across the clusterproxxx anomaly
Spin up an Ubuntu/Debian cloud-init VMproxxx cloud-img list && proxxx cloud-img download ubuntu/24.04
Browse PBS backupsPBS integration
Hook Claude / Cursor inMCP server (5-min setup)
Get Telegram approvalsHITL (more involved)

Common stumbles ​

ErrorFix
Token secret not foundRe-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.

Released under the MIT License. · Privacy & legal