home-assistant

Home Assistant on Proxmox: Complete Setup Guide

Frank Stupak

— 5 min read
Home Assistant on Proxmox: Complete Setup Guide

Prerequisites

You'll need a Proxmox host running version 8.1+ (tested on 8.2.2 LTS) with at least 8GB RAM available for the HAOS VM, SSD storage for acceptable performance, and ideally a USB device for Zigbee/Z-Wave integration. I'm running this on a 2-socket Xeon E5-2620 with 64GB RAM and a 500GB NVMe—overkill for Home Assistant alone, but you're sharing the hypervisor.

Download the Home Assistant OS KVM image from the official Home Assistant installation page—you want the QEMU image (haos_ova-*.qcow2), not the generic KVM image. For this setup, I'm using HAOS 2024.1.4.

Creating the HAOS VM in Proxmox

First, upload the QEMU image to your Proxmox storage. SSH into your Proxmox host and place the image in the images directory:

wget https://github.com/home-assistant/operating-system/releases/download/12.3/haos_ova-12.3.qcow2.xz
xz -d haos_ova-12.3.qcow2.xz
mv haos_ova-12.3.qcow2 /var/lib/vz/images/

Now create the VM from the web UI. Go to Proxmox Console → Create VM:

  • Name: home-assistant
  • VM ID: 100 (or next available)
  • Storage: local or your preferred node storage

Skip to the Hardware tab. You'll import the disk manually. Add these components:

# Via CLI for faster setup:
qm create 100 \
  --name home-assistant \
  --memory 4096 \
  --cores 4 \
  --net0 virtio,bridge=vmbr0 \
  --serial0 socket \
  --vga qxl \
  --scsihw virtio-scsi-single

# Import the disk
qm importdisk 100 /var/lib/vz/images/haos_ova-12.3.qcow2 local --format qcow2

# Attach the disk to SCSI controller
qm set 100 --scsi0 local:vm-100-disk-0

Gotcha #1: If you use the web UI import, Proxmox sometimes attaches the disk to IDE instead of SCSI. Verify in Hardware that it's on SCSI0—you'll get hung boot prompts otherwise.

Set boot order to disk and start the VM. HAOS will take 2-3 minutes on first boot to initialize the partition table. You'll see it cycling through resize prompts—let it finish.

Initial Home Assistant Configuration

Once HAOS boots, it broadcasts via mDNS. Find it:

avahi-browse -a | grep homeassistant
# Or check your DHCP lease
cat /var/lib/dnsmasq/dnsmasq.leases | grep -i home

Navigate to http://homeassistant.local:8123 (or use the IP directly). The first-boot wizard takes about 30 seconds. Create your user account—this becomes your primary admin. Home Assistant generates a default location; update it with your actual coordinates if you care about sunrise/sunset automations.

Gotcha #2: If you get "Couldn't connect to Home Assistant" on the wizard's final step, the backend supervisor is still initializing. Wait 2 minutes and refresh—don't restart the VM yet.

USB Passthrough for Zigbee Devices

This is where Proxmox Home Assistant shines over bare-metal installs. You can pass a Zigbee coordinator (I use a Sonoff Zigbee 3.0 dongle) directly to the VM without losing USB functionality on the host.

First, identify your USB device on the Proxmox host:

lsusb | grep -i zigbee
# Output: Bus 001 Device 005: ID 1a86:55d4 QinHeng Electronics USB Single Serial Converter Module

# Or by path:
ls -la /dev/serial/by-id/ | grep -i usb
# Output: usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_...-if00-port0

