Home Assistant on Proxmox VE

Why Proxmox for Home Assistant?

Proxmox VE is the most popular virtualization platform among self-hosters. Running Home Assistant on Proxmox means it shares your server with other VMs and containers instead of needing dedicated hardware. You get snapshots before updates, easy backups, and resource isolation.

There are two approaches:

HAOS VM (Recommended) — Import the official Home Assistant OS qcow2 disk image as a Proxmox VM. You get the full Home Assistant experience: Supervisor, Add-on Store, managed backups, automatic updates. This is the officially supported Proxmox installation method.

Docker in LXC — Run Home Assistant Core in a Docker container inside a Proxmox LXC container. Lighter on resources, but you lose the Supervisor and Add-on Store. Use this only if you are already managing LXC containers and want everything consolidated.

Prerequisites

• Proxmox VE 8.0+ installed and accessible via web UI
• 2 vCPUs available for the HA VM/LXC
• 4 GB RAM available (2 GB minimum for the VM)
• 32 GB disk space available
• A Zigbee or Z-Wave USB dongle (optional)
• SSH access to the Proxmox host

Method 1: HAOS VM (Recommended)

This creates a dedicated VM running Home Assistant Operating System. The VM gets the full HA experience including the Supervisor and Add-on Store.

Download the HAOS Image

SSH into your Proxmox host:

ssh root@<proxmox-ip>

Download the latest HAOS qcow2 image:

cd /var/lib/vz/template/
wget https://github.com/home-assistant/operating-system/releases/download/14.2/haos_ova-14.2.qcow2.xz
xz -d haos_ova-14.2.qcow2.xz

Check the Home Assistant OS releases page for the latest version. Use the haos_ova variant — it works with any KVM-based hypervisor including Proxmox.

Create the VM

Create a VM shell using Proxmox’s CLI. We will import the HAOS disk into it:

# Create the VM (ID 100 — change if already in use)
qm create 100 \
  --name homeassistant \
  --ostype l26 \
  --memory 4096 \
  --cores 2 \
  --cpu host \
  --net0 virtio,bridge=vmbr0 \
  --scsihw virtio-scsi-pci \
  --bios ovmf \
  --machine q35 \
  --efidisk0 local-lvm:1,format=raw,efitype=4m,pre-enrolled-keys=0 \
  --agent enabled=1

Configuration breakdown:

• --memory 4096 — 4 GB RAM. Home Assistant works with 2 GB but 4 GB gives headroom for add-ons like Zigbee2MQTT, Node-RED, and the database.
• --cores 2 — 2 vCPUs. Sufficient for most setups. Increase to 4 if you run compute-heavy add-ons.
• --cpu host — Passes through the host CPU model for best performance.
• --bios ovmf — UEFI boot (required for HAOS).
• --machine q35 — Modern machine type with PCIe support.
• --agent enabled=1 — Enables the QEMU Guest Agent for clean shutdowns and IP reporting.

Import the Disk Image

qm importdisk 100 /var/lib/vz/template/haos_ova-14.2.qcow2 local-lvm

This imports the HAOS disk as an unused disk attached to VM 100. Now attach it as the boot disk:

# Attach the imported disk as scsi0
qm set 100 --scsi0 local-lvm:vm-100-disk-1,ssd=1

# Set the boot order to use this disk
qm set 100 --boot order=scsi0

Resize the Disk

The HAOS image ships with a small disk (32 GB). Resize it to give Home Assistant room for its database, backups, and add-on data:

qm disk resize 100 scsi0 64G

64 GB is a good starting point. HAOS automatically expands the filesystem to fill the disk on first boot.

Start the VM

qm start 100

Or start it from the Proxmox web UI. Open the VM’s console to watch the boot process. HAOS takes 5-10 minutes on first boot as it downloads and installs the latest Home Assistant Core version.

Access Home Assistant at http://<vm-ip>:8123. Find the VM’s IP from the Proxmox summary tab (requires the QEMU Guest Agent) or from your router’s DHCP lease table.

Complete the onboarding wizard: create an admin account, set location, configure timezone.

USB Passthrough for Zigbee/Z-Wave (VM)

To use a Zigbee or Z-Wave USB dongle with the HAOS VM, pass the USB device through from the Proxmox host.

