Easy Proxmox (by René Bachmann)

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://github.com/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: <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

---

🚀 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:

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:

service: proxmox_pve.reboot
data:
  node: pve1
  vmid: 100
  type: qemu

If you have multiple Proxmox servers configured, you should also specify one of:

host: 192.168.178.101

or

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:

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:

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 for full version history.

Releases: https://github.com/bahmcloud/easy_proxmox/releases