Home Assistant OS on Proxmox

Advanced 30 min Free

Proxmox is a fantastic platform for running Home Assistant OS. You get full VM isolation, snapshots, backups, and the option to run other services on the same hardware.

🤔 Why Proxmox?

Feature	Proxmox VM	Raspberry Pi	Docker
Snapshots	✅ One click	❌ No	❌ No
Live backup	✅ Yes	⚠️ Manual	⚠️ Manual
Hardware passthrough	✅ USB, PCIe	✅ Direct	⚠️ Limited
Resource scaling	✅ Easy	❌ Fixed hardware	✅ Yes
Other VMs/containers	✅ Unlimited	❌ No	✅ Yes
Add-ons support	✅ Full	✅ Full	❌ Separate

Recommended for

• Those who already run a Proxmox server
• Those who want Home Assistant alongside other services
• Those who want enterprise-grade backup and restore

📋 Prerequisites

• ✅ Proxmox VE 8.x or newer installed
• ✅ At least 2 CPU cores available
• ✅ At least 4 GB RAM available
• ✅ At least 32 GB storage (SSD recommended)
• ✅ Access to the Proxmox shell (SSH or web console)

🚀 Method 1: Community Helper Script (Recommended)

The easiest method uses the official community script from community-scripts.github.io/ProxmoxVE.

Open Source

The Proxmox VE Helper Scripts are open source and community-maintained. See the GitHub repository for all available scripts.

1. Log in to the Proxmox shell

   SSH to your Proxmox server or use Shell in the web interface:

   ssh root@YOUR-PROXMOX-IP

2. Run the installation script

   bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/vm/haos-vm.sh)"

3. Follow the installation wizard

   The script will ask about:

   • VM ID: Pick an unused number (e.g. 100)
   • Machine Type: Choose q35 (modern, better performance)
   • BIOS: Choose OVMF (UEFI) - required for HAOS
   • Disk size: Minimum 32GB, recommended 64GB+
   • CPU cores: Minimum 2, recommended 4
   • RAM: Minimum 4096MB, recommended 4096-8192MB
   • Bridge: Your network bridge (typically vmbr0)
   • MAC address: Accept the auto-generated one
   • VLAN: Leave empty unless you use VLANs
   • Start after creation: Yes

4. Wait for the installation

   The script downloads the HAOS image and creates the VM. This takes 2-5 minutes.

5. Find the IP address

   Once the VM has started, find its IP via:

   # In the Proxmox shell
   qm guest cmd VMID network-get-interfaces

   Or check your router’s DHCP list.

Script features

The script automatically configures:

• UEFI boot with an EFI disk
• VirtIO SCSI controller (best performance)
• CPU type host (full CPU feature support)
• QEMU Guest Agent
• Optimal disk cache settings

🔧 Method 2: Manual installation

If you prefer full control, you can install manually.

Download the HAOS image

1. Find the latest version

   Go to Home Assistant OS releases and find the latest qcow2 file for KVM/Proxmox.

2. Download to Proxmox

   # SSH to Proxmox
   cd /var/lib/vz/template/iso/
   
   # Download latest HAOS (replace VERSION with the current one)
   wget https://github.com/home-assistant/operating-system/releases/download/VERSION/haos_ova-VERSION.qcow2.xz
   
   # Extract
   xz -d haos_ova-VERSION.qcow2.xz

Create the VM manually

1. Create a VM without a disk

   # Replace VMID with your desired ID (e.g. 100)
   qm create VMID \
     --name haos \
     --memory 4096 \
     --cores 2 \
     --cpu host \
     --bios ovmf \
     --machine q35 \
     --net0 virtio,bridge=vmbr0 \
     --ostype l26 \
     --agent 1 \
     --onboot 1

2. Add an EFI disk

   qm set VMID --efidisk0 local-lvm:1,efitype=4m

3. Import the HAOS disk

   # Import qcow2 into the VM
   qm importdisk VMID /var/lib/vz/template/iso/haos_ova-VERSION.qcow2 local-lvm
   
   # Attach the disk to the VM
   qm set VMID --scsi0 local-lvm:vm-VMID-disk-1,cache=writethrough,discard=on,ssd=1
   
   # Set boot order
   qm set VMID --boot order=scsi0

4. Start the VM

   qm start VMID

⚙️ Recommended VM settings

Optimal configuration

Setting	Value	Explanation
Machine	q35	Modern chipset, better USB/PCIe
BIOS	OVMF (UEFI)	Required for HAOS
CPU Type	host	Full CPU support
CPU Cores	2-4	2 minimum, 4 recommended
RAM	4096-8192 MB	4 GB minimum
SCSI Controller	VirtIO SCSI	Best disk performance
Disk Cache	Write through	Safe, good performance
Network	VirtIO	Best network performance
QEMU Agent	Enabled	Snapshots, IP display