Find the device on the Proxmox host:

lsusb

Example output:

Bus 001 Device 004: ID 10c4:ea60 Silicon Labs CP210x UART Bridge

Pass it through to the VM using the vendor:product ID:

qm set 100 -usb0 host=10c4:ea60

This passes the device by vendor/product ID, so it reconnects automatically even if the device path changes.

Alternatively, pass through by host bus/device number for a one-time mapping:

qm set 100 -usb0 host=1-4

You can also do this from the Proxmox web UI: VM > Hardware > Add > USB Device.

After adding the USB device, reboot the VM. The dongle appears inside HAOS and can be configured through ZHA or Zigbee2MQTT.

VM Snapshots Before Updates

One of the biggest advantages of running HAOS in a Proxmox VM: snapshots. Before any Home Assistant update:

qm snapshot 100 pre-update-2026.2.3 --description "Before HA 2026.2.3 update"

If the update breaks something, roll back in seconds:

qm rollback 100 pre-update-2026.2.3

This is far safer than HAOS’s built-in backup/restore, which can take minutes and requires Home Assistant itself to be functional.

Method 2: Docker in LXC

This method runs Home Assistant Core in a Docker container inside a Proxmox LXC container. It is lighter on resources but you lose the Supervisor and Add-on Store.

Create the LXC Container

From the Proxmox web UI or CLI:

# Download a Debian 12 template (if not already available)
pveam update
pveam download local debian-12-standard_12.7-1_amd64.tar.zst

# Create the LXC container
pct create 101 local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst \
  --hostname homeassistant-docker \
  --cores 2 \
  --memory 4096 \
  --swap 512 \
  --rootfs local-lvm:32 \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp \
  --features nesting=1,keyctl=1 \
  --unprivileged 1 \
  --onboot 1

Key flags:

• --features nesting=1,keyctl=1 — Required for running Docker inside the LXC container.
• --unprivileged 1 — Security best practice. Use a privileged container only if USB passthrough does not work unprivileged.

Install Docker in the LXC

Start the container and enter its shell:

pct start 101
pct enter 101

Install Docker:

apt update && apt install -y curl
curl -fsSL https://get.docker.com | sh

Deploy Home Assistant

Create the directory and compose file:

mkdir -p /opt/homeassistant/config

Create /opt/homeassistant/docker-compose.yml:

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:2026.3.1
    volumes:
      - /opt/homeassistant/config:/config
      - /etc/localtime:/etc/localtime:ro
    environment:
      - TZ=America/New_York
    restart: unless-stopped
    network_mode: host

Start it:

cd /opt/homeassistant
docker compose up -d

Access the UI at http://<lxc-ip>:8123.

USB Passthrough for Zigbee/Z-Wave (LXC)

USB passthrough in LXC is more involved than VM passthrough. On the Proxmox host:

1. Find the device’s major/minor numbers:

ls -la /dev/ttyUSB0
# Output: crw-rw---- 1 root dialout 188, 0 Mar  4 12:00 /dev/ttyUSB0

The major number is 188, minor is 0.

2. Stop the LXC container:

pct stop 101

3. Edit the LXC config at /etc/pve/lxc/101.conf. Add:

lxc.cgroup2.devices.allow: c 188:* rwm
lxc.mount.entry: /dev/ttyUSB0 dev/ttyUSB0 none bind,optional,create=file

4. Start the container:

pct start 101

5. Inside the LXC, verify the device is available:

pct enter 101
ls -la /dev/ttyUSB0

6. Add the device to Docker Compose:

    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0

For privileged LXC containers, USB passthrough is simpler — mount the entire /dev path. But privileged containers have security implications. Use unprivileged with explicit device passthrough when possible.

Resource Allocation

HAOS VM

Resource	Minimum	Recommended	Heavy Use
vCPU	2	2	4
RAM	2 GB	4 GB	6 GB
Disk	32 GB	64 GB	128 GB

“Heavy use” means 500+ entities, multiple add-ons (Zigbee2MQTT, Node-RED, InfluxDB, Grafana), and voice assistant processing.

Docker in LXC

Resource	Minimum	Recommended
vCPU	1	2
RAM	1 GB	2 GB
Disk	8 GB	16 GB

