# Easy Proxmox (by RenΓ© Bachmann)
[](
https://my.home-assistant.io/redirect/hacs_repository/?repository_url=https://git.bahmcloud.de/bahmcloud/easy_proxmox
)
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 via HACS (Recommended)
To install Easy Proxmox through HACS:
1. **Ensure HACS is already installed** in your Home Assistant instance.
If not, follow the official guide: https://hacs.xyz/
2. Open **HACS β Integrations**.
3. Click the **ββ―β (three dots)** β **Custom repositories**.
4. Add the following repository:
- Repository URL:
```
https://git.bahmcloud.de/bahmcloud/easy_proxmox
```
- Category: **Integration**
- Version: **Tags (recommended)**
5. Click **Add**, then locate **Easy Proxmox** in the HACS list and click **Install**.
6. After installation, **restart Home Assistant**.
7. Go to **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: `pam` or `pve`
- 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:
### 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
---
## π Services & Automations (since v0.7.0)
Easy Proxmox provides Home Assistant services so you can fully control your VMs and containers in automations and scripts without using buttons or switches.
Available services:
| Service | Description |
|--------|------------|
| `proxmox_pve.start` | Start a VM or container |
| `proxmox_pve.shutdown` | Gracefully shutdown a VM or container |
| `proxmox_pve.stop_hard` | Hard stop a VM or container |
| `proxmox_pve.reboot` | Reboot a VM or container |
All services are **multi-host aware** and automatically select the correct Proxmox server.
### β
Recommended usage: Device based
This is the safest and easiest way, especially for multi-host setups.
In an automation or script:
```yaml
service: proxmox_pve.shutdown
target:
device_id: YOUR_DEVICE_ID
```
In the UI, you can simply select the VM/CT device from the dropdown.
Home Assistant will automatically:
- Find the correct Proxmox host
- Find the correct node
- Execute the action
### π§ Manual usage: Node / VMID based
You can also call services manually:
```yaml
service: proxmox_pve.reboot
data:
node: pve1
vmid: 100
type: qemu
```
If you have multiple Proxmox servers configured, you should also specify one of:
```yaml
host: 192.168.178.101
```
or
```yaml
config_entry_id: 8d9f2e7b1c3d4a5f...
```
This avoids ambiguity.
### π§ Resolution priority
When a service is called, Easy Proxmox resolves the target in this order:
1. `config_entry_id`
2. `device_id`
3. `host`
4. Guest lookup by `node + vmid + type`
If a guest exists on multiple Proxmox hosts, the call fails and asks for clarification.
### π Example automations
Shutdown all test systems at night:
```yaml
alias: Stop Test VM at Night
trigger:
- platform: time
at: "23:00:00"
action:
- service: proxmox_pve.shutdown
target:
device_id: 123456abcdef...
```
Start a VM when electricity price is low:
```yaml
alias: Start VM on cheap power
trigger:
- platform: numeric_state
entity_id: sensor.power_price
below: 0.20
action:
- service: proxmox_pve.start
target:
device_id: 123456abcdef...
```
### 𧩠Why this matters
With services you can:
- Fully automate your Proxmox infrastructure
- Remove dependency on dashboard buttons
- Build power-saving or maintenance automations
- Control multiple Proxmox clusters cleanly
---
## 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 |
---
## Support & Contributing
If you need help, open an issue in GitHub.
Want to contribute? Feel free to submit PRs!
---
**Easy Proxmox aims to provide a complete Proxmox VE experience in Home Assistant.**
See [CHANGELOG.md](CHANGELOG.md) for full version history.
Releases: https://git.bahmcloud.de/bahmcloud/easy_proxmox/releases