ThisCalculator

Everyday

Proxmox Home Assistant Integration: Lab Monitoring Guide

Updated · Standard formula, shown below

Proxmox Home Assistant Integration: Lab Monitoring Guide

This guide shows you how to connect Proxmox VE to Home Assistant so you can monitor your virtual machines, containers, and host resources directly from your Home Assistant dashboard. You’ll be able to see CPU, memory, disk, and network usage, plus start, stop, and reboot VMs or containers with a single click. Before starting, you need a working Proxmox VE server (version 6 or newer) and a Home Assistant installation (either Home Assistant OS, Supervised, Container, or Core) that can reach the Proxmox host over your network.

What You’ll Need

  • Proxmox VE server with a web interface accessible at https://:8006
  • A user account on Proxmox with API access (we’ll create a dedicated one)
  • Home Assistant instance with the ability to install integrations (via Settings > Devices & Services)
  • Network connectivity between Home Assistant and Proxmox (both on the same LAN or reachable via firewall rules)
  • Basic familiarity with the Proxmox web UI and Home Assistant configuration files

Step-by-Step

  1. Create a Proxmox API user (optional but recommended). In the Proxmox web interface, go to Datacenter > Permissions > Users and click Add. Create a user like homeassistant with a strong password. Then go to Groups and create a group (e.g., monitoring) and add the user to it.
  2. Assign permissions to the user. Go to Permissions > Add and choose Group Permission. Select the group, set Path to / (or a specific VM/CT pool), and give the role PVEVMUser (or PVEAdmin if you need full control). This allows reading metrics and managing VMs/CTs. For read-only monitoring, PVEVMUser is sufficient.
  3. Generate an API token. In Proxmox, click on your user (top right) > API Tokens > Add. Give it a name like homeassistant, set an expiration date (or leave blank for no expiry), and check Privilege Separation (recommended). Copy the token ID (e.g., homeassistant@pve!homeassistant) and the secret immediately – you won’t see the secret again.
  4. Install the Proxmox integration in Home Assistant. In Home Assistant, go to Settings > Devices & Services > Add Integration and search for “Proxmox VE”. Select it.
  5. Enter the connection details. In the setup dialog:
    • Host: IP address or hostname of your Proxmox server (e.g., 192.168.1.10).
    • Port: 8006 (default).
    • Username: the full API token ID (e.g., homeassistant@pve!homeassistant).
    • Password: the API token secret (not the user password).
    • Verify SSL: If you use a self-signed certificate (default), leave this unchecked. If you have a valid certificate, check it.
    • Node: The name of your Proxmox node (e.g., pve). You can find it in the top left of the Proxmox web UI.
  6. Choose what to monitor. After connecting, the integration will ask which resources to track. You can select the node itself (for host CPU, memory, etc.) and then add individual VMs and containers by their VM ID. You can also add them later via the integration’s options.
  7. Finish the setup. Home Assistant will create sensors for each selected resource. You’ll see entities like sensor.proxmox_cpu_usage, sensor.proxmox_memory_usage, and for each VM, binary_sensor.proxmox_vm_status (running/stopped) and switch.proxmox_vm (to power on/off).
  8. Add a dashboard card. Go to your dashboard, click the pencil icon to edit, add a new card, and choose the entities you want to display. For a quick overview, use the “Entities” card and list the sensors. For more advanced automation, use the switches in a “Grid” or “Picture Elements” card.
  9. Create automations. For example, to turn off a VM when your home is in “Away” mode, go to Settings > Automations and create a new automation with a condition like state('binary_sensor.proxmox_vm_status') == 'on' and an action to turn off the switch.

Common Mistakes

  • Using the wrong credentials. The integration expects the API token ID and secret, not the user’s password. Double-check you copied the full token ID including @pve!tokenname.
  • SSL verification enabled with self-signed cert. Proxmox uses a self-signed certificate by default. If you check “Verify SSL” without adding the certificate to Home Assistant’s trust store, the connection will fail. Leave it unchecked unless you have a proper certificate.
  • Incorrect node name. The node name is case-sensitive and must match exactly what appears in the Proxmox web UI (e.g., pve or proxmox). If you get an error like “Node not found”, verify the name.
  • Permissions too restrictive. If you only give the user PVEAuditor role, you can read metrics but cannot control VMs. To use switches, you need PVEVMUser or higher.
  • Not updating the integration after adding new VMs. If you add a new VM to Proxmox, you need to go to the integration’s options and add the VM ID to the monitored resources list.

Tips

  • Use a dedicated API token with limited permissions. This is safer than using your root user. If the token leaks, the attacker only has control over VMs, not the whole Proxmox cluster.
  • Monitor both the host and the VMs. The host sensors give you overall resource usage, while VM sensors tell you which specific VM is causing high load.
  • Create a Lovelace view with badges. Use the “Markdown” card to show a summary of all VMs with status icons, using the state of the binary sensors.
  • Set up automations for resource alerts. For example, send a notification if CPU usage on the host exceeds 90% for 5 minutes. Use the numeric_state trigger.
  • Back up your Home Assistant configuration. Before making major changes, take a snapshot. The integration stores its configuration in .storage, but it’s still good practice.

Troubleshooting

  • Connection refused / timeout. Check that Home Assistant can reach the Proxmox host on port 8006. Try curl -k https://:8006 from a terminal on the Home Assistant machine. If it fails, check the firewall on Proxmox (it should allow 8006 from your LAN).
  • Authentication error. Verify the API token ID and secret. Recreate the token if necessary. Also ensure the token is not expired and that the user is not disabled.
  • “Node not found” error. Go to the Proxmox web UI and look at the top left corner – the node name is shown there (e.g., pve). Enter it exactly.
  • Sensors show “Unavailable”. This usually means the integration lost connection. Check the Home Assistant logs (Settings > System > Logs) for errors. Restart Home Assistant or re-enter the integration details.
  • Switches don’t work. If the switch toggles but the VM doesn’t change state, the API token may lack the VM.Power privilege. Re-check the permissions: the role must be PVEVMUser or PVEAdmin.
  • Data not updating. The integration polls Proxmox every 30 seconds by default. If you need more frequent updates, you can adjust the scan interval in the integration’s options, but be aware that too frequent polling can load the Proxmox API.

Frequently Asked Questions

  1. Can I monitor multiple Proxmox nodes? Yes, you can add the integration multiple times, each with a different node name. However, you’ll need separate API tokens if the nodes are in different clusters.
  2. Does this integration work with Proxmox Backup Server? No, the integration is for Proxmox VE only. For backups, you’d need a separate integration or use the Proxmox API directly.
  3. Can I use this to start/stop VMs based on Home Assistant presence? Absolutely. Create an automation that triggers when you leave home (e.g., using the mobile app) and turns off selected VMs, and another to turn them on when you return.
  4. Is it possible to see the VM’s IP address? The integration does not expose IP addresses directly. You can use the Proxmox API to fetch that, but you’d need a custom template or use the rest_command to query it.
  5. Why do I see two sensors for the same VM (one as switch and one as binary_sensor)? The switch controls power state, while the binary_sensor reports the current state. They are complementary; you can use one or both.
  6. Can I monitor LXC containers as well? Yes, the integration works with both QEMU VMs and LXC containers. When adding resources, you’ll see both types listed by their VM ID.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.