Homelab & Virtualization

Home Assistant OS on Proxmox: Running Your Smart Home as a VM

The two real install paths, first boot, passing through a Zigbee or Z-Wave coordinator, and why snapshots are the whole reason to do this on Proxmox in the first place.

Home Assistant OS is, for a lot of people, the single most common reason to spin up a Proxmox host at all. Rather than dedicating a Raspberry Pi or an old mini PC to it, giving it its own VM on a cluster you're already running gets you the full Home Assistant appliance experience, Supervisor, Add-on Store, and automatic updates included, plus a safety net Home Assistant can't give you on its own: a VM-level snapshot you can roll back to in seconds if an update goes sideways.

Why a VM Instead of Docker or Bare Metal

Home Assistant ships three different ways: Home Assistant OS (the full appliance image, with a Supervisor managing add-ons and updates), Home Assistant Container (a plain Docker image with none of that), and Home Assistant Core (a Python install with even less). Only HAOS includes the Supervisor, which is what powers the Add-on Store, one-click backups, and OS-level updates from inside the Home Assistant UI itself. Running the Container image is a reasonable choice if you're already comfortable managing everything by hand, but it gives up the exact things that make the OS image worth choosing.

Running that OS image as a VM rather than on dedicated hardware adds one more layer on top: a Proxmox snapshot. Home Assistant's own update process has broken configurations before, badly enough that a rollback path matters, and a VM snapshot taken thirty seconds before clicking "update" turns a bad update from an afternoon of troubleshooting into a few clicks.

Getting It Running

There are two real ways to get Home Assistant OS running as a Proxmox VM, and both end up booting the identical, official HAOS image. The difference is just how much of the VM configuration you want handled for you.

Community script (recommended for most people): run bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/vm/haos-vm.sh)" on the Proxmox shell. It downloads the current stable HAOS release straight from Home Assistant's own GitHub, and builds the VM correctly around it: q35 machine type, OVMF (UEFI) firmware with an EFI disk, and a VirtIO SCSI controller, at 2 vCPUs, 4GB RAM, and a 32GB disk by default. The VM boots directly into Home Assistant OS with no separate installer step.
Manual qcow2 import: download the .qcow2 image from Home Assistant's own alternative installation page, create an empty VM with UEFI (OVMF) firmware and a VirtIO SCSI disk (HAOS requires UEFI to boot), then import the image onto that disk with qm importdisk. This is the path if you want full control over every VM setting or you'd rather not run a third-party script against your hypervisor.

Either way, plan on at least 32GB of disk and 4GB of RAM once you're running more than a couple of add-ons; the documented floor of 2GB RAM is workable for a bare install but gets tight fast with anything doing local voice processing, camera analysis, or Zigbee2MQTT.

First Boot and Onboarding

Give the VM a few minutes on first start; HAOS expands its filesystem and starts the Supervisor before anything answers on the network. Once it's up, point a browser at http://homeassistant.local:8123 (or the VM's IP address on port 8123 if local hostname resolution isn't working on your network) and the onboarding wizard walks through creating your first administrator account, setting your location and unit system, and an initial device-discovery scan of your local network.

From there, the Add-on Store and Integrations page are the two places you'll spend the most time: integrations connect Home Assistant to devices and services directly, while add-ons run alongside it as their own small containers, things like a Zigbee2MQTT bridge, a MQTT broker, or a local voice assistant.

Passing Through a Zigbee or Z-Wave Coordinator

Most Home Assistant setups eventually add a USB Zigbee or Z-Wave coordinator (a SkyConnect, ConBee, or a generic CC2652-based stick are common choices), and passing one through to a VM correctly matters more than it looks like it should. In the VM's Hardware tab, choose Add → USB Device, then select Use USB Vendor/Device ID rather than a specific USB port. Plug the coordinator in before adding it so Proxmox can list it in the device dropdown, then reboot the VM afterward for Home Assistant to see it.

The reason to pick vendor/device ID over a port mapping: the ID stays attached to that exact device no matter which physical port it ends up in, while a port-based mapping can silently point at whatever's plugged into that port after a host reboot or a cable getting bumped, sometimes not what you meant to pass through at all.

Snapshot Before Every Update

This is the actual payoff of running HAOS as a VM. Home Assistant releases roughly monthly, and breaking changes to automations or integrations aren't rare enough to ignore. Before clicking update, take a Proxmox snapshot of the VM; if the update breaks something, roll back to that exact snapshot in under a minute instead of troubleshooting a half-migrated config.

Keep Home Assistant's own backups running too (Settings → System → Backups). They cover a different failure mode: a portable export of your configuration, automations, and add-on data that restores even onto different hardware later, which a Proxmox snapshot tied to one specific VM can't do.

A Few Things That Trip People Up

