Home Assistant OS on Proxmox: 2026 Setup Guide

Running Home Assistant OS on Proxmox is one of the best decisions you can make for your homelab smart home setup. You get a fully supervised install with add-ons, automatic updates, and backups — all on hardware you already own — without sacrificing a dedicated device. This guide walks through every step for 2026, including the USB dongle passthrough that makes Zigbee and Z-Wave work flawlessly.

Why Run Home Assistant OS on Proxmox?

Home Assistant comes in several flavors: OS, Container, Core, and Supervised. Home Assistant OS (HAOS) is the gold standard. It ships its own minimal Linux kernel, manages its own updates, and gives you the full Supervisor stack — including the add-on ecosystem, backup manager, and one-click restore.

Running it inside a Proxmox KVM VM gives you the best of both worlds:

• Snapshots before every major update — roll back in seconds if something breaks
• Live migration if you ever expand to a cluster
• USB passthrough for Zigbee/Z-Wave coordinators works just as well as a bare-metal install
• Resource isolation — HA doesn't compete with other services on the same node

The alternative — running Home Assistant Supervised on a Debian LXC — is technically possible but unsupported and fragile. Stick with the VM.

Prerequisites

Before you start, make sure you have:

• Proxmox VE 8.x or 9.x (this guide covers both)
• At least 2 CPU cores and 4 GB RAM to allocate (HA runs fine on 2 GB but 4 GB is comfortable with add-ons)
• 32 GB or more of disk space on your preferred storage (SSD strongly recommended)
• The HAOS .qcow2 image URL from the official GitHub releases page
• A Zigbee/Z-Wave USB dongle if you plan to use one (Sonoff Zigbee 3.0, HUSBZB-1, or similar)

Step 1: Download the HAOS Image

SSH into your Proxmox node and download the latest HAOS KVM image directly. Check github.com/home-assistant/operating-system/releases for the current version number — as of writing it's 14.x for the 2026 branch.

cd /tmp
wget https://github.com/home-assistant/operating-system/releases/download/14.1/haos_ova-14.1.qcow2.xz
xz -d haos_ova-14.1.qcow2.xz

The .xz decompression takes a minute. The resulting .qcow2 file is around 1.3 GB.

Step 2: Create the VM

You can create the VM entirely from the Proxmox UI or via the CLI. The CLI approach is faster and reproducible.

Create a bare VM with no disk

qm create 200 \
  --name homeassistant \
  --memory 4096 \
  --balloon 0 \
  --cores 2 \
  --cpu host \
  --machine q35 \
  --bios ovmf \
  --net0 virtio,bridge=vmbr0 \
  --ostype l26 \
  --tablet 0 \
  --onboot 1

Key decisions here:

• --cpu host — passes through the full CPU feature set, which HA needs for certain add-ons and containers
• --machine q35 — modern chipset, required for UEFI boot
• --bios ovmf — UEFI firmware; HAOS boots with UEFI by default since version 10
• --balloon 0 — disables memory ballooning; HA's kernel doesn't play well with it

Add the EFI disk

qm set 200 --efidisk0 local-lvm:0,efitype=4m,pre-enrolled-keys=0

Replace local-lvm with your storage name if different. The pre-enrolled-keys=0 part is important — it disables Secure Boot, which HAOS doesn't support.

Step 3: Import the HAOS Disk

Import the downloaded .qcow2 as the main disk for the VM:

qm importdisk 200 /tmp/haos_ova-14.1.qcow2 local-lvm

This copies the image into your storage pool. Once complete, attach it as a VirtIO SCSI disk:

qm set 200 --scsihw virtio-scsi-pci --scsi0 local-lvm:vm-200-disk-1,cache=writeback,discard=on

Then set it as the boot device:

qm set 200 --boot order=scsi0

Resize the disk (optional but recommended)

The default HAOS image is only about 6 GB. Resize it before first boot — HAOS will auto-expand its data partition on startup:

qm disk resize 200 scsi0 64G

64 GB gives you plenty of room for add-on containers and the HA database.

Step 4: Start the VM and Complete Initial Setup

Start the VM from the UI or CLI:

qm start 200

Open the Proxmox console (200 → Console) and watch the boot sequence. First boot takes 2-3 minutes as HAOS expands the partition and starts its Supervisor.

Once it boots, you'll see a line like:

Home Assistant is running at http://homeassistant.local:8123

Navigate to that address in your browser (or use the IP shown in the console). Follow the onboarding wizard to create your account, set your location, and let HA discover devices on your network.

Step 5: USB Dongle Passthrough

This is where most guides fall short. If you have a Zigbee coordinator like the Sonoff Zigbee 3.0 Dongle Plus or a combo stick like the HUSBZB-1, you need to pass it through to the VM so it appears as a real serial device inside HAOS.

Identify the USB device

With the dongle plugged in, run on the Proxmox host:

bash lsusb

You'll see something like:

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

Note the Bus and Device numbers, or use the USB ID (10c4:ea60) for a more stable reference. USB device numbers can change after reboot — the ID stays constant.

Add USB passthrough by vendor:product ID

qm set 200 --usb0 host=10c4:ea60

This passes the device to the VM by its USB vendor:product ID, so it survives reboots and USB hub reconnects.

For multiple dongles (Zigbee + Z-Wave), add more USB entries:

qm set 200 --usb1 host=10c4:ea60
qm set 200 --usb2 host=1cf1:0030

Verify inside Home Assistant

Restart the VM after adding USB passthrough. Inside HA, go to Settings → System → Hardware and you should see the serial devices listed (e.g., /dev/ttyUSB0 or /dev/ttyACM0). When configuring Zigbee Home Automation (ZHA) or Zigbee2MQTT, select the correct path.

