LinuxautomationTested on real hardware

Home Assistant OS VM on Proxmox (community-scripts helper)

Create a Home Assistant OS virtual machine on Proxmox using the community-scripts helper. One command on the Proxmox shell downloads the official HAOS KVM image, builds the VM, and boots it.

Distrosproxmox
Shellbash
Updated
Script
bash
#!/usr/bin/env bash
# Run this on the PROXMOX NODE SHELL — not inside a container or VM.
# Creates a Home Assistant OS VM using the community-scripts helper.
# Source: https://community-scripts.github.io/ProxmoxVE/scripts?id=haos-vm
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/vm/haos-vm.sh)"

What this does

Runs the community-scripts Home Assistant OS helper on a Proxmox node shell. The script:

  1. Downloads the official Home Assistant OS KVM disk image (.qcow2) directly from the Home Assistant project’s GitHub releases.
  2. Imports it as a Proxmox VM disk.
  3. Configures CPU, RAM, firmware (OVMF/UEFI), and boot order.
  4. Starts the VM.

The community-scripts project is the actively maintained fork of the original tteck helper scripts (continued after tteck’s passing in 2024). It is open-source — review haos-vm.sh before running.

Why this approach

Home Assistant is one of the few homelab applications that works best as a full virtual machine rather than a Docker container or LXC. The official Home Assistant OS (HAOS) distribution includes a supervisor that manages add-ons, automatic updates, snapshot backups, and hardware integrations — all features that depend on having full OS control. The Docker container version (homeassistant/home-assistant) has none of the supervisor, no add-ons, and no built-in backup system. For a serious home automation setup where you want the full ecosystem (add-ons like the Mosquitto MQTT broker, Z-Wave JS UI, Zigbee2MQTT), HAOS is the right target.

Running HAOS as a Proxmox VM gives you the best of both worlds: HAOS gets full OS control inside the VM, and Proxmox gives you snapshotting, live migration, and hardware pass-through from outside it. You can snapshot the VM before a major update, roll back if something breaks, and move the whole Home Assistant instance to a different node without reinstallation. These operations are much harder or impossible with a Docker-based deployment.

The community-scripts helper (continued from the original tteck scripts) is the recommended way to install HAOS on Proxmox because it automates a process that involves downloading a .qcow2 image, importing it as a VM disk, configuring UEFI/OVMF firmware, and setting up the boot order correctly — about ten manual steps that are easy to get wrong. The script is open source and actively maintained; review it before running if you’re cautious about piping scripts directly to shell, which is a reasonable instinct.

Prerequisites

  • Proxmox VE 8.x or 9.x on the target node
  • Shell access on the Proxmox node (not a container) — via the Proxmox web UI → node → Shell, or SSH
  • Internet access from the Proxmox node (to download the HAOS image)
  • Sufficient storage: the VM disk is ~6 GB; the recommended final disk size is 32 GB (the script expands it)

What the script will ask

The script presents an interactive menu. Defaults are sensible for most homelabs:

Prompt Recommended default Notes
VMID next available Accept the suggested ID
Hostname haos Change if you like
RAM 4096 MB Use 2048 for light setups; 4096 gives headroom for Add-ons
CPU cores 2 4 if the host has cores to spare
Disk size 32 GB Minimum; increase for large Add-on installs
Storage your default storage Pick local-lvm or an SSD pool
Machine type q35 Default; required for USB passthrough

After the script completes

  1. Wait ~60 seconds for HAOS to boot.
  2. Open http://homeassistant.local:8123 or http://VM-IP:8123.
  3. Complete the onboarding wizard (create an owner account, set location).

Find the VM’s IP from the Proxmox summary tab or:

# On the Proxmox host:
qm guest exec VM-ID -- ip -4 addr show | grep inet

USB device passthrough (Zigbee / Z-Wave sticks)

Proxmox UI → HA VM → Hardware → Add → USB Device
→ select "Use USB Vendor/Device ID"
→ pick your coordinator by ID (e.g. 10c4:ea60 for CP2102-based sticks)

Selecting by Device ID (not port) ensures the stick is found after reboot even if plugged into a different USB slot.

Resize the disk later

# On the Proxmox host — replace 101 with your VMID:
qm resize 101 scsi0 +20G
# Then inside Home Assistant OS terminal:
# Settings → System → Storage → resize is handled automatically on HAOS boot

Backups

Because this is a proper VM, you get two independent backup mechanisms:

  • HAOS Supervisor backup — Settings → System → Backups inside Home Assistant. Creates a .tar of config, Add-ons, and data.
  • Proxmox VM snapshot / PBS backup — backs up the entire VM disk, including the OS and all data. Configured in Datacenter → Backup.

Recommended: run both. HAOS backups are portable; PBS backups are the fast full-restore path.

Updating Home Assistant OS

Home Assistant notifies you in the UI when updates are available. Updates are applied from Settings → System → Updates. The HAOS updater handles the OS, Supervisor, core, and Add-on updates independently.

macOS / Windows note

This playbook runs on the Proxmox server itself (Linux). No client-side install is needed on macOS or Windows — use the Proxmox web UI’s built-in Shell or SSH into the Proxmox node and run the command there.

All playbooks