Home Lab Projects

How to Monitor Proxmox From Home Assistant

Monitor a Proxmox host and its VMs from Home Assistant with a read-only API token, then add power controls and handle self-signed certificates.

On this page
  1. Choose an integration
  2. Before you connect
  3. Create a dedicated user and API token
  4. Connect Home Assistant
  5. Optional: Home Assistant OS in a VM
  6. Alerts worth setting up first
  7. Backups
  8. Common mistakes

Proxmox VE runs virtual machines and containers on one host. Home Assistant can show the health of that host and its guests, and it can alert you when a guest stops. This guide covers the integration options, a read-only account to create first, and the certificate and power-control settings that need care.

Choose an integration

Home Assistant’s core Proxmox VE integration has offered limited data, and what it exposes depends on your Home Assistant version. Check its current documentation before you rely on it.

Many people use the Proxmox VE custom integration from HACS instead. It adds CPU, memory, disk and uptime sensors for each node, and for each VM and container. It also adds buttons to start, stop, shut down and reboot guests. Because it’s a custom integration, Home Assistant doesn’t maintain it, and it can break after an update.

Other options:

  • The Glances integration reports host metrics, if you run Glances on the Proxmox host.
  • Prometheus with prometheus-pve-exporter collects detailed metrics, but you have to run Prometheus.

Start with read-only access, and add power controls only when you need them.

Before you connect

Proxmox’s web interface and API listen on port 8006 over HTTPS. A new installation uses a self-signed certificate by default.

Give the Proxmox host a static IP address or a DHCP reservation, so Home Assistant keeps finding it.

If Home Assistant runs on the Proxmox host you want to monitor, it can’t alert you when that host goes down. Monitor the host from somewhere else as well. Uptime Kuma on a separate machine is one option.

Create a dedicated user and API token

Don’t connect with root@pam. Create a separate user for Home Assistant, for example homeassistant@pve.

  1. In the Proxmox web interface, go to Datacenter > Permissions > Users and add the user.
  2. Go to Datacenter > Permissions, add a permission for that user at path /, and select the built-in PVEAuditor role. This role is read-only.
  3. Go to Datacenter > Permissions > API Tokens and create a token for the user.

With privilege separation on, the token has no rights until you grant them to the token itself. Granting rights to the user isn’t enough, so assign the read-only role to the token as well.

For power control, create a custom role that contains everything in PVEAuditor plus the VM.PowerMgmt privilege. Assign it only to the paths that need it. A token with full privileges can delete VMs, so keep every role as narrow as the features you use.

Connect Home Assistant

Install the HACS integration, restart Home Assistant, then go to Settings > Devices & services and add the Proxmox VE integration. Enter the host name or IP address, port 8006, and the token ID and secret. Field names vary between integration versions, so follow the prompts on screen.

A self-signed certificate fails verification. You have two choices:

  • Install a certificate that your Home Assistant host trusts.
  • Turn off certificate verification in the integration.

Turning verification off removes a check on the connection. Use it only on a network you control, and prefer a trusted certificate when you can.

Optional: Home Assistant OS in a VM

Home Assistant OS in a virtual machine is the route the Home Assistant documentation describes for Proxmox. Community helper scripts can build the VM for you. The community-scripts project, formerly tteck’s scripts, is one option. Read any script before you run it as root on your host.

When you build the VM by hand, these settings are a common starting point:

  • The q35 machine type with the OVMF (UEFI) BIOS.
  • Two vCPUs, 4 GB of RAM and a 32 GB disk are a comfortable starting point.
  • The QEMU Guest Agent option turned on. Home Assistant OS includes the agent, which allows clean shutdowns and IP reporting.

If you use a Zigbee or Z-Wave USB stick, pass it through by vendor and product ID rather than by USB port. It then keeps working after the stick is unplugged and replugged.

Alerts worth setting up first

Start with a few simple alerts:

  • A guest stopped. Use a state trigger on the VM’s or container’s status entity, and notify when it leaves the running state.
  • Sustained high memory or disk use. Use a trigger with a for: duration, so a brief spike doesn’t send an alert.

Backups

Proxmox backups (vzdump) don’t replace Home Assistant backups. Proxmox backs up the whole VM. Home Assistant’s own backups hold its configuration and add-on data, so keep both.

Common mistakes

  • Connecting with root@pam. Use a dedicated user and a read-only token.
  • Running Home Assistant in an LXC container. The Home Assistant OS VM route is the one the project documents, so use a VM.
  • Expecting CPU and memory graphs from the core integration. Use the HACS integration or Glances for host metrics.
  • Relying on Home Assistant to report a host outage. An outage on the same host also silences Home Assistant.

The complete guide to home lab projects

Self-Hosted Apps That Integrate With Home Assistant: Immich, Donetick and TeslaMate
Read the guide

Keep exploring

Guides from other topics

All topics →