Tip: If you're unsure which /dev/tty* path corresponds to your dongle, the Hardware page in HA often labels them by manufacturer. You can also check with ls /dev/tty* via the HA SSH add-on.

Step 6: Enable the QEMU Guest Agent

The QEMU guest agent lets Proxmox communicate with the running VM — it enables clean shutdowns, IP address reporting in the UI, and more accurate snapshot timing.

HAOS includes the guest agent, but you need to enable it in the VM config:

qm set 200 --agent enabled=1

Then reboot the VM. After a minute, the Proxmox summary tab for the VM will show the guest's IP address directly.

Step 7: Configure a Static IP

A static IP is non-negotiable for a home automation hub. You don't want HAOS switching IPs after a DHCP lease renewal.

You have two options:

Option A — DHCP reservation on your router: Preferred. Set a reservation for the HAOS VM's MAC address in your router or DNS server. No config needed inside HA.

Option B — Static IP via HA network settings: In HAOS, go to Settings → System → Network, edit the interface, and set a manual IP. This works but means the address is managed in two places.

For most homelabs, a DHCP reservation on OPNsense or your router is cleaner.

Step 8: Snapshots Before Updates

This is the single biggest advantage of running HAOS in a VM. Before applying any Home Assistant update, take a Proxmox snapshot:

qm snapshot 200 pre-update-14.2 --description "Before HA 14.2 update"

If the update causes issues with an integration or add-on, rolling back takes about 30 seconds:

qm rollback 200 pre-update-14.2

Compare this to running HA on a Raspberry Pi or dedicated device — a bad update can leave you without smart home control until you reflash the SD card.

Automate pre-update snapshots

You can wire this into a Proxmox scheduled task or a simple cron job on the node:

# Add to /etc/cron.d/ha-snapshot
0 3 * * 0 root qm snapshot 200 weekly-$(date +\%Y\%m\%d) --description "Weekly auto-snapshot"

Pair this with a snapshot retention policy to auto-delete snapshots older than 30 days.

Step 9: Essential Add-ons to Install First

Once HA is up and stable, install these add-ons from the official store before anything else:

SSH & Web Terminal

Gives you shell access inside HAOS for debugging and scripting:

• Go to Settings → Add-ons → SSH & Web Terminal
• Set a password or SSH key under Configuration
• Enable "Start on boot"

File Editor

A browser-based editor for configuration.yaml and other HA config files. Easier than SSH for quick edits.

Samba share

Mounts the HA config directory as a Windows/macOS network share, so you can edit files from your workstation with VS Code. Huge quality-of-life improvement.

Zigbee2MQTT (if using Zigbee)

Alternative to ZHA with broader device support and more granular control. Requires an MQTT broker (install Mosquitto from the add-on store first).

Performance Tuning

HAOS is not resource-hungry, but a few tweaks improve responsiveness:

Use VirtIO for everything

Make sure the disk is attached as VirtIO SCSI (virtio-scsi-pci), not IDE or SATA. The VirtIO driver dramatically reduces I/O latency for the SQLite database that powers HA's recorder.

Pin CPU cores if you're running a busy node

qm set 200 --cpuunits 1024

This gives the HA VM higher CPU scheduling priority when the node is under load.

Tune the HA recorder

The default recorder keeps 10 days of history for every entity. On a busy network this fills fast. In configuration.yaml:

recorder:
  purge_keep_days: 5
  exclude:
    entity_globs:
      - sensor.*_signal_strength
      - sensor.*_rssi
      - sensor.*_lqi

Excluding noisy sensor readings (signal strength, RSSI, LQI) cuts database size by 30-50% without losing any useful history.

Troubleshooting Common Issues

VM won't boot after first start

Check that UEFI is configured correctly. Go to VM → Hardware and confirm the EFI disk is present. Also verify --bios ovmf is set. A common mistake is importing the disk but forgetting to disable Secure Boot via pre-enrolled-keys=0.

USB dongle not appearing inside HA

Run lsusb on the Proxmox host to confirm the dongle is detected at the host level. If it shows up in lsusb but not in HA, check that the usb0 passthrough entry is set with the correct vendor:product ID. Then fully power cycle (not just reboot) the VM — USB enumeration sometimes requires a cold boot.

HA shows the wrong IP or no IP in Proxmox

The QEMU guest agent may not be running. Verify --agent enabled=1 is set, then check inside HA via Settings → System → Logs for any guest agent errors. The agent service in HAOS is qemu-ga.

Zigbee devices won't pair

Make sure you're using the correct /dev/tty* path. With multiple USB devices, paths can shift. Using Zigbee2MQTT with the adapter's USB ID (not path) is more reliable:

# zigbee2mqtt configuration.yaml
serial:
  port: /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus...

The /dev/serial/by-id/ path is stable and doesn't change between reboots.

Conclusion

Running Home Assistant OS as a Proxmox VM is the most robust setup available in 2026 for homelab smart home enthusiasts. You get the full Supervisor experience with add-ons and one-click restores, backed by Proxmox snapshots that make updates genuinely risk-free.

The key steps are straightforward: download the HAOS .qcow2 image, create a q35 VM with OVMF/UEFI and VirtIO storage, pass through your USB coordinator by vendor:product ID, and enable the QEMU guest agent. From there, snapshot before every update and tune the recorder to keep the database lean.

If you're running Zigbee or Z-Wave devices, USB passthrough is rock-solid in KVM — I've been running the same Sonoff dongle through a Proxmox VM for over a year without a single dropout. The combination of Proxmox's management capabilities and Home Assistant's integration breadth is hard to beat for a centralized smart home hub.