Proxmox Agent

Proxmox Agent

The Proxmox agent watches one Proxmox VE cluster and reports VMs and LXC containers grouped by node.

Run one Proxmox agent per cluster.

The agent is read-only. It uses a Proxmox API token with PVEAuditor rights and performs GET requests.

Where it runs

The Proxmox agent does not need to run on a Proxmox node.

It can run from:

• the Trove server host
• a NAS
• a small VM
• any Linux box/container that can reach the Proxmox API

TROVE_PROXMOX_URL should point to the Proxmox API as seen from wherever the agent runs.

Create a read-only Proxmox token

Run on any Proxmox node:

pveum user add trove@pve --comment "Trove read-only catalog agent"
pveum aclmod / --users trove@pve --roles PVEAuditor
pveum user token add trove@pve trove-agent --privsep 0

The token format for Trove is:

trove@pve!trove-agent=PROXMOX_TOKEN_SECRET

The privilege separation footgun

--privsep 0 is required.

If privilege separation is enabled, the token can authenticate but may inherit no useful permissions. The agent can look healthy while returning zero nodes and zero guests.

If you create the token in the Proxmox UI, uncheck "Privilege Separation".

Verify the Proxmox token

Run this from the host that will run the agent:

PVE_TOKEN='trove@pve!trove-agent=PROXMOX_TOKEN_SECRET'
curl -sk -H "Authorization: PVEAPIToken=${PVE_TOKEN}" \
  https://YOUR-PVE-HOST:8006/api2/json/nodes

Expected: JSON with node data.

Bad sign:

{"data":[]}

That usually means permissions are missing.

Run the agent

docker run -d --name trove-agent-proxmox --restart unless-stopped \
  -e TROVE_SERVER_URL=http://YOUR-SERVER:8080 \
  -e TROVE_TOKEN=AGENT_TOKEN_VALUE \
  -e TROVE_PROXMOX_URL=https://YOUR-PVE-HOST:8006 \
  -e TROVE_PROXMOX_TOKEN='trove@pve!trove-agent=PROXMOX_TOKEN_SECRET' \
  -e TROVE_PROXMOX_INSECURE=true \
  ghcr.io/techdox/trove-agent-proxmox:latest

Use TROVE_PROXMOX_INSECURE=true for the default self-signed Proxmox certificate. Remove it if your Proxmox API has a trusted certificate.

Configuration

Variable	Default	Purpose
TROVE_SERVER_URL	required	Base URL of the Trove server.
TROVE_TOKEN	required	Trove agent token.
TROVE_PROXMOX_URL	required	Proxmox API base URL.
TROVE_PROXMOX_TOKEN	required	Proxmox API token in USER@REALM!TOKENID=SECRET format.
TROVE_PROXMOX_INSECURE	false	Accept self-signed TLS certificates.
TROVE_INTERVAL	30s	Push interval.

What appears in Trove

Each Proxmox node appears as a host.

VMs report as vm services. LXCs report as lxc services.

Templates are skipped.

The image/OS column uses the guest OS type from Proxmox config where available. Trove does not require the QEMU guest agent.

Running guests are healthy; stopped guests are neutral with health=unknown and Guest is stopped detail. Trove does not guess which guests are supposed to be running. Live CPU, memory, disk, and uptime are shown as detail/labels for investigation, but high utilization does not create a health incident by itself.

Host headers include Proxmox version metadata when the API exposes it.

Common mistakes

Wrong agent image

Use:

ghcr.io/techdox/trove-agent-proxmox:latest

Do not use the Docker agent image with Proxmox environment variables. The Docker agent will ignore TROVE_PROXMOX_*, connect to Docker instead, and make the dashboard confusing.

Two different tokens

There are two tokens:

Token	Variable	Format
Trove agent token	TROVE_TOKEN	trove_...
Proxmox API token	TROVE_PROXMOX_TOKEN	user@realm!tokenid=secret

Do not swap them.

Agent reports zero hosts

Check:

• PVEAuditor role exists on /
• token was created with --privsep 0
• token string includes both token ID and secret
• URL is reachable from the agent container
• TROVE_PROXMOX_INSECURE=true is set for self-signed TLS