What is the best way to install Home Assistant on Proxmox?

The recommended method is to run Home Assistant OS (HAOS) inside a dedicated virtual machine, not a container. HAOS is the full, officially supported Home Assistant experience — it includes the Supervisor and the Add-on store, which the container and core installs do not. On Proxmox the easiest way to create this VM is the community helper script (from the community-scripts/ProxmoxVE project), which downloads the official Home Assistant KVM disk image and builds the VM for you in a couple of minutes.

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

Home Assistant OS is designed to run as a complete operating system on its own virtual machine, which is what unlocks Add-ons, the Supervisor, and easy full-system backups. Running Home Assistant in an LXC container is unsupported by the project and breaks the Add-on store, because Add-ons themselves run as Docker containers and cannot nest cleanly inside an LXC. For a reliable, upgradable smart-home hub, use a VM.

How do I pass a Zigbee or Z-Wave USB stick to Home Assistant on Proxmox?

Plug the USB coordinator into the Proxmox host, then add it to the Home Assistant VM through the VM's Hardware tab as a USB Device (select it by its USB ID so it survives reboots). Because Home Assistant runs in a VM, the whole USB device is passed through cleanly, and ZHA or Zigbee2MQTT inside Home Assistant will detect it as a serial port.

How much RAM and CPU does Home Assistant need on Proxmox?

A typical Home Assistant OS VM runs comfortably with 2 virtual CPUs, 4GB of RAM, and a 32GB disk. Light setups work on 2GB, but 4GB gives headroom for Add-ons like Zigbee2MQTT, Mosquitto, ESPHome, and Frigate. The community helper script defaults are a sensible starting point and everything can be increased later from the Proxmox VM Hardware tab.

Run Home Assistant on Proxmox the Right Way (HAOS in a VM)

On this page

The four installs, and why you want HAOS
Install it with the community helper script
Add a Zigbee or Z-Wave stick (the payoff move)
What to build next

Home Assistant is the reason a huge number of people build a homelab in the first place. It’s the open-source brain for your smart home — local, private, and vendor-neutral, tying together lights, sensors, locks, cameras, and thousands of other devices without shipping your data to anyone’s cloud.

There’s just one catch that trips up nearly every beginner: there are four ways to install it, and only one of them is the good one on Proxmox. Pick wrong and you’ll spend a weekend fighting a broken Add-on store. Let’s get it right the first time.

The four installs, and why you want HAOS

Home Assistant OS is a complete, purpose-built operating system. When you run it as a VM, you get the full Home Assistant: the Supervisor that manages the system, the one-click Add-on store (Zigbee2MQTT, Mosquitto, ESPHome, Frigate, and more), and painless whole-system backups.

Don't run Home Assistant in an LXC

You’ll find guides that shoehorn Home Assistant into a Proxmox LXC container. Resist. Add-ons are themselves Docker containers, and nesting Docker inside an unprivileged LXC is fragile and unsupported by the Home Assistant project. A VM is the officially blessed path, and on modern hardware the overhead is negligible. Read VM vs LXC if you want the full reasoning.

Install it with the community helper script

The official Home Assistant team publishes a ready-made KVM disk image. The community-scripts helper project (the actively maintained continuation of the beloved tteck scripts) wraps the whole download-import-configure dance into a single command.

1Open a shell on the Proxmox host

In the Proxmox web UI, click your node, then Shell. Run the helper command here on the host — not inside an existing container. It creates a brand-new VM for you.

Run on the Proxmox node shell


bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/vm/haos-vm.sh)"

Always read a script before you pipe it to bash

Running a script straight from the internet deserves a second of caution. The community-scripts project is open-source and widely used — you can read exactly what haos-vm.sh does on its GitHub page before running it. This is good hygiene for any curl-to-bash command, not just this one.

2Accept or tweak the defaults

The script asks a few questions — storage location, RAM, disk size — then downloads the official Home Assistant OS image, imports it as a disk, attaches it, sets the boot order, and starts the VM. The defaults (2 vCPU, ~4GB RAM) are fine for a first setup. Total time: a couple of minutes.

3Find the VM's address and open onboarding

When it finishes, the VM boots Home Assistant. Give it a minute, then browse to http://homeassistant.local:8123 (or http://VM-IP:8123 if mDNS doesn’t resolve on your network). You’ll be greeted by the onboarding wizard.

4Create your account and let it discover your devices

Set up your owner account, name your home, and set your location. Home Assistant immediately scans your network and often finds smart devices (Chromecasts, printers, smart plugs, Philips Hue bridges) automatically. Add them, or skip and add them later — the dashboard is yours now.

Add a Zigbee or Z-Wave stick (the payoff move)

The moment Home Assistant becomes magic is when you add a Zigbee coordinator (like a SkyConnect / Home Assistant Connect ZBT-1 or a Sonoff dongle) and start pairing cheap, cloud-free sensors and bulbs. Because you’re running a VM, USB passthrough is clean:

1Plug the stick into the Proxmox host

Physically insert the USB coordinator into the machine running Proxmox.

2Pass it through to the VM

In the Proxmox UI: select the Home Assistant VM → Hardware → Add → USB Device → pick your coordinator by its Device ID (not the port), so it survives reboots and reordering. Then reboot the VM.

3Install the ZHA or Zigbee2MQTT integration

Inside Home Assistant, the passed-through stick appears as a serial device. Add the built-in ZHA integration (simplest) or the Zigbee2MQTT Add-on (more powerful) and start pairing devices.

Back it up the easy way

Because this is HAOS, Settings → System → Backups gives you a one-click full backup of your entire configuration and Add-ons. Even better, since it’s a Proxmox VM, you also get whole-VM snapshots and scheduled backups from Proxmox Backup Server — belt and suspenders for the hub that runs your house.

What to build next

You’ve now got the single most-loved service in the homelab world running properly. From here, most people:

Put it behind clean HTTPS and reach it from anywhere with Tailscale.
Add it as a tile on their Homepage dashboard alongside every other service.
Wire in local voice and AI with Ollama so the assistant answers without the cloud.

Home Assistant is a rabbit hole all of its own — and now it’s running on a foundation that won’t fight you. Back to the full roadmap whenever you’re ready for the next piece.

Related posts:

Creating Your First Proxmox VM — the VM workflow HAOS runs in
Proxmox VM vs LXC: When to Use Each — why Home Assistant OS wants a full VM
Proxmox LXC Networking: Bridges, VLANs, and Static IPs — give Home Assistant a stable address
Pi-hole on Proxmox LXC — local DNS for your smart-home devices
CPU-Only Ollama Cluster with LXC — local AI/voice for the assistant
Tailscale Subnet Router — reach your dashboard away from home

Comments

Comments are powered by GitHub Discussions — sign in with a GitHub account to join the conversation.