Someone asks this every week in r/HomeAssistant: I'm running Home Assistant in a Docker container, should I move to HAOS? Usually right after something broke and a reply told them HAOS would have prevented it. Here's the honest version, from someone who ran HA Container on Debian for years before touching HAOS: the migration is very doable, it costs more than people tell you, and if you're already comfortable with compose, you may not need to do it at all.

What a backup actually restores — and what it doesn't

The good news first. A full Home Assistant backup restores almost everything you care about: automations, scripts, scenes, integrations, dashboards, helpers, users — the entire /config tree. Drop it into a fresh instance and your smart home comes back.

What it does not carry is add-ons. This is the part that bites people. HA Container has no Supervisor, which means there is no such thing as an add-on in that world. Everything that was a one-click add-on under HAOS — Zigbee2MQTT, Mosquitto, ESPHome, AdGuard — becomes your problem to run as its own container, with its own compose service and its own volume.

That isn't hard. It's just no longer one click. Moving to HAOS, you're trading compose files for the add-on store; moving the other way, you trade the store for compose files. Neither is wrong — they're different chores.

HACS survives

HACS reinstalls itself and re-pulls all your custom repositories on its own, once you drop the custom_components directory back into /config. You don't rebuild it from scratch.

The two gotchas that eat a weekend

If you remember only two things from this, make it these.

1. Map the Zigbee stick by its by-id path, never /dev/ttyUSB0

USB passthrough for a Zigbee or Z-Wave coordinator has to be mapped explicitly in your compose file. The trap is pointing at /dev/ttyUSB0, which is not stable — it can become ttyUSB1 on the next reboot, and suddenly your whole Zigbee network is "gone." Use the persistent /dev/serial/by-id/ path instead:

services:
  homeassistant:
    network_mode: host
    devices:
      - /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus-if00:/dev/ttyACM0
Don't use ttyUSB0

A path like /dev/ttyUSB0 is assigned in enumeration order at boot. Add another USB device, or just reboot, and your coordinator can move. The by-id path is tied to the hardware and never changes.

2. Use network_mode: host if you care about discovery

Anything relying on mDNS or broadcast discovery — Chromecast/Google Cast, HomeKit, a lot of integrations' auto-discovery — needs the container on the host network. Bridge mode technically works, but you'll spend a Saturday wondering why half your integrations can't find devices that are sitting right there. Set network_mode: host and move on.

One consequence worth knowing: with host networking on, if Mosquitto runs on the same machine, point Zigbee2MQTT and Home Assistant at the host's LAN IP, not localhost. Under host mode the usual container-name DNS doesn't apply.

The migration order that won't strand you

Whichever direction you're going, do it in an order that keeps a working instance alive the entire time:

  1. Stand up the new instance fresh and get it on the network. Don't touch the old one yet.
  2. Restore your backup into it. Let it settle for a day — watch for integrations that need re-auth.
  3. Only then move the Zigbee stick over and update the coordinator path in Z2M.

The point of that sequence: until step 3, your old instance is still running and still controlling your house. If the new one explodes, you've lost nothing — unplug the stick from the new box and put it back. Migrate the radio last, because it's the one piece you can't run in two places at once.

So should you actually switch?

Here's the contrarian part. If you're already running HA Container on a Debian box that's also your Docker host for everything else, the honest answer is often no. Putting HA on a separate Pi just so it can be HAOS adds a network hop, a second machine to maintain, and an SD card that will eventually corrupt. The "HAOS gives you add-ons" pitch matters a lot less when you already write compose files for a living — to you, an add-on is just another service.

Switch to HAOS if you want the managed, appliance-like experience and would rather not think about the host OS. Stay on Container if you already run a Docker host and like keeping everything in one place under your own compose files. Both are legitimate. Just go in with your eyes open about what the backup does and doesn't carry.

The migration itself is an afternoon. The recovery plan for when it goes sideways is the part worth getting right — which is mostly "keep the old instance running until the new one proves itself."