2026.3.1
Home ▸ Integrations ▸

Proxmox VE

Proxmox VE is an open-source server virtualization environment. This integration lets you monitor your Proxmox VE nodes, virtual machines, and containers in Home Assistant, and exposes control actions (if your Proxmox permissions allow it).

Prerequisites

Important

To see entities in Home Assistant, you need at least one node with at least one virtual machine or container in Proxmox VE.

Before you set up the integration, make sure you have created a Proxmox VE user with the right permissions. See Proxmox permissions.

Configuration

To add the Proxmox VE service to your Home Assistant instance, use this My button:

Manual configuration steps

If the above My button doesn’t work, you can also perform the following steps manually:

  • Browse to your Home Assistant instance.

  • Go to Settings > Devices & services.

  • In the bottom right corner, select the Add Integration button.

  • From the list, select Proxmox VE.

  • Follow the instructions on screen to complete the setup.

Host

Address of your Proxmox instance. Example: https://proxmox.example.com.

Port

Port to connect to Proxmox. Default is 8006.

Realm

The authentication realm in Proxmox VE. Default is pam. For a dedicated Home Assistant account, we recommend using the built-in Proxmox VE realm and selecting pve (see Proxmox permissions).

Username

Configured user to authenticate.

Password

Password associated with the username.

Verify SSL certificate

Enable SSL certificate verification for secure connections.

Proxmox permissions

This integration reads status and resource usage from Proxmox VE, and can perform actions using button entities.

Important

To keep things secure, create a dedicated Proxmox VE user for Home Assistant and only grant the permissions you need. In short, do not use the root account.

Choose the right role

The minimum required permissions depend on what you want to do:

  • Monitor only (sensors and binary sensors): The Auditor role (PVEAuditor) is typically sufficient.
  • Monitor and control (button entities like start, stop, reboot): You will need a role that allows those actions, such as User (PVEVMUser) or another custom role that includes the required privileges.

If you are not sure which privileges you need for control in your Proxmox VE setup, start with PVEVMUser, confirm everything works, and then tighten the permissions by switching to a custom role. If you want full but responsible control start with PVEVMAdmin.

Create a Home Assistant group

Before creating the user, you need to create a group for the user. Privileges can be either applied to Groups or Roles.

  1. Select Datacenter.
  2. Open Permissions and select Groups.
  3. Select the Create button above all the existing groups.
  4. Name the new group (for example, HomeAssistant).
  5. Confirm Create.

Add Group Permissions to all Assets

Assign the role you chose to the group at the root path (/) so it applies to all nodes, VMs, and containers.

  1. Select Datacenter.
  2. Select Permissions.
  3. Open Add and select Group Permission.
  4. For Path, select /.
  5. For Group, select your Home Assistant group (HomeAssistant).
  6. For Role, select the role you want to use, like PVEAuditor (monitoring only) or PVEVMUser (monitoring plus basic actions).
  7. Make sure Propagate is checked.
  8. Confirm Create.

Create a user for Home Assistant

Using the pve realm helps limit the account to API access, instead of Linux system authentication and remote (SSH) command line access.

Important

If you plan to use the pve realm, make sure you select it during user creation and use the @pve suffix in Home Assistant (like hass@pve).

  1. Select Datacenter.
  2. Open Permissions and select Users.
  3. Select Add.
  4. Enter a username (for example,hass).
  5. Set the realm to Proxmox VE authentication server for pve (or Linux PAM standard authentication for pam).
  6. Enter a secure password (it can be complex as you will only need to copy/paste it into your Home Assistant configuration).
  7. Select the group just created earlier (HomeAssistant) to grant access to Proxmox.
  8. Ensure Enabled is checked and Expire is set to “never” (for example, leave it blank).
  9. Confirm Add.

Entities

Sensor

  • CPU: Percentage of CPU usage.
  • Max CPU: Maximum amount of CPU on the node/VM/LXC.
  • Disk: Disk usage of the node/VM/LXC.
  • Max disk: Maximum amount of available disk space.
  • Memory: Amount of memory usage.
  • Max memory: Maximum amount of memory on the node/VM/LXC.
  • Status: Current status of the node/VM/LXC.

Binary sensor

The integration will automatically create a binary sensor for each tracked virtual machine or container. The binary sensor will either be on if the VM state is running or off if the VM state is different.

The created sensor will be called binary_sensor.NODE_NAME_VMNAME_running.

Button

  • Start: Starts a node/VM/LXC.
  • Start all: Starts all VMs and LXCs known on a node.
  • Stop: Stops a node/VM/LXC.
  • Stop all: Stops all VMs and LXCs known on a node.
  • Restart: Restarts a VM/LXC.
  • Reboot: Reboots a node.
  • Shutdown: Shuts a node down.
  • Hibernate: Puts a VM in hibernation; only available to VMs.
  • Reset: Resets a VM; only available to VMs.

Troubleshooting

Buttons not working

If you want to use the button entities to control power actions (start/stop/reboot and similar actions), the Proxmox VE user must have the required privileges for those actions (for example, VM.PowerMgmt on the relevant path). If monitoring works but button presses fail, assign a more permissive role (or create a custom role) and try again.

Diagnostic data

If you need to create an issue to report a bug or want to inspect diagnostic data, use the following steps to retrieve diagnostics:

  1. Go to Settings > Devices & services, and select your integration and device.
  2. On the integration entry, select the .
    • Then, select Download diagnostics and a JSON file will be downloaded.
  3. You can inspect the downloaded file or, when requested, upload it to your issue report.

Removing the integration

This integration follows standard integration removal. No extra steps are required within Home Assistant. Remember to clean up your Proxmox permissions.

To remove an integration instance from Home Assistant

  1. Go to Settings > Devices & services and select the integration card.
  2. From the list of devices, select the integration instance you want to remove.
  3. Next to the entry, select the three dots menu. Then, select Delete.

Related topics