The LXC method uses less resources because it does not run a full OS — no Supervisor, no add-on containers, just Home Assistant Core.

Platform-Specific Tips

• Enable QEMU Guest Agent for HAOS VM. It is already set in the qm create command above (--agent enabled=1). HAOS includes the guest agent by default. This lets Proxmox cleanly shut down the VM and report its IP address.
• Set the VM to start on boot. In the Proxmox UI: VM > Options > Start at boot: Yes. Set a startup delay of 30 seconds so the Proxmox host’s network is ready first.
• Use virtio drivers. The qm create command uses virtio for disk (via virtio-scsi-pci) and network (virtio). These are paravirtualized drivers that perform far better than emulated IDE/e1000 drivers.
• Avoid overcommitting RAM. If your Proxmox host has 16 GB RAM total, do not allocate 4 GB to HA and 12 GB to other VMs. Leave 2-4 GB for the host and ZFS ARC (if using ZFS storage).
• Backup the VM with Proxmox. Use Proxmox’s built-in backup scheduler (Datacenter > Backup) to back up the HAOS VM regularly. This captures the entire VM state including HAOS configuration, HA config, and database. Restore is a single click.
• Do not use ballooning with HAOS. HAOS does not install the balloon driver by default. Disable memory ballooning in the VM settings to avoid Proxmox reporting incorrect memory usage.

Troubleshooting

HAOS VM Won’t Boot — “No Bootable Device”

Symptom: Proxmox console shows “No bootable device” or “UEFI shell” after importing the HAOS disk.

Fix: Verify the boot order is set correctly:

qm set 100 --boot order=scsi0

Confirm the disk is attached as scsi0:

qm config 100 | grep scsi0

If the disk shows as unused0, reattach it:

qm set 100 --scsi0 local-lvm:vm-100-disk-1

Also verify UEFI boot is configured (--bios ovmf). HAOS requires UEFI — it does not boot with SeaBIOS.

USB Device Not Visible in HAOS VM

Symptom: Zigbee/Z-Wave dongle is plugged into the Proxmox host but does not appear inside the HAOS VM.

Fix:

1. Verify the device is visible on the host: lsusb
2. Check the USB passthrough config: qm config 100 | grep usb
3. Try removing and re-adding the USB device:

   qm set 100 -delete usb0
   qm set 100 -usb0 host=10c4:ea60

4. Reboot the VM (not just restart HA — reboot the entire VM)
5. If the device still does not appear, check if any other VM or the Proxmox host itself is claiming the device

Docker Fails to Start Inside LXC

Symptom: docker: Cannot connect to the Docker daemon or overlay filesystem errors inside the LXC container.

Fix: Ensure nesting is enabled:

pct set 101 --features nesting=1,keyctl=1
pct stop 101
pct start 101

For unprivileged containers, Docker may fail if the LXC storage backend does not support overlayfs. Try switching the container’s root filesystem to a directory-backed storage or use a privileged container.

Network Discovery Not Working in VM

Symptom: Home Assistant in the HAOS VM cannot discover devices on the local network (Chromecast, Hue, etc.).

Fix: The VM must be on the same Layer 2 network as your IoT devices. Verify:

1. The VM’s network interface uses a bridged adapter (vmbr0) that is bridged to your physical NIC
2. The VM has an IP on the same subnet as your other devices
3. IGMP snooping on your switch is not filtering multicast traffic to the VM

If you use VLANs, make sure the VM is on the same VLAN as your smart home devices. mDNS and SSDP do not cross VLAN boundaries without a multicast relay.

LXC Container Runs Out of Disk Space

Symptom: Home Assistant stops writing to the database. Logs show “No space left on device.”

Fix: Resize the LXC root filesystem from the Proxmox host:

pct resize 101 rootfs +16G

The filesystem inside the container expands automatically. No reboot required.

To prevent: monitor disk usage and set the recorder to limit database retention.

Related

• How to Self-Host Home Assistant with Docker
• Install Home Assistant on Ubuntu
• Home Assistant on Raspberry Pi
• Best Self-Hosted Home Automation
• Home Assistant vs OpenHAB
• Replace Google Home
• Docker Compose Basics
• Backup Strategy
• Getting Started with Self-Hosting