Now attach the device to the VM via the Proxmox API (the web UI USB passthrough doesn't persist across reboots reliably):

# Via qm command
qm set 100 --usb0 host=1a86:55d4

# Or add it to /etc/pve/qemu-server/100.conf manually:
usb0: host=1a86:55d4,usb3=1

Restart the VM and verify from within Home Assistant. Go to Settings → Devices & Services → Integrations → Zigbee Home Automation. It should auto-discover the serial device at /dev/ttyUSB0 or /dev/ttyACM0. If not, add it manually—the device path is consistent on HAOS.

Add-ons and Integration Setup

Home Assistant's killer feature is its add-ons ecosystem. Essential ones for a mature setup:

Terminal & SSH: Go to Settings → Add-ons & integrations → Create add-on → search "Terminal". This gives you a native terminal inside Home Assistant without exposing SSH to the network. Configure it with a password-only authentication (SSH keys via the web UI are clunky).

File editor: Grab the Official SSH & Web Terminal add-on for YAML editing. Install, enable, and set your SSH key:

# Add-on config (in Home Assistant UI)
password: "your-strong-pass-here"
authorized_keys:
  - ssh-rsa AAAAB3NzaC1... [email protected]

# Test from Proxmox host
ssh -p 22222 [email protected]

Zigbee2MQTT (optional, but superior to ZHA): If you prefer Zigbee2MQTT over the native ZHA integration, install the add-on, mount your USB device in the add-on config, and configure the serial port:

# File: /config/addons/zigbee2mqtt/options.json
{
  "serial": {
    "port": "/dev/ttyUSB0"
  },
  "frontend": {
    "port": 8081
  }
}

Start it and verify logs show device recognition. Web UI is at homeassistant.local:8081.

Backup Strategy and Storage

Home Assistant backups are critical—they're your entire configuration. Enable automated backups in Settings → System → Backups → Create backup. Schedule daily at 2 AM, then pull backups off the VM.

I mount an NFS share from my TrueNAS to store backups outside the VM:

# On the Proxmox host, mount the NFS share
mkdir -p /mnt/backups
mount -t nfs 192.168.1.50:/mnt/tank/backups /mnt/backups

# Inside the HAOS VM, via SSH add-on
mkdir -p /mnt/external-backups

# Edit /etc/fstab in the VM (via SSH terminal)
echo "192.168.1.50:/mnt/tank/backups /mnt/external-backups nfs defaults 0 0" >> /etc/fstab
mount -a

Then set Home Assistant's backup directory to /mnt/external-backups in the Supervisor settings. Backups now persist independently of the VM disk.

Verification: Trigger a manual backup from the UI and confirm the file appears on the NFS share:

ls -lh /mnt/backups/*.tar | head -1
# Should show a recent tar file ~500MB-2GB depending on your data

Common Issues and Gotchas

VM won't boot after USB passthrough: The device isn't available at boot time. Add a small delay: edit /etc/pve/qemu-server/100.conf and add args: -global usb-host.hostdevices=1a86:55d4,delay-ms=2000. This won't break anything and gives USB time to enumerate.

Sluggish web UI after add-on install: You're low on RAM. The HAOS VM defaults to 4GB. Increase it to 6-8GB if you run Zigbee2MQTT, MariaDB for history, and the SSH terminal simultaneously. Edit in the web UI or via qm set 100 --memory 8192 (requires shutdown).

Home Assistant can't see NFS-mounted backups: Permission issue. The HAOS supervisor runs as root, but NFS mounts might enforce root_squash. On your NFS server, allow root access for the Proxmox subnet, or use no_root_squash for that export (careful with security implications).

Serial device disappears on reboot: USB device was disconnected or re-enumerated. This is physical flakiness, not a Proxmox issue. Try a powered USB hub or a different USB port on your Proxmox host. If using a USB extension cable, shorten or remove it—USB3 is fussy.

What You Now Have

You're running Home Assistant OS as a resilient Proxmox VM with hardware-backed Zigbee integration, persistent backups on external storage, and terminal access for advanced config. The setup scales: you can snapshot the VM, nest it in a cluster, or rebuild from backup in minutes.

Next steps: configure your first integration (Zigbee, MQTT, or a cloud service like Nabu Casa), create a few automations to test the rules engine, and build out your device inventory. If you're running multiple IoT protocols (Zigbee + Z-Wave), add a second USB device via passthrough—Proxmox handles it seamlessly.

Read more