// Betrieb
Connecting a Proxmox homelab
A single, end-to-end walkthrough for putting a Proxmox VE host under Fleeger:
create the location, add the proxmox_node resource, mint a read-only Proxmox
monitoring token, hand it to Fleeger as a credential, deal with the
self-signed API certificate, and onboard the spoke-agent that ties it together.
The individual steps each have their own reference page (creating a location, adding a resource, managing credentials, onboarding a location); this page threads them into one sequence and fills in the Proxmox-specific details those pages leave generic.
What you'll need: root (or
Sys.Audit) access to a Proxmox node for a fewpveumcommands, the hub's URL, and somewhere to run the agent (the PVE host itself, a Pi, a VM — anywhere that can reach both the hub and the Proxmox API).
The shape of it
spoke-agent ──(1) bootstrap over HTTPS ──► hub (mints per-location NATS creds)
│ ──(2) metrics + inventory ──► hub, over wss://<hub>/nats
│
└────────(3) reads the Proxmox API ──► https://<pve>:8006 (self-signed)
The agent reaches the hub over one URL (see onboarding). Separately, it reaches the target — your Proxmox API — using the address and credential you register below. Those are two different network paths; this page is mostly about the second one.
1. Create the location
Locations → New location: name it (e.g. homelab), pick Kind = homelab.
See creating a location. The location's name is a
stable id — later steps (agent creds, metric labels) bind to it.
2. Create a read-only Proxmox monitoring token
Fleeger only reads Proxmox for metrics and discovery (node/VM status and resource usage), so the monitoring token needs audit rights only — no power privileges. (Power actions like Start/Stop are a separate, opt-in step with its own token privilege; see controlling a Proxmox VM.)
Run these on any Proxmox node, as root@pam. They create a dedicated user, an
API token for it, and grant that token the built-in PVEAuditor role
(Proxmox's read-only role) across the whole datacenter:
# 1. a dedicated monitoring user in the PVE realm (no password — token-only)
pveum user add fleeger@pve
# 2. an API token for it, with privilege separation ON (--privsep 1).
# This prints the token's secret VALUE exactly once — copy it now.
pveum user token add fleeger@pve monitoring --privsep 1
# 3. grant the TOKEN read-only audit rights on the whole tree, propagating down
pveum acl modify / --tokens 'fleeger@pve!monitoring' --roles PVEAuditor --propagate 1Step 2 prints something like:
┌──────────────┬──────────────────────────────────────┐
│ key │ value │
├──────────────┼──────────────────────────────────────┤
│ full-tokenid │ fleeger@pve!monitoring │
│ value │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │
└──────────────┴──────────────────────────────────────┘
Keep both: full-tokenid and value are the two halves of the credential you
enter in step 4.
--privsep 1matters. With privilege separation on, the token starts with no rights and only gets what you grant to the token in step 3 (not what its user has). That's why the ACL in step 3 targets--tokens 'fleeger@pve!monitoring'and not the user. It's the least-privilege default.A quick homelab shortcut is to use an existing
root@pamtoken instead of a dedicated user — the UI even placeholdersroot@pam!monitoring— but that token is only read-only if you scope it withPVEAuditoras above; a privsep-off root token inherits root's full rights.
PVEAuditor is the smallest built-in role that covers everything the
collector calls (/nodes needs Sys.Audit, /cluster/resources needs
VM.Audit; PVEAuditor bundles Datastore.Audit, Sys.Audit, VM.Audit, …).
Using the built-in PVEAuditor is the version-proof choice: Proxmox keeps it
in sync across major upgrades, so it stays correct on both PVE 8 and PVE 9 (see
required permissions by Proxmox version).
If you'd rather hand-roll a minimal custom role:
pveum role add FleegerMonitor -privs "VM.Audit Sys.Audit Datastore.Audit"
pveum acl modify / --tokens 'fleeger@pve!monitoring' --roles FleegerMonitor --propagate 1The custom FleegerMonitor role above is deliberately spelled with only
VM.Audit, Sys.Audit, and Datastore.Audit — three privileges that exist and
mean the same thing on both PVE 8 and PVE 9 — so it survives an 8 → 9 upgrade
unchanged. Do not add the old VM.Monitor privilege to it: PVE 9 removed
that privilege, and pveum role add … -privs "… VM.Monitor" fails outright on a
PVE 9 host. See the version table next for the details.
Required permissions by Proxmox version
Fleeger's collector only ever makes three read calls per poll, and their privilege requirements are what actually matter:
| API call (per poll) | What it feeds | Privilege | Granted at |
|---|---|---|---|
GET /api2/json/nodes |
node status + CPU/RAM/uptime | Sys.Audit |
/ (propagate) |
GET /api2/json/cluster/resources?type=vm |
per-VM/CT status + usage | VM.Audit |
/ (propagate) |
GET /api2/json/cluster/status |
which cluster the VMs belong to (below) | Sys.Audit |
/ (propagate) |
Both privileges — and the built-in PVEAuditor role that bundles them — exist
on every supported Proxmox version, so the setup in this page works the same
whether the host is PVE 8 or PVE 9:
| Proxmox major | Recommended role | Equivalent hand-rolled privileges | Notes |
|---|---|---|---|
| 8.x | PVEAuditor |
Sys.Audit, VM.Audit, Datastore.Audit |
VM.Monitor still exists but Fleeger's metrics path never needs it. |
| 9.x | PVEAuditor |
Sys.Audit, VM.Audit, Datastore.Audit |
VM.Monitor removed — basic monitor access folded into Sys.Audit. |
The 8 → 9 change that silently breaks metrics. Proxmox VE 9.0 lists "Removal of the
VM.Monitorprivilege" among its breaking changes — basic KVM monitor access now rides onSys.Auditinstead. Two ways this bites a homelab that was working on PVE 8:
- A custom role that listed
VM.Monitor. After the upgrade Proxmox drops the now-nonexistent privilege from the role. If that role was the token's only grant ofSys.Audit-adjacent rights, its effective audit coverage can shrink and/nodes//cluster/resourcesstart returning 403, which the agent surfaces as "no metrics" rather than a loud error. Re-grant with the PVE-9 privilege set above (or just switch the token to built-inPVEAuditor).- Re-running an old provisioning script that does
pveum role add … -privs "… VM.Monitor"on the freshly-upgraded host — it now errors becauseVM.Monitorno longer exists. Drop it from the-privslist.If you used the built-in
PVEAuditor(this page's recommendation), the upgrade needs no permission changes — Proxmox updated the built-in role for you.
3. Add the Proxmox resource
Open the location → New resource (see adding a resource):
- Kind —
proxmox_node. - Address — the Proxmox API base URL,
https://<host>:8006. Use a name/IP the agent can reach (see networking). Examples:https://pve1.local:8006,https://192.168.1.10:8006, orhttps://localhost:8006when the agent runs on the PVE host itself. Behind a reverse proxy at a path, include the path:https://proxy.lan/proxmoxis asked athttps://proxy.lan/proxmox/api2/json/…. - Allow invalid/self-signed TLS certs — tick this. Proxmox serves
:8006with a self-signed certificate by default, so leaving it unchecked makes every collection fail with a TLS verification error. See self-signed TLS below for the trade-off and alternatives. - Tags (optional) — e.g.
env:homelab.
4. Attach the monitoring token as a credential
Still in the resource form, under Credential, choose New credential and fill in the two Proxmox fields (this is the credential shape managing credentials refers to generically):
| Field | UI label | Enter | Example |
|---|---|---|---|
api_user |
API token id | the full token id, USER@REALM!TOKENID |
fleeger@pve!monitoring |
api_secret |
API token secret | the token's secret value (a UUID) |
3b6f…-…-… |
Those are the full-tokenid and value from step 2. Internally the agent sends
them to Proxmox as the PVEAPIToken=<api_user>=<api_secret> header — so the id
must include the !TOKENID part, not just the user. The secret is stored
encrypted at rest and never shown again; to change it later, rotate the
credential (one place, all attached resources — see
managing credentials).
Save the resource.
5. Networking: what must reach what
Two independent paths, and only one is the "single hub URL" the onboarding docs describe:
- Agent → hub — one URL (
https://<hub>for bootstrap, thenwss://<hub>/natsfor everything else). Covered in onboarding. - Agent → Proxmox API — the agent must reach the Address from step 3 on
TCP 8006. This is what varies by where you run the agent:
- On the PVE host (as a container or the binary):
https://localhost:8006works, but the self-signed cert's name won't matchlocalhost, so you must tick allow invalid certs (step 3). If you run it in Docker, rememberlocalhostinside a container is the container — use--network host, or point the address at the host's LAN IP instead. - Elsewhere on the LAN (a Pi, another VM): use the PVE host's LAN name or
IP, e.g.
https://pve1.local:8006, and make sure any firewall lets 8006 through from the agent's host.
- On the PVE host (as a container or the binary):
6. Onboard the agent
Back on Locations, use Onboard on the location's row to mint a one-time registration token and copy the install command (full onboarding guide). One Proxmox-specific caveat:
Your own registry? The Onboard panel's Docker command runs
registry.netcode.dev/fleeger/spoke-agentat your hub's version. If you built and pushed the images to another registry (deploy/build-and-push.shwith yourREGISTRY, see container images), swap the image accordingly, e.g.:docker run -d --restart unless-stopped --name fleeger-agent \ -v fleeger-agent-data:/var/lib/fleeger \ -e FLEEGER_HUB_URL=https://your-hub.example.com \ --env-file fleeger-agent.env \ registry.example.com/fleeger/spoke-agent:X.Y.Z
fleeger-agent.envholds the token so it stays off the command line. The copied Docker command creates it in its first line and removes it afterdocker run; keep both lines around the editeddocker run. The onboarding guide has a version that asks for the token at a prompt.
Run the command where the agent lives. On first boot it exchanges the token for per-location NATS credentials and starts collecting. Within ~90s the location flips to reachable (checking reachability).
Tuning the poll interval
The agent collects every 30s by default. To change it, set
FLEEGER_POLL_INTERVAL_SECS (or poll_interval_secs in the TOML config;
0 is ignored).
Docker only takes environment variables when it creates a container, so a
running agent is removed and created again; its credentials stay on the
volume:
docker rm -f fleeger-agent
docker run -d --restart unless-stopped --name fleeger-agent \
-v fleeger-agent-data:/var/lib/fleeger \
-e FLEEGER_HUB_URL=https://your-hub.example.com \
-e FLEEGER_POLL_INTERVAL_SECS=15 \
registry.netcode.dev/fleeger/spoke-agent:X.Y.ZKeep it well under 90s: each resource reports once per cycle, and its
alerts treat 90s of silence as unreachable. An agent that has already
bootstrapped needs no token: its credentials are on the fleeger-agent-data
volume. On a first start, add the token's --env-file fleeger-agent.env as
above.
Verifying
Dashboard → Locations: the card shows reachable with a recent "last seen".
Open the location → Resources: the
proxmox_nodereports, and each VM/CT appears as an auto-discovered read-only sub-resource.A VMID is unique only within its cluster, so each guest is keyed on its cluster's name as well: two clusters in one location that both have VM 100 show two resources. A node in no cluster keys its guests on its own registration. So register a cluster by any one of its nodes (or several: they share the guests), and give two clusters in one location different names. A node that later joins a cluster, or a renamed cluster, keeps its guests' resources. If the agent cannot read
/cluster/status, it still reports metrics but no guests, and the node's resource shows the collect errorcannot tell which cluster it belongs to.Nothing after a minute or two? Work through checking reachability. The two most common Proxmox-specific causes:
- TLS error in the agent log → the allow invalid certs box wasn't ticked (step 3), or you're pointing at a name the cert doesn't cover.
- 403 Forbidden → the token is missing audit rights, or privsep is on and
the ACL was granted to the user instead of the token (step 2's
--privsep 1note). Note agent logs live on the remote host — they are not shipped to the hub. - Metrics stopped after a Proxmox major upgrade (e.g. 8 → 9) → the token's
effective privileges changed with the Proxmox version. Re-check the token
against the version table:
PVE 9 removed
VM.Monitor, so a custom role that listed it can lose coverage on upgrade. Fastest fix is to (re-)grant built-inPVEAuditor, which Proxmox keeps correct across versions.
Reference
Self-signed TLS
Proxmox's :8006 API uses a self-signed certificate out of the box. Fleeger
gives you a per-resource Allow invalid/self-signed TLS certs toggle (the
allow_invalid_certs flag on the proxmox_node resource). Ticking it tells the
agent's HTTP client to skip certificate verification for that endpoint only.
For a LAN-local homelab that's the normal choice. If you'd rather keep verification on, install a certificate the agent trusts on the Proxmox host (e.g. via the built-in ACME/Let's Encrypt integration, using a DNS name the agent then uses as the Address) and leave the box unticked.
Standalone binary
The Standalone onboarding option runs spoke-agent --config …, but there is
no separately-published binary artifact — only the container images are
published (container images). Build it from
the repo:
cargo build -p spoke-agent --release # → target/release/spoke-agentThen run it with a small TOML config, exactly as onboarding → Standalone shows. For most homelabs the Docker option is less fuss.
See also
- Onboarding a location — the agent install mechanics (Docker / Kubernetes / Standalone) in full.
- Adding a resource — the resource form.
- Managing credentials — reuse, rotation, cleanup.
- Controlling a Proxmox VM — the opt-in power token (a superset of this monitoring token's rights).
- Checking reachability — what "reachable" means and how to debug it.