Smart Home

Home Assistant on a NAS: Docker vs VM

Decide how to run Home Assistant on a NAS — the plain Docker container has no add-ons and awkward radio passthrough; HAOS in a VM gets Supervisor, add-ons, and clean USB passthrough.

Problem summary

On a NAS you choose between HA Container (plain Docker) and HAOS in a VM, and the decisive fact is what you lose with the container: no Supervisor, so no add-ons, and you own host + updates. Add-ons and clean USB-radio passthrough really want HAOS in a VM (Synology VMM / TrueNAS / Proxmox). Only HAOS and HA Container are supported install methods now — Core and Supervised were deprecated in 2025, so 'run Supervised on the NAS' is a trap.

Operator snapshotEvidence first

First proof

Decide whether you need add-ons (Zigbee2MQTT, Mosquitto, ESPHome dashboards).

Screen to open

Settings > About / Settings > System > (Supervisor present?)

Expected signal

You know if Supervisor/add-ons are required for your setup.

Stop boundary

Running Supervised on the NAS host (deprecated) or passing a radio by /dev/ttyACM0 (it moves and breaks).

Layer path

1On a NAS you choose between HA Container (plain Docker) and Home Assistant OS in a VM, and the decisive difference is the Supervisor: the container has none.

2No Supervisor means no add-ons and you own host + updates — Home Assistant's FAQ states the Container install doesn't support add-ons and makes you responsible for the OS and updates.

3Add-ons and clean USB-radio passthrough want HAOS in a VM (Synology VMM, TrueNAS, Proxmox); the container can still work if you run supporting services (MQTT, Z2M) as your own containers.

4Only HAOS and HA Container are supported install methods now — Core and Supervised were deprecated in 2025 — so running Supervised on the NAS host is a legacy trap, not a recommendation.

Runbook

Step-by-step runbook

Start here. Do each check in order, compare it to the expected result, and stop when the evidence explains the failure or the safe stop point applies.

Decide add-ons vs self-hosted services

Check: Determine whether you need Supervisor add-ons.

Expected result: You know whether to run HAOS-in-VM or HA Container.

If not: If add-ons are needed, the bare container is out.

Pick the install method on your NAS

Check: HAOS in a VM (Synology VMM / TrueNAS / Proxmox) or HA Container.

Expected result: You have a supported, appropriate install type.

If not: Do not run Supervised on the NAS host.

Pass the radio through correctly

Check: Pass the USB device into the VM/container and reference it by by-id.

Expected result: Home Assistant sees the Zigbee/Thread/Z-Wave adapter reliably.

If not: Use PCI/controller passthrough for radios that need it.

Verify add-ons and radio work

Check: Install a test add-on (if HAOS) and confirm the radio enumerates.

Expected result: Add-ons run and the radio is detected at its stable path.

If not: If add-ons are missing, you're on Container, not HAOS.

Plan backups before you depend on it

Check: Set up full backups (and the restore test) now.

Expected result: You can migrate or recover later without re-pairing.

If not: See /smart-home/migrate-home-assistant-new-server.

Decision tree

If: You need add-ons or one-click integrations.

Then: Supervisor required — the plain container won't do it.

Action: Run HAOS in a VM (Synology VMM / TrueNAS / Proxmox).

If: You have a USB Zigbee/Thread/Z-Wave radio.

Then: Clean passthrough strongly favors a VM.

Action: Run HAOS in a VM and pass the radio through by its by-id path.

If: You're comfortable with Docker and need no add-ons.

Then: HA Container is fine.

Action: Run HA Container and host MQTT/Z2M as your own containers.

If: You were about to run Supervised on the NAS.

Then: Deprecated and fragile (goes Unsupported with other containers).

Action: Use HAOS-in-VM or HA Container instead.

Evidence

Evidence table

Symptom	Evidence to collect	Likely layer	Next action
No 'Add-ons' menu in Home Assistant.	Install type — Container has no Supervisor.	Install method (Container vs HAOS)	Move to HAOS in a VM for add-ons.
Zigbee dongle not detected.	How the USB device is passed and which path is used.	USB passthrough / device path	Pass it explicitly; reference /dev/serial/by-id/...
System shows Unsupported/Unhealthy.	Whether Supervised is in use with extra containers.	Deprecated Supervised install	Migrate to HAOS-in-VM or HA Container.
ConBee II keeps re-connecting under the VM.	Passthrough type (simple USB vs PCI controller).	Radio-specific passthrough quirk	Use PCI/controller passthrough or a start script.

Reference

Commands and settings paths

Confirm the install type

Settings > About / Settings > System > (Supervisor present?)

Where: In the Home Assistant UI.

Expected: HAOS shows Supervisor/Add-ons; Container does not.

Failure means: No Add-ons menu confirms a Container install.

