A powerful Home Assistant integration to monitor and control Proxmox VE. With Easy Proxmox you can monitor nodes, VMs and containers directly in Home Assistant, start/stop/reboot guests and display detailed system metrics.
Features
Per Node
- CPU usage (%)
- Load Average (1 minute)
- RAM Used / Total / Free (MB)
- Swap Used / Total / Free (MB)
- Storage (RootFS):
- Used / Total / Free (GB, 3 decimals)
- Uptime (days, hours, minutes)
Per VM / Container
- Status (running, stopped, etc.)
- CPU usage (%)
- RAM usage (MB)
- Uptime (days, hours, minutes)
- Network In / Out (MB)
- IP address (preferred IP is configurable)
- Power Switch:
- ON = Start
- OFF = Shutdown (soft)
- Buttons:
- Reboot
- Stop (hard)
Dynamic Behavior
- New VMs/CTs appear automatically
- Deleted VMs/CTs are fully removed (no “ghost devices”)
- Renames are applied live
- Options are applied live (no restart required)
Installation
-
Create the folder: /config/custom_components/proxmox_pve/
-
Copy all integration files into that folder.
-
Restart Home Assistant.
-
Add the integration:
Settings → Devices & Services → Add Integration → Easy Proxmox
Proxmox: Create User & API Token
1) Create a User
In the Proxmox Web UI:
Datacenter → Permissions → Users → Add
Example:
- Username:
homeassistant - Realm:
pamorpve - Set a password (only for management; the token will be used for API access)
2) Create an API Token
Datacenter → Permissions → API Tokens → Add
- User:
homeassistant@pve - Token ID:
easyproxmox - Privilege Separation: disabled (important!)
- Create → copy & store the Token Secret
You will get:
Token Name: homeassistant@pve!easyproxmox
Token Secret: <long secret string>
3) Assign Permissions (Admin Rights)
To ensure full functionality (monitoring + guest controls), assign admin rights:
Datacenter → Permissions → Add
- Path:
/ - User:
homeassistant@pve - Role:
PVEAdmin
This allows the integration to:
- read node status
- read VM/CT status
- start/stop/shutdown/reboot guests
- query QEMU Guest Agent (for IP discovery)
Set Up the Integration in Home Assistant
When adding the integration, you will be asked for:
| Field | Meaning |
|---|---|
| Host | IP address or hostname of your Proxmox server |
| Port | Default: 8006 |
| Verify SSL | Enable only if your certificate is valid/trusted |
| Token Name | e.g. homeassistant@pve!easyproxmox |
| Token Secret | The generated API token secret |
After saving:
- One device is created per Proxmox node
- VM/CT devices are linked below their node device
Options (Gear Icon)
After setup, open: Settings → Devices & Services → Easy Proxmox → Options (gear icon)
Polling Interval
How often data is fetched from Proxmox.
| Value | Description |
|---|---|
| 5 seconds | Very fast, higher API load |
| 10–20 seconds | Recommended |
| >30 seconds | Lower API load |
Changes are applied immediately (no restart required).
IP Preference Mode
Controls which IP is shown as the “primary” IP for a guest:
| Mode | Description |
|---|---|
| prefer_192168 | Prefer 192.168.x.x |
| prefer_private | Prefer private networks (10.x, 172.16–31.x, 192.168.x) |
| any | Use the first available IP |
| custom_prefix | Use a custom prefix |
Custom IP Prefix
Only relevant if custom_prefix is selected.
Examples:
10.0.192.168.178.172.20.
This allows you to force a specific subnet to be selected as the guest’s preferred IP.
Recommended Network Configuration
For reliable guest IP detection:
- Enable QEMU Guest Agent in VMs
- Ensure the guest receives valid IPs (DHCP/static)
- If only loopback/link-local addresses exist, no useful IP can be selected
Device Structure in Home Assistant
Easy Proxmox └── Proxmox Node pve1 ├── CPU ├── RAM Used / Free / Total ├── Swap Used / Free / Total ├── Storage Used / Free / Total ├── Uptime └── VM: HomeAssistant (VMID 100) ├── Status ├── CPU ├── RAM ├── Network In / Out ├── IP ├── Power Switch ├── Reboot Button └── Stop (hard) Button
Security Notice
The API token has admin rights. Treat it like a root password:
- never share it publicly
- store it only in Home Assistant
- revoke and regenerate it if compromised
Troubleshooting
| Issue | Fix |
|---|---|
| Integration won’t load | Check logs: Settings → System → Logs |
| No IP shown | QEMU Guest Agent missing OR IP preference mode not matching your subnet |
| Buttons don’t work | Check Proxmox permissions (PVEAdmin role) |
| Old devices remain | Fully cleaned up automatically since version 0.4.1 |
License / Support
Look into LICENSE file.
Easy Proxmox aims to provide a complete Proxmox VE experience in Home Assistant.