How to Install Home Assistant on Proxmox

If you are figuring out how to install home assistant on proxmox, use Home Assistant OS (HAOS) in a KVM virtual machine. Home Assistant recommends HAOS for most users, while the Container install lacks Supervisor-managed apps. A whole VM feels extravagant, but it beats losing Saturday to Docker-inside-LXC archaeology. The official Linux guide confirms KVM support, UEFI, and a minimum of two vCPUs and 2 GB RAM.

Who this is for / who should skip

This is for someone who already runs Proxmox, wants other VMs beside Home Assistant, and needs straightforward USB passthrough and recovery. Budget about an hour for installation; integrations and radios take longer.

Skip Proxmox if the mini-PC will run only Home Assistant. Bare-metal HAOS or Home Assistant Green is simpler. Skip unofficial HAOS-in-LXC setups unless maintaining the container boundary is the hobby. A VM follows Home Assistant’s supported KVM model.

Hardware that works

An N100 mini-PC such as a Beelink Mini S12 Pro or GMKtec NucBox G3 is a sensible host. Intel lists four cores, VT-x, and VT-d. Enable virtualization in firmware. Give HAOS two vCPUs and 4 GB RAM, leaving the rest for Proxmox.

An Intel NUC 13 offers more headroom but is unnecessary for Home Assistant alone. Use wired Ethernet; bridging Wi-Fi through Proxmox is avoidable pain. Keep the VM disk local. A Synology DS923+ supports NFS and suits backup duty, but a live database on the NAS adds an unnecessary dependency.

The stack: HAOS as a Proxmox VM

Compose and k3s do not apply: HAOS is the guest operating system. Run this in the Proxmox node shell as root after changing VMID, STORAGE, and BRIDGE. It refuses an existing VM ID and downloads the current official OVA QCOW2.

set -eu

VMID=120
STORAGE=local-lvm
BRIDGE=vmbr0

if qm status "$VMID" >/dev/null 2>&1; then
  echo "VMID $VMID already exists" >&2
  exit 1
fi
pvesm status | awk 'NR > 1 {print $1}' | grep -qx "$STORAGE"
ip link show "$BRIDGE" >/dev/null

INSTALL_DIR="$(mktemp -d /tmp/haos-proxmox.XXXXXX)"
trap 'rm -f "$INSTALL_DIR/haos.qcow2" "$INSTALL_DIR/haos.qcow2.xz"; rmdir "$INSTALL_DIR"' EXIT

HAOS_URL="$(python3 - <<'PY'
import json
import urllib.request

request = urllib.request.Request(
    "https://api.github.com/repos/home-assistant/operating-system/releases/latest",
    headers={"Accept": "application/vnd.github+json", "User-Agent": "haos-proxmox-install"},
)
with urllib.request.urlopen(request) as response:
    release = json.load(response)

matches = [
    asset["browser_download_url"]
    for asset in release["assets"]
    if asset["name"].startswith("haos_ova-")
    and asset["name"].endswith(".qcow2.xz")
]
if len(matches) != 1:
    raise SystemExit("Could not identify the HAOS OVA QCOW2 asset")
print(matches[0])
PY
)"

curl --fail --location "$HAOS_URL" --output "$INSTALL_DIR/haos.qcow2.xz"
unxz "$INSTALL_DIR/haos.qcow2.xz"

qm create "$VMID" \
  --name home-assistant \
  --ostype l26 \
  --machine q35 \
  --bios ovmf \
  --efidisk0 "$STORAGE":0,efitype=4m,pre-enrolled-keys=0 \
  --cpu host \
  --cores 2 \
  --memory 4096 \
  --scsihw virtio-scsi-pci \
  --net0 virtio,bridge="$BRIDGE"

qm disk import "$VMID" "$INSTALL_DIR/haos.qcow2" "$STORAGE"
IMPORTED_DISK="$(qm config "$VMID" | sed -n 's/^unused0: //p')"
test -n "$IMPORTED_DISK"
qm set "$VMID" --scsi0 "${IMPORTED_DISK},discard=on,ssd=1"
qm set "$VMID" --boot order=scsi0 --onboot 1 --agent enabled=1
qm resize "$VMID" scsi0 +32G
qm start "$VMID"

Open the VM console. When HAOS boots, use its displayed URL or router lease and complete onboarding. Reserve the address in DHCP. homeassistant.local uses mDNS and may fail across VLANs; the IP address is less magical and more dependable.

Zigbee, Z-Wave, and USB passthrough

On the Proxmox host, run ls -l /dev/serial/by-id/ before and after connecting the coordinator. In VM > Hardware > Add > USB Device, select it by vendor/device ID. Avoid passing through an entire controller. A short extension cable moves a Zigbee radio away from noisy USB ports.

USB passthrough ties the VM to one node and complicates cluster migration. A network coordinator avoids that coupling.

Storage and backups

Use two layers. In Settings > System > Storage, add the NAS NFS or CIFS share as Backup, then schedule encrypted automatic backups. Keep the emergency kit outside Home Assistant and the NAS account. The backup documentation recommends another system and, ideally, an off-site copy.

Also schedule a Proxmox vzdump of the VM to the NAS or Proxmox Backup Server. Same-SSD snapshots are rollback, not backup. Quarterly, restore HAOS into a disposable VM on an isolated bridge, leave the radio detached, and confirm the dashboard loads. An untested backup is optimism with a timestamp.

Networking and remote access

Keep Home Assistant on the LAN through vmbr0. If IoT devices occupy another VLAN, allow required traffic and remember that discovery protocols do not cross routed networks automatically. Segmentation can wait until the automations work.

For household remote access, prefer Tailscale: no inbound port-forward, and access stays inside the Tailnet. Its Home Assistant guide covers the HAOS app, MagicDNS, HTTPS, and Tailscale Serve. Add an ACL tag if you manage Tailnet policy.

Cloudflare Tunnel avoids inbound ports but adds DNS, a connector, and Access policies. Use it when clients cannot run a VPN. Raw port-forwarding is last: it needs Caddy or Traefik, ACME TLS, and scoped trusted proxies. Home Assistant blocks proxy requests unless trust is configured.

Operations

Watchtower and Renovate do not manage HAOS. Use its update screen, back up first, and read breaking-change notes. Patch Proxmox during a planned reboot window. Check both systems’ logs afterward.

Run uptime checks from another VM or the NAS; Home Assistant cannot report its own outage. Watch both disks. TechSentinel covers broader self-hosting security issues, while project release notes should drive updates.

Quick troubleshooting

• UEFI shell or no boot disk: confirm BIOS is OVMF, Secure Boot pre-enrolled keys are off, scsi0 is attached, and it is first in boot order.
• No web UI: read the VM console address, verify the vmbr0 bridge and DHCP lease, then check any VLAN tag.
• Radio disappears after reboot: reselect the stable vendor/device mapping in Proxmox and avoid moving the dongle between ports.
• Reverse proxy returns an error: enable forwarded-header trust only for the proxy’s IP or network, never the entire LAN without a reason.