proxmoxve: a custom Proxmox VE integration for Home Assistant

Why a second Proxmox integration exists

This integration began as the maintainer's own custom integration for Home Assistant, built on the Home Assistant core integration for Proxmox VE, and it has grown well beyond it. When you install it, it replaces the core one. The architectural decision that makes it different is that everything goes through the Proxmox API with the credentials you provide. Nothing is installed on the nodes, with a single exception: PVE-mods, and only if you want hardware temperatures. That exception matters for the security conversation, because it is the difference between an integration that holds a token and reads data, and one that asks for root level changes on every hypervisor in your house. The project is MIT licensed, publishes numbered releases such as 5.3.4 on 2026-10-12, and its last push was on 2026-10-19, so the integration is actively being changed alongside Proxmox itself.

What the entity tree covers

The coverage is broad enough that the interesting detail is the grouping. At cluster level you get nodes online, guests running, CPU and memory across the cluster, plus HA status, backup coverage and Ceph health when the optional cluster credentials are supplied, and shared storage shown as a single device. Per node there is status, CPU, memory, swap, disk, IO delay, load average and version, package updates surfaced as a Home Assistant update entity, the last backup and failed tasks, replication, subscription and certificate expiry, and optionally hardware temperatures, fans and voltages through PVE-mods along with physical disks reported with SMART and ZFS pools. Guests, meaning virtual machines and containers, report status with QEMU's finer run states, CPU both on their own and as a share of the host, memory, disk from the guest agent, network, uptime and even a file read from inside the guest. Storage reports capacity along with the active, enabled and shared flags, per node for local storage and once for shared. A file read from inside a guest is the detail that suggests what this integration is for, monitoring rather than a management console.

Buttons for guests and a backup action built on vzdump

The action surface is where a monitoring integration starts to become a management tool. For each guest there are buttons for start, stop, shutdown, reboot, suspend, resume, hibernate, reset, unlock, snapshot and backup. At node level you get bulk start, stop, suspend and backup, plus Wake on LAN, arm and disarm HA, and an action called proxmoxve.backup that carries all of vzdump's options. Taking vzdump's options rather than a simplified subset is the right call for anyone who has configured a backup job before, since the parameters people actually use are the ones the tool already knows. The buttons and the action are subject to the same permission model as everything else: the integration shows a button only where the privilege exists, and when something is missing, the repair it offers names the missing privilege rather than failing with a generic error.

Token authentication, realms and the two-field configuration

Adding the integration is done through the user interface, and the credential model has a few sharp edges worth reading before you start. The tip in the documentation is to use token based authentication for greater integration stability. When you do, you enter the token's name in the Token name field, which is the part after the ! in what Proxmox shows as Token ID, so homeassistant from homeassistant@pve!homeassistant, and the secret value in the password field. Pasting the full user@realm!name also works, because the user and the realm are taken from their own fields. To use user based authentication only, you leave the Token name field empty. The realm field is the other trap: it offers pam for Linux users and pve for users created inside Proxmox as a pick list, while an LDAP, Active Directory or OpenID realm has to be typed into the same field, and getting it wrong means the credentials are silently wrong rather than obviously wrong. The project points you at Datacenter, Permissions, Users and the Realm column in Proxmox to confirm the value.

Failover, discovery and nodes that were off overnight

The behaviour documentation covers the situations that separate a good integration from a working one, and the project also lists what it cannot test. There is optional automatic discovery of everything the credentials can see, so the integration can build its entity tree from the cluster rather than from a hand written list. There is failover to another cluster node when the configured one goes down, and no re-authentication is required after a node was off overnight, which is the kind of edge case that produces a flood of false alerts when a laptop-sized server is rebooted. The credential model follows from the same design: since the API is the only channel, a node that is off does not break the integration, it only removes some data. Whether the project can be run against a single node is stated plainly in the introduction, for a single node as much as for a cluster, so the cluster features do not make a single machine setup awkward.

Most entities start disabled, and the polling options are deliberate

Many entities are created disabled by default. The buttons that change things and the sensors most setups never need are the ones that stay off, and you enable them per entity. For an integration that can reboot a hypervisor, that default is the correct one, and it also keeps the entity list short for people who only wanted a dashboard. The options page, split into a selection page and an advanced configuration page, controls what is tracked at all: you add or remove nodes, virtual machines, containers or storages, with shared storage listed once and marked as shared. Monitoring physical disks can be switched off, and the reason given is a good one, reading SMART wakes sleeping disks. The polling interval is chosen from 30, 45, 60, 90 or 120 seconds for nodes, guests, storage and backups, while certificates, subscriptions and Ceph stay on an hourly schedule and failed tasks are checked every five minutes. That last split is a sensible cost model, since not every value changes quickly enough to be worth a request every thirty seconds.

Installation through HACS or a manual copy

There are two ways in. With HACS installed, you can add Proxmox VE as a custom repository of type Integration using the repository URL, click Install on the integration, and restart Home Assistant. The manual route is to copy the proxmoxve folder from the latest release into the custom_components folder in your configuration directory and restart Home Assistant. Either way the integration then appears in the add integration dialog, where the configuration flow asks for the credentials described earlier. The rest of the documentation is worth knowing about, because the entity list is large: there are pages for entities by cluster, node, guest and storage, for actions and the backup action, for hardware sensors and physical disks including when readings come and go, for Proxmox permissions covering roles, groups, users and tokens step by step, for how it behaves, for troubleshooting with debug logging, diagnostics and screenshots, and a page comparing the integration with the core one feature by feature. There are also blueprints, including a scheduled backup as a ready made automation, and a crowdin.yml file for translations. The pinned dependencies are narrow: homeassistant at version 2026.9.1, proxmoxer at 2.3.0, ruff at 0.16.10, colorlog and pip.

Editorial conclusion

proxmoxve is a good fit for a Home Assistant household that runs Proxmox and wants cluster, node, guest and storage state in the dashboard plus buttons to act on it, especially if the core integration has not kept up with your setup. It is the wrong choice if you want a vendor-supported integration, if you cannot give it token credentials, or if you need hardware temperatures and refuse to install PVE-mods on your nodes. Before you install, read docs/compared-to-core.md to see what replaces what, decide whether tokens or user authentication fit your realm, and plan for the fact that the writing entities are disabled until you enable them one by one.

Frequently asked questions

Official sources

1. dougiteixeira/proxmoxve on GitHub
2. Issues
3. License: MIT
4. README
5. Releases