Proxmox Home Assistant Dedicated User Setup

This guide shows you how to create a dedicated, non-root user in Proxmox for managing your Home Assistant virtual machine or container. Using a separate user limits the damage if credentials are compromised and keeps your Proxmox host more secure. You’ll need root or sudo access to Proxmox to complete the setup.

What You’ll Need

• Root or sudo access to the Proxmox web interface or shell.
• An existing Home Assistant VM or container (or the ability to create one).
• Basic familiarity with Proxmox’s web interface.

Step-by-Step

1. Log in to Proxmox – Open your Proxmox web interface (usually https://your-server-ip:8006) and log in with an account that has root or administrator privileges.
2. Navigate to Datacenter → Permissions → Groups – In the left sidebar, click Datacenter, then expand Permissions and select Groups. This is where you’ll create a group for Home Assistant management.
3. Create a group – Click Create, give the group a name like home-assistant, and optionally add a comment. Click OK to save.
4. Create the user – In the left sidebar, go to Datacenter → Permissions → Users. Click Add, fill in a username (e.g., ha-user), set a strong password, and add the user to the home-assistant group. Leave other fields default unless you have specific needs. Click Add.
5. Assign permissions to the group – Go to Datacenter → Permissions → Add. In the dropdown, choose Group Permissions. Select your group (home-assistant), choose the path (usually / for all nodes, or restrict to a specific VM/CT), and select the role PVEVMUser (or PVEVMAdmin if you need full VM control). Click Add.
6. Verify the user can log in – Log out of Proxmox and log back in with the new user account. You should see the VMs/CTs you’ve been granted access to in the sidebar.
7. Use the user for Home Assistant – When configuring Home Assistant’s integrations (e.g., the official Proxmox integration), use this dedicated user’s credentials instead of root. The integration will use the API token you generate in the next step.
8. Generate an API token (optional but recommended) – In Proxmox, go to Datacenter → Permissions → API Tokens. Click Add, select your user, give the token a name, and choose the privileges (usually PVEVMUser). Click Add and copy the token secret immediately – it’s shown only once.
9. Configure Home Assistant – In Home Assistant, go to Settings → Devices & Services → Add Integration, search for “Proxmox�, and enter the URL, username, and password (or API token) you created. Test the connection and save.

Common Mistakes

• Giving too many permissions – Assigning Administrator role to the group defeats the purpose. Use the least privilege needed.
• Using the root password in Home Assistant – This exposes your root credentials to the HA instance. Always use a dedicated user.
• Forgetting to set the group path – If you leave the path as /, the user gets access to all VMs/CTs, which may be too broad. Restrict to specific VM IDs if possible.
• Not enabling the API token – If you generate a token but don’t enable it, it won’t work. Make sure the toggle is on.
• Using the wrong realm – Proxmox has authentication realms (PAM, LDAP, etc.). Make sure you select the correct realm when creating the user (usually PAM).

Tips

• Use a separate group per VM – If you manage multiple VMs, create separate groups for each to keep permissions granular.
• Store the API token securely – The token secret is shown once; save it in a password manager.
• Regularly review permissions – Periodically check the group’s permissions to ensure they still match your needs.
• Use the API token for automation – Tokens are better for scripts and integrations because they can be revoked individually.
• Test the user’s access – After setup, try a simple action like starting/stopping a VM to confirm the user has the right privileges.

Troubleshooting

• User cannot log in – Check that the user is in the correct realm (PAM) and that the password is correct. Also verify the account is not locked.
• User sees no VMs – The group’s path might be too restrictive. Ensure the path includes the VM/CT ID, e.g., /vms/100 or / for all.
• Home Assistant integration fails to connect – Verify the URL is correct (including port 8006), and that the user has API access. If using a token, ensure it’s enabled and has the correct privileges.
• Permission denied when starting VM – The role PVEVMUser only allows read-only access. To start/stop VMs, use PVEVMAdmin or create a custom role with the needed privileges.
• Token not working – Regenerate the token and ensure you copy the secret immediately. Also check that the token is not expired (tokens can have an expiration date).

Frequently Asked Questions

Can I use the same user for multiple VMs?

Yes, just set the group’s path to / or add multiple paths in the permission rule.

Is it safe to give Home Assistant admin rights on the VM?

Only if you trust your Home Assistant configuration. It’s better to give minimal rights and expand later if needed.

What’s the difference between PVEVMUser and PVEVMAdmin?

PVEVMUser allows read-only access to VMs, while PVEVMAdmin allows full control, including start/stop and console access.

Can I use an API token instead of a password?

Yes, tokens are more secure and can be revoked individually. Use them in Home Assistant’s Proxmox integration.

Do I need to create a new user for each Home Assistant instance?

Not necessarily, but if you have multiple HA instances, separate users help with auditing and security.

What if I forget the API token secret?

You can’t retrieve it, but you can delete and recreate the token in Proxmox.

Related

• Garmin Instinct Solar: Best Hiking Smartwatch?
• Subwoofer Against Couch: Does It Really Improve Bass?
• Volume Calculator from Density and Mass