Example configuration file

/etc/pve/qemu-server/VMID.conf

agent: 1
bios: ovmf
boot: order=scsi0
cores: 4
cpu: host
efidisk0: local-lvm:vm-VMID-disk-0,efitype=4m,size=4M
machine: q35
memory: 4096
name: haos
net0: virtio=XX:XX:XX:XX:XX:XX,bridge=vmbr0
onboot: 1
ostype: l26
scsi0: local-lvm:vm-VMID-disk-1,cache=writethrough,discard=on,size=32G,ssd=1
scsihw: virtio-scsi-pci

🔌 USB Passthrough (Zigbee/Z-Wave)

To use USB devices (Zigbee coordinator, Z-Wave stick) in Home Assistant:

1. Find the USB device ID

   # On the Proxmox host
   lsusb

   Example output:

   Bus 002 Device 003: ID 1a86:55d4 QinHeng Electronics SONOFF Zigbee 3.0 USB Dongle Plus V2

2. Add it to the VM

   # Format: vendor:product (from the lsusb output)
   qm set VMID --usb0 host=1a86:55d4

   Or via the web interface:

   • Select the VM → Hardware → Add → USB Device
   • Select Use USB Vendor/Device ID
   • Pick your device from the list

3. Restart the VM

   qm reboot VMID

USB passthrough tip

Use the Vendor/Device ID rather than a USB Port. That way it keeps working even if you plug the USB device into a different port.

💾 Expand the disk size

If you run out of space:

1. Expand in Proxmox

   Via the CLI:

   qm resize VMID scsi0 +50G

   Or via the web interface:

   • VM → Hardware → Select the disk → Resize

2. Expand in Home Assistant

   HAOS expands automatically on the next reboot, or:

   • Settings → System → Storage → Resize

📸 Backup and Snapshots

Snapshots (fast)

Perfect before updates or experiments:

# Create snapshot
qm snapshot VMID pre-upgrade --vmstate 1

# Restore snapshot
qm rollback VMID pre-upgrade

# Delete snapshot
qm delsnapshot VMID pre-upgrade

Snapshot best practice

Always take a snapshot BEFORE major Home Assistant updates. Give it a descriptive name, e.g. pre-2024.12-upgrade.

Backups (full)

For disaster recovery:

# Manual backup
vzdump VMID --compress zstd --storage local --mode snapshot

# List backups
ls /var/lib/vz/dump/

Or schedule automatic backups via Datacenter → Backup in the web interface.

🌐 First-time setup

1. Open Home Assistant

   Go to http://HAOS-IP:8123 in your browser.

   Note

   The first boot takes 5-20 minutes. You will see “Preparing Home Assistant” until it is ready.

2. Create a user

   • Choose a username and a strong password
   • Store the password in a password manager!

3. Configure your home

   • Name your home
   • Set your location (for sunrise/sunset)
   • Pick your time zone

4. Update everything

   Go to Settings → System → Updates and install all available updates.

🔧 Troubleshooting

VM won't start?

Check these things:

1. Is the BIOS set to OVMF (UEFI)? HAOS requires UEFI.
2. Is the boot order correct? It should be scsi0 or virtio0.
3. Do you have enough RAM? Minimum 4 GB, recommended 4-8 GB.
4. Check the task log in the Proxmox web interface or journalctl -u pvedaemon

No network?

Try these fixes:

1. Check that the bridge is correct (typically vmbr0)
2. Check that the VLAN settings match your network
3. Try restarting the VM
4. Check the firewall rules on Proxmox

USB device not working?

Check:

1. Was the USB passthrough added correctly?
2. Restart the VM after adding the USB device
3. Check dmesg on Proxmox for USB errors
4. Try a different USB port on the host

Slow performance?

Optimizations:

1. Use cache=writethrough on the disk
2. Use cpu: host instead of kvm64
3. Enable discard=on,ssd=1 on the disk
4. Increase RAM to 4-8 GB

🔄 Updating HAOS

Home Assistant is updated through the web interface:

1. Settings → System → Updates
2. Click Update on the available updates
3. Wait for the restart

Before updating

ALWAYS take a snapshot before major updates:

qm snapshot VMID pre-upgrade-$(date +%Y%m%d) --vmstate 1

🚀 Next steps

⚡ First automation

Create your first automation in Home Assistant.

Create automations →

📡 Zigbee2MQTT

Add Zigbee devices with USB passthrough.

Set up Zigbee →