HAOS as a VM is low-maintenance once it's running, but a couple of rough edges show up early. Bluetooth passthrough works the same way as USB passthrough (by device ID), but Bluetooth integrations tend to be pickier about latency, so a Bluetooth proxy ESPHome device on your network is often more reliable than passing a host Bluetooth adapter straight into the VM. And because HAOS boots and manages its own OS layer, it doesn't take Proxmox LXC-style shared-kernel shortcuts. It needs to be a full VM, which is a firmer requirement here than with most of the other apps on this site.

If you're running anything add-on-heavy (Frigate for camera AI, local voice processing, a Matter server), keep an eye on RAM headroom specifically; HAOS itself is light, but a handful of resource-hungry add-ons can quietly eat past whatever you allocated at install time. Bumping the VM's RAM later is a normal Proxmox hardware edit, no reinstall required.

A Few Things I'd Get Right From the Start

1. Pass USB devices by vendor/device ID, never by port

Covered above, but it's worth repeating: a port-based USB mapping is the single most common reason a Zigbee network silently stops responding after a host reboot.

2. Snapshot before every update, not just the big ones

Point releases occasionally break something too. The snapshot takes seconds; skipping it only saves those same few seconds.

3. Give it 4GB of RAM even if you start small

The 2GB documented minimum works for a bare install, but almost everyone ends up adding at least one add-on that wants more headroom than that leaves.

4. Don't put it on the same node as anything Zigbee-latency-sensitive

If your cluster has more than one node, keeping Home Assistant on a node with light, predictable CPU load helps avoid the small automation delays that show up under heavy contention elsewhere.

5. Set the VM to start on boot

An easy one to miss during setup. If the host ever reboots unattended, you want Home Assistant back online without having to remember to start it manually.

Related Resources

Official Virtualization Images

The qcow2/vmdk/ova images this guide's manual method uses.

Proxmox VE Helper Scripts: HAOS

The community script this guide's easy path runs.

Zigbee Integrations

Comparing ZHA against a standalone Zigbee2MQTT add-on.

Proxmox Updates

What's new in Proxmox VE, kept current with a live feed.

Docker on Proxmox & Windows

The LXC-first pattern for services that don't need a full VM.

OpenClaw AI Homelab

Another self-hosted service that fits well alongside a home-automation VM.

Frequently Asked Questions

Why run Home Assistant OS instead of the Home Assistant Container or Core install?

HAOS is the only install method that includes the Supervisor, which is what gives you the built-in Add-on Store, one-click backups, and automatic updates from the Home Assistant UI itself. Home Assistant Container (a plain Docker image) and Core (installed straight into a Python virtual environment) both skip the Supervisor, so you'd manage add-ons, backups, and updates yourself. Running HAOS as its own Proxmox VM gets you the full appliance experience plus Proxmox-level snapshots on top, which neither Container nor Core can offer on their own.

Should I use the community script or the official qcow2 image?

The community script is faster and configures the VM correctly for you (q35 machine type, OVMF/UEFI firmware, VirtIO SCSI disk) in one command, so it's the better starting point for most people. The manual qcow2 import from Home Assistant's own download page is worth knowing if you want full control over VM settings, are scripting a repeatable deployment, or just don't want to run a third-party script against your hypervisor. Both end up running the identical, official Home Assistant OS image. The difference is purely in how the VM around it gets built.

How do I pass through a Zigbee or Z-Wave USB coordinator?

Add it in the VM's Hardware tab as a USB Device and pick "Use USB Vendor/Device ID" rather than a specific USB port. Device IDs stay the same no matter which physical port the dongle is plugged into or what happens after a host reboot, while a port-based mapping can silently point at the wrong device the next time your hardware re-enumerates. Plug the coordinator in before adding it so Proxmox can list it, and reboot the VM after adding it for Home Assistant to see it.

What are the minimum specs for the VM?

Home Assistant's own documentation lists 2 vCPUs and 2GB of RAM as the floor, with 32GB of disk recommended. In practice, the moment you start running add-ons, especially anything doing local voice processing, camera analysis, or a Zigbee2MQTT/Matter server, 4GB of RAM is a much more comfortable baseline, which is also what the community install script provisions by default.

Should I still back up Home Assistant itself, or is a Proxmox snapshot enough?

Keep both. A Proxmox snapshot protects you at the VM level, useful right before an OS or Supervisor update, while Home Assistant's own built-in backups (Settings -> System -> Backups) capture your configuration, automations, and add-on data in a portable format you can restore even onto different hardware later. They cover different failure modes, and both are quick enough that there's no real reason to pick just one.

Can Home Assistant OS run in an LXC container instead of a VM?

Not officially, and it's not worth fighting. HAOS is built and only tested as a full appliance image, expecting to own its own kernel and boot process the way a VM provides; LXC containers share the host's kernel instead. People have gotten a stripped-down Home Assistant Core running in an LXC, but you lose the Supervisor, the Add-on Store, and OS-level auto-updates in the process, which are the exact things that make HAOS worth choosing over Container or Core to begin with.