Off the TrueNAS app, onto HAOS: the migration

TrueNAS deprecated its Home Assistant community app in August 2026 and removed it from the catalog on November 26 — leaving more than 12,000 installs on an unsupported path. The good news: this migration is one of the safest in the ecosystem, because Home Assistant's own backup carries everything. Here is the move to Home Assistant OS in a VM, step by step, with the decision made honestly first.

Published Nov 18, 2026

Decide the target first

With the community app gone, TrueNAS users have three sane targets. HAOS in a VM on the TrueNAS box (this guide's path) keeps everything on the hardware you own and gets you the fully supported install — add-ons, one-click updates, the Marketplace. HAOS on a small dedicated machine or mini-PC is the same software with a physical separation bonus. Home Assistant Container in Docker remains supported but leaves add-ons and some conveniences manual — fine for Docker natives, a downgrade for app users. Core and Supervised installs are deprecated and unsupported; do not migrate to a dead end. For most app refugees, HAOS-in-a-VM is the answer: same box, supported forever, and the restore process below does the heavy lifting.

Take a full backup→Build the HAOS VM→Restore on first boot→Move USB devices→Verify + retire the app

Step 1 — the backup that makes this safe

  1. In your current Home Assistant: Settings → System → Backups → create a full backup. Not partial — full, including add-ons and their data.
  2. Download that backup file off the NAS entirely (laptop, cloud, anywhere that is not the box you are about to reconfigure).
  3. Note your current version. The restore target should run the same or a newer Home Assistant version; HAOS images ship current, which satisfies this for almost everyone.

Do not skip the download. The backup sitting inside the TrueNAS app's storage is not a backup of the app — it is a file inside the thing you are replacing. Off-box copy first, always.

Step 2 — build the HAOS VM

  1. Download the Home Assistant OS image for virtual machines (the .qcow2 / VM image from the official installation page) and place it where TrueNAS keeps VM disks.
  2. Create a VM: 2 vCPUs and 4 GB RAM is the comfortable floor (2 GB works, 4 breathes), the HAOS disk at 64 GB or more, UEFI boot, and a network bridge so the VM lands on your LAN with its own IP.
  3. Boot it and wait for the welcome screen — HAOS announces itself at homeassistant.local:8123 once it is up, which can take a few minutes on first boot.

Step 3 — restore, then move the radios

  1. On the HAOS onboarding screen, choose the restore option ('Upload backup' / restore from backup) and give it the file from step 1. Walk away — a full restore of a mature system can take a while, and interrupting it is the one way to make this migration exciting.
  2. When it comes up, sign in with your usual account: dashboards, automations, history and integrations should simply be there. Check Settings for any repairs the system flags.
  3. USB devices: shut the VM down, pass through your Zigbee/Z-Wave coordinators in the TrueNAS VM settings (pass the device, or the whole USB controller if the VM fights you), boot, and confirm the integrations reconnect. IP-based devices (Matter border routers, ESPHome, cameras) need nothing — they find the new instance by network.
  4. Update the IP in your phone app and any bookmarks if the VM's address differs from the old app's, then run the house for a day before retiring anything.

Step 4 — retire the app, keep the parachute

Once the VM instance has run cleanly for a day or two, stop the TrueNAS app (do not delete it yet) and keep both it and your downloaded backup for a week. If anything subtle surfaces — a forgotten integration, a history graph you miss — the old instance is one start-click away. After the week, delete the app and archive the backup file with your other important documents. You now own the boring, supported setup: HAOS updates itself in one click, add-ons work, and the next deprecation headline will be about somebody else.

Official documentation and references

Frequently asked questions

Will I lose my history and dashboards in the move?

No — a full backup carries configuration, dashboards, automations, add-on data and history databases. Restoring it onto HAOS reproduces your system; that is exactly what the backup format is designed for.

Can I run HAOS in a VM and keep my Zigbee coordinator working?

Yes — pass the USB coordinator through to the VM in TrueNAS's VM device settings. If a specific stick is stubborn, passing the entire USB controller usually resolves it.

Is the Docker (Container) install a valid alternative?

It is supported, but it is a step down from the app experience: no add-on store, more manual plumbing. If you are migrating anyway, HAOS is the target that ends migrations. Our radios and Docker guides assume HAOS or Container accordingly.

Related guides