Safe next step: Switch to HAOS-in-VM if you need add-ons.

Find the radio's stable path

ls -l /dev/serial/by-id/

Where: On the NAS/VM host shell.

Expected: The Zigbee/Thread/Z-Wave adapter is listed with a stable by-id name.

Failure means: If absent, the device isn't passed through to the host/VM.

Safe next step: Fix passthrough, then use the by-id path in HA.

Check supported-ness (HAOS/Supervised)

Settings > System > Repairs / Supervisor logs

Where: In the HA UI (Supervisor-based installs).

Expected: System reports healthy and supported.

Failure means: Unsupported/Unhealthy flags a deprecated or modified setup.

Safe next step: Move to a supported method (HAOS-in-VM or Container).

Hardware boundary

Hardware and platform boundary

Change only when

Run HAOS in a VM on the NAS when you need add-ons or a USB radio; choose HA Container only if you're comfortable owning Docker and self-hosting supporting services.

Evidence that matters

A hypervisor with clean USB passthrough (Synology VMM / TrueNAS / Proxmox), a radio referenced by its by-id path, and a supported install method (HAOS or Container).

Evidence that does not matter

CPU benchmark bragging — Home Assistant is light; reliability comes from the install type, passthrough, and backups, not raw horsepower.

Avoid

Running Supervised on the NAS host (deprecated) or passing a radio by /dev/ttyACM0 (it moves and breaks).

Related tool

Use the linked tool to turn this runbook into a guided check for your exact setup.

NAS setup planner

Last reviewed

2026-06-03 · Reviewed by HomeTechOps. Built from 2026-06 research verified against home-assistant.io (HA vs HAOS FAQ, deprecation of Core/Supervised, Connect ZBT-2); the operator differentiator is the Container-has-no-add-ons fact and the HAOS-in-VM-for-radio-passthrough decision, with the Supervised-is-deprecated trap called out. Bridges the existing /nas cluster.

Sources/assumptions

Assumes running Home Assistant on a NAS/hypervisor (Synology Container Manager/VMM, TrueNAS, or Proxmox) with an optional USB Zigbee/Thread or Z-Wave radio.
Only HAOS and HA Container are supported install methods (Core and Supervised deprecated 2025) — Supervised-on-the-NAS is explicitly not recommended.
USB-radio passthrough behavior is host/hypervisor-specific and version-dependent; reference the radio by its /dev/serial/by-id path, not /dev/ttyACM0.

Source-backed checks

HomeTechOps turns official docs and conservative safety rules into a shorter runbook. These links are the source trail for the page direction.

Home Assistant: Home Assistant vs Home Assistant OS (FAQ)Used for the Container-has-no-add-ons fact (add-ons need Supervisor/HAOS) and the install-type tradeoff that decides Docker-container vs HAOS-VM on a NAS.Home Assistant: Deprecating Core and Supervised installation methodsUsed to state that only HAOS and HA Container are supported now (Core/Supervised deprecated 2025-05-22) — so 'run Supervised on the NAS' is a legacy trap, not a recommendation.Home Assistant: Introducing Connect ZBT-2Used for the radio naming truth — SkyConnect was renamed Connect ZBT-1, which ended production Nov 2025; the current Zigbee/Thread adapter is Connect ZBT-2 (Zigbee OR Thread, not both at once).

Diagnostic rule

1. Check the simplest signal first.
2. Change one thing at a time.
3. Confirm the layer (radio, IP, app) before deep config.
4. Stop when the evidence says the risk moved.

FAQ

Why can't I install add-ons on my Home Assistant container?

Because add-ons are a Supervisor feature, and the plain HA Container has no Supervisor — Home Assistant's own FAQ says the Container install doesn't support add-ons and makes you responsible for updates and the host OS. If you want add-ons (and one-click Zigbee2MQTT, Mosquitto, etc.), run Home Assistant OS in a VM instead of the bare container. See HA vs HAOS.

Docker container or HAOS VM on my NAS — which should I pick?

Pick HA Container if you're comfortable managing Docker, don't need add-ons, and run supporting services (MQTT, etc.) as your own containers. Pick HAOS in a VM if you want Supervisor, add-ons, and clean USB-radio passthrough — the common choice on Synology (VMM), TrueNAS, and Proxmox. Don't run Supervised on the NAS host: it's deprecated and installing other containers alongside it flips the system to Unsupported.

My Zigbee dongle isn't detected in the container — why?

USB passthrough into a container or VM is where this breaks. Pass the device through explicitly and reference it by its stable path (`/dev/serial/by-id/...`), not `/dev/ttyACM0`, which can move. Some radios (e.g. ConBee II) misbehave under simple USB passthrough and need PCI passthrough of the USB controller or a start script. For add-ons plus reliable passthrough, HAOS in a VM is the smoother path.