2026.2.3
Home ▸ Integrations ▸

Proxmox VE

Proxmox VE is an open-source server virtualization environment. This integration allows you to poll various data from your instance.

After configuring this integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more], the binary sensors automatically appear.

Configuration

Important

You should have at least one VM or container entry configured within Home Assistant, else this integration won’t do anything. You should have the Proxmox permissions ready before creating the integration.

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

Authentication source of Proxmox. Default is PAM.

Username

Configured user to authenticate.

Password

Password associated with the username.

Verify SSL certificate

Enable SSL certificate verification for secure connections.

Proxmox permissions

To be able to retrieve the status of VMs and containers, the user used to connect must minimally have the VM.Audit privilege. Below is a guide to how to configure a new user with the minimum required permissions.

Create Home Assistant Group

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

  1. Click Datacenter
  2. Open Permissions and click Groups
  3. Click the Create button above all the existing groups
  4. Name the new group (e.g., HomeAssistant)
  5. Click Create

Add Group Permissions to all Assets

For the group to access the VMs we need to grant it the auditor role

  1. Click Datacenter
  2. Click Permissions
  3. Open Add and click Group Permission
  4. Select “/” for the path
  5. Select your Home Assistant group (HomeAssistant)
  6. Select the Auditor role (PVEAuditor)
  7. Make sure Propagate is checked

Create Home Assistant User

Creating a dedicated user for Home Assistant, limited to only to the access just created is the most secure method. These instructions use the pve realm for the user. This allows a connection, but ensures that the user is not authenticated for SSH connections. If you use the pve realm, just be sure to add realm: pve to your configuration.

Important

The Home Assistant user you create must already exist on the Linux system.

  1. Click Datacenter
  2. Open Permissions and click Users
  3. Click Add
  4. Enter a username (e.g.,hass)
  5. Set the realm to “Proxmox VE authentication server”
  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”
  9. Click Add

In your Home Assistant configuration, use hass@pve for the username and your chosen password for the password.

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’s state is running or off if the VM’s state is different.

The created sensor will be called binary_sensor.NODE_NAME_VMNAME_running.

Related topics