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, Google Drive via HA’s official Google Drive integration, 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.

Where commands actually run.

Every command block in this guide carries a Run on: tag; this is the map those tags point into. The single most common way a backup workflow fails is running the right command in the wrong container.

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/.
• Selected installed apps (add-ons) and their application data, per your backup selection.
• The addons folder: locally created or manually installed apps only. Store-installed app packages aren’t archived as packages; they’re reinstalled during restore.
• HACS configuration, repository data, and installed custom components: all under /config, all included in a regular backup.
• 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.

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

Integrations configured through the UI live as configuration entries under /config/.storage, which is part of Home Assistant settings and restores with the backup, stored tokens included. What a provider does after restore is its own business: most accept the restored token and carry on; some expire or revoke it and trigger a reauthentication flow in HA. Appendix B documents what to expect, integration by integration.

Treat reauthorization as integration-specific, not a universal consequence of new hardware. The failure mode to plan for is a provider-side rejection (expired token, revoked app, changed redirect URL), which HA surfaces as a visible repair or reauth prompt: annoying, obvious, fixable.

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.

What this backup doesn’t even try to protect.

An HA backup protects data stored inside the HA installation, plus the apps and folders you selected. It does not automatically protect anything that merely talks to HA. If part of your stack runs on another box, it has its own blast radius and needs its own plan.

Common externals that need their own backup

• Zigbee2MQTT or Mosquitto running on a separate host (not as HA apps).
• An external MariaDB or PostgreSQL recorder database.
• Frigate’s configuration and media on its own server.
• Standalone Node-RED flows.
• A cloudflared service on a router or another server.
• NAS media that HA only mounts.
• ESPHome source files kept outside /config.

The test

For every dependency, record: where it runs · where its config lives · where its data lives · which backup protects it · how it’s restored · when that restore was last tested. If the answer to “which backup contains this?” is unclear, treat the service as unprotected, because it is. Appendix B flags the rows where an external deployment falls outside this guide’s backup entirely.