---
title: "Homarr Integration — Proxmox"
aliases: [homarr-proxmox, proxmox-homarr-integration]
tags: [homarr, proxmox, homelab, integration, monitoring]
sources: [raw/Homarr documentation 1.md]
created: 2026-04-19
updated: 2026-04-19
---

## Overview

Homarr integrates with Proxmox VE to display system health and status via the **Health Monitoring** widget. Authentication uses Proxmox API tokens, not username/password.

## Credential Fields

| Field | Description |
|-------|-------------|
| Username | Account username (e.g. `api`) |
| Token ID | Token name (e.g. `homarr`) |
| Realm | Auth realm — almost always `pve` |
| API Key | Secret shown once at token creation |

> **Warning:** Linux PAM (`pam`) realm may not work with the Proxmox API. Always use the **Proxmox VE** realm (`pve`) when creating the API user.

### Credential Format Splitting

Proxmox sometimes shows credentials as `api@pve!homarr` — split this for Homarr:
- **Username:** `api`
- **Realm:** `pve`
- **Token ID:** `homarr`

## Creating the API Token in Proxmox (Step-by-Step)

1. **Datacenter → Permissions → Groups** — Create a group (e.g. `api-users`)
2. **Datacenter → Permissions** — Add Group Permission:
   - Path: `/`
   - Group: `api-users`
   - Role: `PVEAuditor`
   - Propagate: ✓
3. **Datacenter → Permissions → Users** — Add a new user
4. **Datacenter → Permissions → API Tokens** — Add token:
   - User: the user created above
   - Token ID: `homarr` (or any descriptive name)
   - Privilege Separation: **unchecked**
5. **Copy the Secret immediately** — it is shown only once
6. **Datacenter → Permissions** — Add API Token Permission:
   - Path: `/`
   - API Token: token from step 4
   - Role: `PVEAuditor`
   - Propagate: ✓

## Adding to Homarr

Follow the standard [[wiki/homelab/homarr-integrations|Homarr Integrations]] workflow (Manage → Integrations → New), then enter the four credential fields above.

## Widget

The Proxmox integration powers the **System Health Monitoring** widget — displays CPU, memory, and status for nodes/VMs/containers.

## Key Takeaways

- Use `PVEAuditor` role — read-only, least privilege for a dashboard
- Set **Privilege Separation: unchecked** so the token inherits the user's permissions directly
- Split `user@realm!tokenid` format into three separate fields in Homarr
- Save the API secret at creation — Proxmox will not show it again
- Realm must be `pve`, not `pam` — PAM auth is unreliable with the API

## Related

- [[wiki/homelab/homarr-integrations|Homarr Integrations — Third-Party App Connections]]
- [[wiki/homelab/proxmox-install-setup-2025|Proxmox VE — Install & Setup from Scratch (2025)]]
- [[wiki/homelab/homarr-docker-stats|Homarr Docker Stats Widget — Container Resource Monitoring]]
