★ Quick Start

Protected in 30 minutes.

If you do nothing else from this guide today, do this. It will not cover every scenario, but it will get you out of the worst one: total loss with no recoverable backup.

The three things that need backing up

Most people think “Home Assistant backup” is one thing. It is three things, and missing any of them turns a recovery into a rebuild.

1. HA configuration — your automations, scenes, scripts, dashboards, integrations list. This is what the built-in Backup integration captures.
2. Add-on data — Z-Wave JS pairings, ZHA database, Mosquitto retained messages, Node-RED flows. Some of this is included in HA backups by default; some is not.
3. The credentials and tokens that don’t survive a backup — Cloudflare tunnel tokens, OAuth integrations, anything you typed into a UI form that wasn’t in secrets.yaml. These are documented in Appendix B.

Minimum viable backup: 30 minutes, two locations

If you have nothing today, this is the smallest setup that will save you from disaster:

1. Enable HA’s built-in Backup integration if it isn’t already on. Set it to run nightly. (Chapter 03.)
2. Add one off-host destination. Any of these works: a Samba share on your NAS, a Google Drive folder via the community Google Drive Backup add-on, or rclone to Backblaze B2. (Chapter 04.) Same-disk backups are not backups.
3. Take one full backup right now, copy it to a USB drive, and put the USB drive somewhere your house fire can’t reach. This is your nuclear-option recovery.
4. Download the backup emergency kit from Settings → System → Backups → the three-dot menu. It contains the encryption key needed to restore. Store it in your password manager and one offline location — both outside Home Assistant.

The restore test you should do today

Spin up a Home Assistant VM, virtual machine, or even a spare Raspberry Pi. Restore your most recent backup to it. Notice what works, what doesn’t, and what asks you to log in again. The answers are the contents of Appendix B — the integration re-auth tracker.

This is the chapter most guides skip. It is the only chapter that matters when something is actually broken.

How this guide is organized

• Chapters 01–02 — what backups actually contain, and the three-layer model that makes recovery reliable.
• Chapters 03–05 — the actual setup: HA-native backups, off-host destinations, full disk imaging.
• Chapter 06 — the restore drill. The chapter most people skip.
• Chapters 07–08 — full hardware migration, including SD card to SSD for Pi users.
• Chapters 09–10 — HA update strategy and disaster recovery drills.
• Appendix B — the integration re-auth tracker, 25+ integrations and what each needs after restore. This appendix alone is the reason to keep this guide on hand.

§ 1.1 · The contents of the backup file

What’s in the .tar.

An HA backup is a single .tar archive containing a structured snapshot of your installation. The default full backup includes:

• Your HA configuration directory: configuration.yaml, automations.yaml, scripts.yaml, scenes.yaml, your dashboards, custom blueprints, and the contents of /config/.storage/.
• Your installed add-ons (the apps themselves, not necessarily their data — see below).
• Add-on data, if you ticked the per-add-on data box when configuring the backup. This is opt-in, not default for every add-on.
• Your installed HACS components are reinstalled on restore from the HACS configuration that does survive.
• Your secrets file (secrets.yaml) and any other files in /config/.

What is “full” vs “partial”

HA gives you two backup types. The naming is misleading.

• Full backup includes the configuration directory plus add-ons. You choose which add-ons (and which add-on data) to include.
• Partial backup lets you pick a smaller subset — e.g., just the configuration without the add-ons.

Neither version is “everything that exists in your HA instance.” The next page documents what neither of them captures.

§ 1.2 · What backups don’t restore

What you’ll need to redo.

This list is the most-printed page of this guide for a reason. None of these are bugs. They’re design choices that make sense individually and collectively turn a restore into a chase.

Tokens, OAuth, and credentials

Anything you authorized through a browser-based OAuth flow generally survives the backup as a configuration entry, but the actual token is rotated by the provider and may need to be re-authorized after restore. The list of integrations in Appendix B documents which providers do this.

Anything you typed into a UI form that wasn’t backed by secrets.yaml is stored in /config/.storage/core.config_entries. This file is in the backup — but the credentials inside it may be encrypted with a key that’s tied to your installation, not your user. Restore on a fresh install, and some of those entries decode to empty.

Hardware-bound state

This is where most migrations break.

• Zigbee coordinator pairing data. ZHA stores its device database (zigbee.db) in the config directory and survives. Z-Wave JS stores a .json network store. But both depend on the USB device path being the same on the new host. If your dongle was /dev/ttyUSB0 on the old host and is /dev/ttyACM0 on the new one, you’ll edit your config before HA recognizes it.
• The Zigbee2MQTT devices.yaml file is in the Z2M add-on’s data. If you didn’t opt into add-on data backup, you’ll re-pair every device.
• HomeKit Bridge entries don’t survive reliably. Plan to delete the bridge from each iOS device’s Home app and re-add after restore.

Tunnels, certificates, and external services

• Cloudflare Tunnel tokens are stored in the add-on configuration. The add-on’s data is included only if you ticked it; the token text itself is recoverable from your Cloudflare dashboard if you didn’t.
• Let’s Encrypt certificates need to regenerate. Cloudflare-issued certs in your origin server config are similar.
• Nabu Casa (HA Cloud) generally re-authorizes itself when you log back in.