← Back to dashboard

Proxmox VE Integration

What is it?

The Proxmox VE integration connects the dashboard to one or more Proxmox Virtual Environment nodes or clusters via the Proxmox REST API. It adds a Proxmox tab to the dashboard where you can see all your QEMU VMs and LXC containers, check resource usage, and start, stop, or reboot them — without opening the Proxmox web UI.

Use cases

• Unified on-prem + cloud view — see Proxmox VMs alongside AWS EC2, Azure VMs, and GCP instances in a single dashboard without switching between tools.
• Lab and homelab management — start and stop VMs before a demo or test session from the same interface used for cloud resources.
• Multi-node visibility — view all VMs and containers across every node in a Proxmox cluster, grouped by node, from one screen.

Prerequisites

Setup

Step 1 — Create an API token (recommended)

API tokens are the preferred auth method: they are revokable, auditable, and do not require session management.

1. Log in to the Proxmox web UI → Datacenter → Permissions → API Tokens → Add.
2. Select the user (e.g. root@pam), enter a Token ID (e.g. dashboard), and uncheck Privilege Separation if you want the token to inherit the user's full permissions.
3. Click Add and copy the Token Secret — it is shown only once.

The full token identifier shown in Proxmox is USER@REALM!TOKENID (e.g. root@pam!dashboard). In the dashboard, enter: - Username: root@pam - Token ID: dashboard - Token Secret: the UUID shown after creation

Step 2 — Grant the API token read and power permissions

The minimum required privileges on the / path (or the relevant pool):

Assign via Datacenter → Permissions → Add → API Token Permission: - Path: / - Token: root@pam!dashboard - Role: PVEVMAdmin (includes all of the above) or a custom role

Step 3 — Enable and configure in the dashboard

Option A — Settings → Integrations → Proxmox VE

Toggle Proxmox VE on. Fill in the connection fields:

Click Save. No container restart is required.

Step 4 — Verify

The Proxmox link appears in the navigation bar. Click it — you should see your nodes as tabs and all VMs and containers listed within a few seconds.

What it enables in the dashboard

Templates are automatically hidden from the resource list.

Password auth (alternative)

If you cannot create an API token, you can authenticate with a username and password instead. Leave Token ID and Token Secret blank and set Password. Note that password auth creates a ticket that expires; the dashboard will re-authenticate on each request, which is slightly slower and adds one API call per operation.

PROXMOX_USER=root@pam
PROXMOX_PASSWORD=<your-root-password>

Cluster vs single-node setup

The integration works identically for a single-node Proxmox installation and a full Proxmox cluster. Point PROXMOX_HOST at any node in the cluster — Proxmox returns resources across all cluster members from any single node's API. The node tabs in the UI reflect the actual cluster topology.

IP address display (QEMU guest agent)

The VM detail panel shows IP addresses when the QEMU Guest Agent is installed and running inside the VM. Without it, IP addresses cannot be read from the API.

To install the agent inside a Debian/Ubuntu VM:

apt-get install -y qemu-guest-agent
systemctl enable --now qemu-guest-agent

Then enable it in Proxmox: VM → Options → QEMU Guest Agent → Enabled.

Troubleshooting

Proxmox tab is missing — verify PROXMOX_ENABLED=true and that the stack restarted after the change (or that you saved via Settings → Integrations).

"PROXMOX_HOST is not configured" — the host field is required. Set it in Settings → Integrations → Proxmox VE.

"Connection refused" or timeout — confirm port 8006 is reachable from inside the container:

docker compose exec app curl -sk https://proxmox.local:8006/api2/json/version

If the request times out, check firewall rules between the Docker host and the Proxmox node.

"401 Unauthorized" — the token ID or secret is incorrect, or the token has been deleted. Regenerate the token in Proxmox → Datacenter → API Tokens.

"403 Forbidden" on power operations — the API token lacks VM.PowerMgmt. Reassign the token to a role that includes that privilege (e.g. PVEVMAdmin).

SSL certificate errors — for self-signed certificates, set PROXMOX_VERIFY_SSL=false. For production with a valid cert, set it to true.

IP addresses not showing — install and enable the QEMU Guest Agent inside the VM and ensure QEMU Guest Agent is checked under VM → Options in the Proxmox UI.

Multiple connections

Connection details used to live in Settings as a single set of fields, so there could only ever be one Proxmox cluster. They now live in the Connections page (/connections), which holds as many as you like — a second Proxmox cluster at another site, or the same one under a read-only and a privileged service account.

• The default connection is what every page and API call uses when not told otherwise. The first connection of a kind becomes the default automatically.
• Pass ?connection_id=<id> to any /api/proxmox endpoint to target a specific one.
• Job-backed operations (deploys, power verbs) record the connection at enqueue, so changing the default while one is queued cannot redirect it.

Your existing Settings values were copied into the first connection on upgrade. The old panel is still there, read-only, with a banner pointing here — editing it no longer changes what the dashboard connects to. It is kept so that rolling back to a previous image still works.

Over a remote agent

A Proxmox cluster the dashboard has no network route to can be reached through a remote agent instead. Tick Reached through a remote agent when adding the connection and give it the name that connection has in the agent's own connections.yaml.

The dashboard then stores no host and no credential for it — only the name. The agent uses the /api2/json REST API with an API token, which needs no dependency the agent does not already have.

Three separate grants must line up: the dashboard grants the agent the agent_hypervisor job type, your policy.yaml grants the individual verbs on that connection, and your connections.yaml defines it. Withhold any one and nothing runs.

When the connection is reached through an agent

The dashboard has no route to an agent-bound connection — that is the point of binding it to an agent — so this page cannot query it live. It shows the last synced inventory instead, with a banner saying so and how old it is. Live-only figures (CPU usage, uptime, disk) are blank there rather than zero: they were never measured, and a fabricated 0 is worse than an empty cell.

Power actions still work: they are dispatched to the agent as jobs and appear on /jobs with Live Output, exactly like a discovery scan. Every button this page offers — Start, Stop, Shutdown and Reboot — maps to a verb, so nothing here is refused; see the verbs for how the other products differ.

One upgrade note: Shutdown and Reboot use the shutdown and reboot verbs, which are newer than the agent image many installs are running. Until an agent is re-pulled it refuses them by name in Live Output, pointing at its policy.yaml.