About
Proxmox VE Custom is an integration that reads Proxmox VE state into Home Assistant and lets it act on nodes and clusters. It talks to the Proxmox API locally with the given credentials, either a user password or an API token, and installs nothing on the nodes. It covers clusters, nodes, virtual machines, containers and storage, with sensors, binary sensors, buttons and a software update entity for pending package upgrades. Buttons start, stop, reboot, suspend or back up guests, and a backup action exposes vzdump options. Options include automatic tracking of everything the credentials can see, monitoring of physical disk health, failed tasks and a choice between standard and prefixed entity id schemes. It replaces the core Proxmox integration when installed, is added as a custom repository, and is configured in the UI.
Automatic summary of the README and code of dougiteixeira/proxmoxve. Something wrong, or are you the maintainer and want your own text here? Get in touch
Supports
Works locally Talks to your devices on your own network. No vendor cloud in between.
From the Marketplace Installed through the Marketplace, formerly HACS.
Actively maintained Its author released or pushed a change in the last six months.
Provides
- Sensors
Setting it up
Add its repository to the Marketplace as a custom repository and install it, then restart Home Assistant and add it under Settings, Devices and services.
Enter the address
- Host
- Password or token value
- Token name
- Port
- Realm
- Username
- Verify SSL certificate
Also asked when changing the connection.
Expose
- Nodes
- Virtual Machines (QEMU)
- Linux Containers (LXC)
- Storages
- Monitor physical disksRead the model, size, temperature, wearout and SMART health of each node's physical disks as a device of its own. If you spin disks down, switch this off - the SMART read wakes them on every poll otherwise.
- Track everything automaticallyTrack every node, virtual machine, container and storage the credentials can see, and follow the cluster from then on: whatever is added is picked up, whatever is removed is dropped. The selection above is ignored while this is on. Templates are never tracked.
- Entity id schemeStandard: Home Assistant's device then name, qemu_win11_108_cpu_used. Extended: prefix, kind, id, name, item - pve_qemu_108_win11_cpu_used - so a search or a recorder filter catches everything by the prefix and a list sorts by id. Applies to entities created from now on; ids that exist keep them.
- Prefix for the extended schemeThe first part of every entity id under the extended scheme; pve unless you choose otherwise. Not used by the standard scheme.
Reauthenticate Integration
- Password or token value
- Username
- Token name
- Realm
After setup
- Password or token value
- Token name
- Realm
- Username
- Verify SSL certificate
- UsernameLeave empty (along with the fields below) to disable the Arm/Disarm HA buttons and the HA managed sensor.
- Token name
- Password or token valueNeeds Sys.Console (arm/disarm) and Sys.Audit (HA resource list) on '/' — not the scoped permissions recommended for the main integration user.
- Realm
- Linux Containers (LXC)
- Nodes
- Virtual Machines (QEMU)
- Storages
- Track everything automaticallyTrack every node, virtual machine, container and storage the credentials can see, and follow the cluster from then on: whatever is added is picked up, whatever is removed is dropped. The selection above is ignored while this is on. Templates are never tracked.
- Monitor physical disksRead the model, size, temperature, wearout and SMART health of each node's physical disks as a device of its own. If you spin disks down, switch this off - the SMART read wakes them on every poll otherwise.
- Monitor failed tasksTrack and report failed tasks from the last 24 hours on the selected nodes, as a sensor. Read every five minutes.
- Monitor package updatesRead the pending package upgrades of each node into an update entity and a count sensor. Needs Sys.Modify on the node; switch this off to run without that privilege - or without the entities.
- Polling intervalHow often nodes, guests, storage and backups are read. 60 seconds unless changed; Proxmox itself refreshes guest figures about every 10 seconds. Certificates, subscriptions and Ceph are read hourly, failed tasks every five minutes, whatever is set here.
- Guest file path to monitor (QEMU, requires guest agent)Absolute path of a file inside each tracked QEMU guest to read via the guest agent and expose as a sensor. Leave empty to disable. Requires the QEMU guest agent to be running in the guest.
- Backup storage for the backup buttonsWhere the "Back up now" and "Back up all" buttons write their backups (snapshot mode). The buttons exist only while a storage is picked here and the credentials hold VM.Backup. Storages that accept backups are listed; any other name can be typed in.
- Entity id schemeStandard: Home Assistant's device then name, qemu_win11_108_cpu_used. Extended: prefix, kind, id, name, item - pve_qemu_108_win11_cpu_used - so a search or a recorder filter catches everything by the prefix and a list sorts by id. Applies to entities created from now on; ids that exist keep them.
- Prefix for the extended schemeThe first part of every entity id under the extended scheme; pve unless you choose otherwise. Not used by the standard scheme.
Texts from the code of dougiteixeira/proxmoxve.
Entities
- Binary sensorsStatus, Backup running, Health, Locked, Guest agent, Updates packages, HA managed, Replication failing, Quorate, CRM master stale, Storage active, Storage enabled, and 2 more
- ButtonsStart all, Stop all, Shutdown, Reboot, Start, Stop, Unlock, Resume, Suspend, Reset, Wake-on-LAN, Arm HA, and 5 more
- SensorsCPU used, CPU used of host, CPU pressure, CPU pressure stalled, IO pressure, IO pressure stalled, Memory pressure, Memory pressure stalled, Memory used on host, IP address, Snapshots, CPUs, and 59 more
- UpdatesSoftware update
Actions
- Back up guestsStarts backup runs (vzdump) for the targeted guests, nodes or cluster - or for the node and guest ids named. One run per node; returns their task ids.Fields: Node, Guests, All, Storage, Mode, Compression, Notes, Skip if running
Troubleshooting
- DiagnosticsDownloads a diagnostics file to attach to a bug report.
- Repair noticesNotices it can show in Settings, Repairs:Guest agent not readable, Guest file not readable
From the README
Proxmox VE is an open-source server virtualization environment. This integration reads its state into Home Assistant and lets you act on it — for a single node as much as for a cluster.
It began as @dougiteixeira's custom integration, built on the Home Assistant core integration and grown well beyond it; it replaces the core one when installed (what differs). Everything goes through the Proxmox API with the credentials you give it — nothing is installed on the nodes, except PVE-mods if you want hardware temperatures.
Shows in Vulpo
Button card, Chart card, Apple Watch.Information
- Installs
- 5.7k sharing analytics
- GitHub stars
- 985
- Connection
- Works locally
- Upkeep
- Updated in the last 6 months
- Version
- 5.3.4,
- Category
- Computers and network, NAS and servers
- Kind
- Marketplace integration
- Brand
- Proxmox
- Needs
- Added as a custom repository in the Marketplace
- Domain
proxmoxve- Issues
- Report an issue












