Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsiTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Connect an existing Proxmox VE host from Home Assistant with the built-in Proxmox VE integration. Create a dedicated Proxmox user, give it only the permissions your intended monitoring or control needs, then add the integration at Settings > Devices & services > Add Integration > Proxmox VE. The usual port is 8006. For monitoring, start with the PVEAuditor role; add action-specific privileges only if you want Home Assistant to control guests. This guide is for connecting an existing host, not installing Home Assistant as a Proxmox virtual machine.
What do I need before connecting Proxmox to Home Assistant?
You need a running Proxmox VE host with at least one node and at least one virtual machine (VM) or LXC container on that node. The integration uses guest data to create entities, so a host with no guests may connect without presenting the entities you expect.
Before starting, have these details ready:
- The Proxmox host name or IP address and the port Home Assistant should use. The integration defaults to port
8006. - A dedicated Proxmox VE account and the authentication realm where it was created.
- A password for that account, or an API token and its secret.
- A decision about whether Home Assistant should monitor only, or also perform actions such as powering a guest on or off and creating snapshots.
Home Assistant must be able to reach the host address and port from its network. If you use a Proxmox certificate that Home Assistant can validate, leave certificate verification enabled during setup. The available setup fields do not establish that every network arrangement will work; if the host is unreachable, check the address, port, routing, and any firewall rules between the systems.
Connecting an existing host is a configuration-only task: it does not require a new computer, an SSD purchase, or a USB installer. Those considerations apply only if you are building or upgrading a Proxmox host. Decide first whether the integration should be read-only or able to act on guests; that choice determines the permissions to assign, not which hardware you need.
Popular on Amazon
- 【90 Degree Full Function USB C Adapter】Supports the latest USB4 standard for up to 40Gbps of bandwidth, 8K video support, and up to 240W Fast charging; Support USB PD 3.1 Extended Power Range (EPR) including 140W, 180W and 240W. Your productivity is easily doubled. *Warm Tip: For the best fit, please make sure the USB-C port is fully exposed; thick or bulky cases may affect compatibility.
- 【Reliable Quality】Made from high-quality, scratch-resistant aluminum alloy, delicate metal frame. get excellent wear resistance and heat dissipation. Non-Slip Design for easier insertion and removal.
- 【Small and portable】Ultra thin size, ultra compact design, a petite physique that matches the minimalist design of your modern laptops. Coming with a slim figure that won't block the port next to the one it's plugged into.
- 【Compatibility】Widely work with most usb c, thunderbolt 4/3 devices. Compatibilit for ROG Ally, Steam Deck, Switch, MacBook Pro, Quest 3 VR headset, Surface Book 2, iPhone 18/17/16/15, Samsung Galaxy S23/S22/S21, Note 20/10, Google Pixel, ChromeBook, etc.
- 【Excellence Customer Support】If you experience any issues or cable failure, simply reach out to our dedicated customer service team. We provide a prompt response within 18 hours, providing you with the necessary technical support to resolve any concerns.
Which Proxmox permissions should the Home Assistant account have?
For a dashboard that reads status and metrics, PVEAuditor is the recommended starting role. Give the account additional privileges only for the specific actions you intend to expose; a monitoring account does not need broad administrative access merely because the integration offers control buttons.
| Need | Starting permission guidance | Important qualification |
|---|---|---|
| Monitor guests and node data | PVEAuditor |
Start here for read-only use. |
| Power management | VM.PowerMgmt or the documented PVEVMUser example role |
Confirm the privileges cover the intended guest action; do not assume one role grants every node-level operation. |
| Create snapshots | VM.Snapshot or the documented PVEVMAdmin example role |
Grant snapshot access only if Home Assistant should create snapshots. |
| Use a node update entity | Sys.Modify or PVEAdmin |
This is a specific update-entity permission, not a requirement for monitoring. |
Proxmox permissions can be assigned through a group, which makes it easier to manage the integration account without making it a root user. Home Assistant’s official guidance is: “For security, create a dedicated Proxmox VE user for Home Assistant and grant only the minimum required permissions.” If the built-in roles do not match the actions you need, use a narrower custom role after confirming which privileges those actions require.
Think of monitoring and control as two different permission decisions. A monitoring-only setup can begin with PVEAuditor and avoids granting Home Assistant the ability to change guest state. If you later decide to add power or snapshot actions, grant the corresponding privilege and verify it at the relevant path. This is safer than starting with a broad administrative role and trying to reduce access after the integration is already in use.
Recommended Free Tools
How do I create a dedicated Proxmox user?
Create a group, assign its role at the root permission path, and add a dedicated user in the Proxmox VE authentication realm. The role assignment must propagate so it applies to the guests and node data you intend to monitor.
- In Proxmox, open Datacenter > Permissions > Groups and create a group, for example
HomeAssistant. - Open Datacenter > Permissions > Add > Group Permission. Set the path to
/, select the group and the role you chose, and check Propagate. - Open Datacenter > Permissions > Users and add an enabled user, for example
hass, in the Proxmox VE authentication server (PVE) realm. - Add the user to the group you created, then save the configuration.
The PVE realm is for Proxmox VE authentication. It does not give the account ordinary Linux authentication or SSH access. Avoid using root for this integration: a dedicated account limits the permissions exposed to Home Assistant and can be managed separately.
The realm matters both when setting up the account and when connecting from Home Assistant. A username that exists in the Proxmox VE realm is not the same login as an identically named account in the PAM realm. The Home Assistant form defaults to PAM, so explicitly select PVE for the dedicated Proxmox account. At the permission stage, setting the group role at / with propagation checked is the documented way to make the assignment apply down the tree; omitting propagation can leave the account without access where the guests or node data are located.
Should I use a password or an API token?
Home Assistant supports both. A password is straightforward; an API token provides a separate credential that can be revoked without changing the user’s password. A token can also have an expiration date, and privilege separation affects how its permissions must be assigned.
Free tools Windows power users keep installed
One-click scans. No signup required.
| Credential | What to know | Permission detail |
|---|---|---|
| User password | Authenticate as the dedicated Proxmox user with its selected realm. | The user’s Proxmox permissions govern access. |
| API token | Create it under Datacenter > Permissions > API tokens. Copy the secret when it is shown; Proxmox displays it only once. A token can be revoked separately, and may have an expiration date. | If Privilege Separation is checked, grant the token the permissions it needs as well as configuring the parent user. If unchecked, the token inherits the user’s permissions. |
Home Assistant recommends an API token to reduce exposure of the Proxmox account password and allow separate revocation. Do not assume a privilege-separated token will inherit the user’s group role: its own required permissions must be granted. Store the token secret securely; if it is lost, create a replacement rather than expecting Proxmox to display the original secret again.
Also popular on Amazon
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
To make one, open Datacenter > Permissions > API tokens, choose the dedicated user, and assign a Token ID. Decide whether to check Privilege Separation before saving: with separation enabled, grant the token the needed permissions too; without it, the token uses the parent user’s permissions. Copy the secret before closing the creation dialog and record any expiration date you set. The token is useful when you want a credential that can be revoked independently, but it does not eliminate the need to assign appropriate permissions.
In practical terms, choose a password if you prefer the simplest credential flow and are comfortable storing that account credential in Home Assistant. Choose a token if separate revocation and reduced password exposure matter to you, and be prepared to manage its secret and permissions carefully. Neither credential option changes what the account is allowed to do; the user role and token privilege settings determine that.
How do I add the Proxmox VE integration in Home Assistant?
Use Home Assistant’s integration flow and enter the host, port, matching realm, username, and the credential you selected. For a user in the Proxmox-only realm, select PVE; the form defaults to PAM, which is not interchangeable with that account’s realm.
- In Home Assistant, open Settings > Devices & services > Add Integration.
- Search for and select Proxmox VE.
- Enter the Proxmox host name or IP address and port. Use
8006if that is the port your host uses. - Select the authentication realm that matches the account. For the dedicated user created in the Proxmox VE authentication server, choose
PVErather than leaving the defaultPAM. - Enter the username and either the user password or the API-token credentials requested by the form. For password authentication, the form generally expects the username portion without
@realm, because the selected realm is appended. - Keep Verify SSL certificate enabled if Home Assistant can validate the Proxmox certificate. Do not treat disabling verification as a general fix for connection problems.
- Complete the prompts, then open the integration’s device and entity pages to check what was added.
If the form rejects a login, first check that the username, credential, and selected realm agree. A user in PVE will not authenticate as though it were a PAM user simply because the form’s default was left in place.
Before changing certificate verification, check the details you entered and whether Home Assistant can reach the specified host and port. The form’s SSL option controls certificate validation; it is not a substitute for correcting an address, port, or authentication mismatch. Keep verification enabled when the Proxmox certificate is valid and can be checked by Home Assistant.
What entities and actions does the integration provide?
The integration can create sensors for Proxmox and guest information, binary sensors for VM and container running status, and action buttons when the account has the necessary privileges. The actual entities depend on the guests, permissions, and data exposed by Proxmox.
Sensors and status
Documented sensor types include CPU, disk, memory, network input and output, uptime, and last-backup data. VM and container status is represented by binary sensors. A node can also have an update entity, but that entity has a specific permission consideration described below.
Disabled entities
Some entities are disabled by default. If an expected sensor or control is absent, open the relevant device page in Home Assistant and inspect its entities; enable the ones you want there. Not every storage value is exposed through the Proxmox API, so an absent storage measurement is not necessarily an account-permission problem.
Also popular on Amazon
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Buttons and safe guest control
Depending on permissions, buttons can expose power actions and snapshot creation. Distinguish Shut down from Stop: shutting down is the clean guest shutdown action, while an immediate Stop can damage data. Grant control permissions only when you want Home Assistant to be able to issue those actions.
That distinction matters when adding buttons to a dashboard or automation. A Stop action is not simply another label for a graceful shutdown; it stops the guest immediately and can damage its data. If your intention is to let a guest shut down cleanly, use the Shut down action. Make sure household users and automations that can access the button understand which action they are invoking.
Polling and automations
The integration polls every 60 seconds, according to Home Assistant’s integration documentation. That cadence matters when designing notifications or automations: a brief state change may not be observed in the same way as a sustained one. Home Assistant’s example for an offline-VM notification waits 15 minutes; that delay is an example, not a required outage threshold. Build automations around the actual entity ID shown in your Home Assistant instance rather than copying an example ID literally.
For instance, a notification can watch the binary sensor for the guest you care about, wait for it to remain offline for a period, and then alert you. The documented 15-minute delay is one example, not a guarantee that every offline event should be ignored for that long. Choose a delay appropriate to the use case and test it with your own entity. A one-minute polling interval also means an automation should not be described as firing exactly one minute after a guest changes state: polling, network response, and Home Assistant’s own automation handling all affect timing.
Why are my Proxmox guests missing or the controls unavailable?
Separate visibility problems from action-permission problems. If monitoring works but a button fails, the connection is probably reaching enough data for read-only entities; check the permission for that particular action rather than replacing the account with an administrator.
No guests or entities appear
- Confirm the Proxmox node has at least one VM or LXC container; the integration needs a guest to show entities.
- Check that the integration points to the intended host and port.
- Confirm that the selected realm matches the user. In particular, a
PVEaccount should not be submitted with the form’sPAMdefault. - Verify that the user can read the relevant guest and node information. If using a privilege-separated token, verify the token’s permissions as well as the user’s.
- Inspect the device page for entities that are present but disabled by default.
Monitoring works, but power or snapshot actions fail
Check whether the account has the privilege for the action: Home Assistant identifies VM.PowerMgmt or PVEVMUser for power management, and VM.Snapshot or PVEVMAdmin for snapshots. Verify the actual assignment and propagation at the relevant path. Do not broaden permissions indiscriminately to make a button work.
A useful diagnostic is to compare what works with what does not. If sensors and status entities appear but a power button fails, the account has enough access for at least some monitoring, so focus on the required power-management privilege and where it is assigned. If the button is missing rather than failing when used, also inspect disabled entities and the permissions relevant to that action. For snapshot creation, check the snapshot-specific privilege instead of assuming that power-management access includes it.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteThe node update entity is unavailable
Home Assistant calls out Sys.Modify or the PVEAdmin role for the node update entity. This is a more powerful permission than a monitoring-only account needs; leave it out unless the update function is part of the intended setup.
Also popular on Amazon
- Portable and powerful USB-C HUB: BENFEI USB Type-C HUB, with super-soft and knot-free silicone woven design cable, meets most mobile office needs. Compact, lightweight, stylish, and powerful portable USB C Hub equipped with 1 x HDMI port, 1 x 100W charging, and 3 x USB ports. 18-month warranty, 24-hour response, to ensure you feel at ease when using our product.
- Design centered on comfort and reliability: Thanks to BENFEI's end-to-end in-house cable production capability, in-house PCBA and assembly capability, using the industry's most advanced silicone woven design and process, 20cm cable in length, no knots, super-soft, the HUB is easy to use in all scenarios: laptop, tablet, stand etc. Super-soft, 25000+ life cycles, to meet your daily carrying and office needs.
- 100W Charging: Support up to 90W USB C pass-through charging via Type-C port to keep your laptop powered. 10W is reserved for other interface operations. No data and video function on the Type-C port.
- 4K HDMI Display: The HDMI port supports media display at resolutions up to 4K 30Hz, keeping every incredible moment detailed and ultra vivid. Please note that the C port of the Host device needs to support video output.
- Transfer Files in Seconds: Transfer files and from your laptop at speeds up to 10 Gbps with USB A 3.2 port. Extra 2 USB A 2.0 ports are perfectly for your keyboards and mouse.
Data is missing or an entity state looks unexpected
First check whether the entity is disabled and whether Proxmox exposes that data through its API. The integration’s device page provides a diagnostics download that can help investigate problems. Missing storage data in particular may reflect API exposure rather than a broken connection.
When investigating, check the integration’s devices and entities before recreating the account. A value may be unavailable because an entity starts disabled, because the API does not expose that storage data, or because the account or token lacks the necessary read permissions. The diagnostics download from the device page can provide information for further investigation; it does not change the integration’s permissions or make unsupported API data appear.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.How do I remove the connection safely?
Deleting the integration removes its Home Assistant devices and entities. It does not replace the separate task of cleaning up Proxmox permissions. When retiring the connection, remove or adjust the dedicated account, group permissions, and API token in Proxmox as appropriate; revoke a token you no longer need.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
If you are only replacing a credential, distinguish that from deleting the integration. A lost API-token secret cannot be displayed again after creation, so create a replacement, update Home Assistant to use it, and revoke the old token when it is no longer needed. If you are retiring the connection entirely, remove the Home Assistant integration and separately review the Proxmox group and user permissions so they do not remain unnecessarily active.
What if I have not built a Proxmox host yet?
Connecting an existing host is a configuration task and does not require buying additional hardware. A new host is a separate project: Proxmox requires virtualization-capable hardware, and its recommended configuration calls for at least 2 GB for the operating system and Proxmox VE services, plus memory for guests. Proxmox also describes a lower testing-only configuration, so the 2 GB figure is not a universal minimum for every use or a complete sizing recommendation for a host running VMs.
Check the CPU virtualization support and memory capacity of any hardware before installing Proxmox. Proxmox recommends SSD storage and documents copying its installer ISO to USB media, but neither an SSD upgrade nor an installer USB is required merely to connect Home Assistant to a host that already exists.
If you are choosing hardware for a new host, consider it as a separate planning step rather than a requirement of this integration. A virtualization-capable mini PC is one possible category to investigate, but check the exact model’s CPU virtualization support and memory before buying; the 2 GB recommendation covers the OS and Proxmox VE services, with guest memory added on top. Storage and installer media likewise belong to host installation or upgrade planning, not the Home Assistant connection itself.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Frequently Asked Questions
Should I choose PVE or PAM in Home Assistant?
Choose the realm where the Proxmox user was created. A dedicated Proxmox VE user belongs to the PVE realm, while the form defaults to PAM. Selecting PAM for a PVE user will not make the credentials interchangeable.
Also popular on Amazon
- 【Read before You Buy】 Note: This adapter is USB 2.0 version and cannot transmit HDM, VGA, or other video signals. Nevertheless, they are fully capable of charging devices,duplicating files, and can be seamlessly integrated with USB-C earphones, wireless network adapters, and SD card adapters.
- 【Easy to Use and Safe】Thanks to modern manufacturing techniques, we've made these adapters sufficiently compact so that they can remain inserted in your device without noticeable protrusion or inconvenience. This means you don't have to constantly plug and unplug them, reducing the likelihood of wear and misalignment, and making them more convenient to carry around.
- 【Reliable Quality】Engineered for enhanced durability, durable aluminum alloy shell material,get excellent wear resistance and heat dissipation,the male USB C and female USB connectors & the male USB and female USB C connectors are designed to be plugged and unplugged up to 20000 times. Provides data transfer, device charging, memory space expansion, and additional computer peripherals.
- 【Think more for you】Do you need to connect a USB-C-enabled device to an odd device that only has USB-A ports? Then these USB-A male to USB-C female adapters are made for you.Simply insert the adapter into the USB-A port on the device, and you can instantly connect your USB-C device to the device that originally didn't have the correct connection port.
- 【Trusted xiwxi Quality and Service】As a responsible brand seller, you will receive xiwxi's 12-month Quality assurance and lifetime friendly customer service, you're not just buying a product,you're investing in peace of mind with all-round quality and exceptional customer service.
Can I use a Proxmox API token instead of a password?
Yes. Home Assistant supports API-token authentication. A token can be revoked separately from the user password, but copy its secret when it is created because Proxmox shows it only once. If privilege separation is enabled, assign the token the permissions it needs as well as configuring the parent user.
Why can I see Proxmox sensors but the buttons don’t work?
Monitoring and control require different permissions. Check the action-specific permission: Home Assistant identifies VM.PowerMgmt or PVEVMUser for power management and VM.Snapshot or PVEVMAdmin for snapshots. Avoid granting broad administrative access just to make one action work.
Why aren’t my Proxmox VMs showing up?
Confirm that the node has at least one VM or LXC container, that the integration uses the correct host and port, and that the account’s realm and read permissions are correct. Also check the device page for entities that are present but disabled by default.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Can I use a Proxmox API token after its secret has been lost?
Proxmox shows the token secret only when the token is created, so the original secret cannot be recovered from that screen later. Create a replacement token, update the Home Assistant credential, and revoke the lost or unused token.
Does the 60-second polling interval mean an automation runs exactly one minute after a guest changes state?
No. Polling describes how often the integration checks Proxmox, not a guaranteed end-to-end automation delay. Network latency, Home Assistant scheduling, and the automation’s own conditions can affect when an action runs.
Can I safely expose a Home Assistant power button to other users?
Only expose controls to people and automations you trust with the Proxmox permissions behind them. A Stop action is immediate and may damage guest data, so prefer a clean shutdown action where that is the intended outcome.
The Bottom Line
For an existing Proxmox VE host, add Home Assistant’s built-in integration with a dedicated PVE user, the correct host and port, and only the permissions you need. Start with PVEAuditor for monitoring; add and verify action-specific privileges for power or snapshots. An API token is a separately revocable option, but protect its one-time secret and account for privilege separation. Keep the distinction between graceful shutdown and immediate Stop clear before exposing controls.
