A dead SD card costs more than it used to

Your Home Assistant box already runs the lights, the locks and the energy dashboard. Losing it used to mean an evening of re-pairing devices. Pi Agent adds a layer that is much harder to recreate: every conversation you have had, every provider key you configured, every Skill you installed or wrote, and the rclone authorization that uploads to Google Drive. Together that can be weeks of work.

Four things go wrong often enough to plan for:

• Storage failure. An SD card or drive can become unreadable without warning.
• A failed upgrade. A Home Assistant release or an add-on update can stop the service from starting, and rolling back without a recent backup is difficult.
• Accidental deletion. One mistyped command in File editor or over SSH removes configuration you needed.
• Host migration. Moving from a Pi 4 to a Pi 5, from a Pi to a NUC, or to another building is a supported operation only because backups exist.

Home Assistant Backup packages the selected system configuration, databases, shared data and each selected add-on's /data/ directory into a .tar archive. Pi Agent runs as an add-on precisely so that its data travels inside that same archive. There is no second backup system to set up and no extra scheduled job to write.

Results go in the archive; the toolchain does not

You never have to open this folder over SSH, but seeing the layout makes the boundary obvious.

The four exclusions are deliberate, and the reason is size. venv/ and playwright-cache/ together use about 720 MB. Including them would add nearly 1 GB to every archive, so keeping ten backups would spend roughly 10 GB on files that download again by themselves. Clips and segments are regenerated from the script and narration you did keep.

One consequence surprises people. The empty marker file .video-tools-installed is in the archive — but restoring it alone does not skip the download, because the startup check looks for the Python executable too.

flowchart TD
  A["Add-on starts after a restore"] --> B{"Is .video-tools-installed there?"}
  B -->|"yes, it came from the archive"| C{"Is venv/bin/python3 there?"}
  B -->|"no"| D["Download again, 3-8 minutes"]
  C -->|"no, venv was excluded"| D
  C -->|"yes"| E["Skip it, ready straight away"]
  D --> F["Log reads video-tools-init done"]

Five steps, about five minutes

1. Step 1

   Open the backup page

   Go to Settings → System → Backups. It may be empty the first time, or it may already show something an existing schedule made. On releases from before 2023 this lived under Settings → System → Server Controls; that route no longer exists.

2. Step 2

   Select Backup now, then Manual backup

   On the data-selection screen, keep everything selected for your first one: configuration, every add-on, shared folders and media. That is what puts Woow HA Pi Agent and its /data/pi-agent/ into the archive. You may drop large media later to shrink it — but leave Pi Agent selected.

3. Step 3

   Give it a name you will recognize

   Replace the generic version-and-timestamp name with something meaningful: 2026-08-14-full, before-pi-agent-upgrade, provider-keys-configured. In six months this is the only thing telling you which archive to pick.

4. Step 4

   Download the Backup Emergency Kit

   Home Assistant 2025 releases generate an encryption key automatically and offer you the Backup Emergency Kit, a .txt file holding that key. Put it in a password manager, or print it. Keep it away from both the host and the archive — not in the same cloud folder as the file it unlocks.

5. Step 5

   Choose destinations, then take a copy off the device

   Local storage, Nabu Casa, mounted network storage, or an add-on destination such as Google Drive Backup or Samba Backup. A home backup usually takes 1-10 minutes. When it appears in the list, use its menu to download the .tar and keep that copy elsewhere.

An untested backup is only a guess

Test it on a machine that is not your production host: another Pi, an idle NUC, a Home Assistant OS virtual machine, or a small VPS running Home Assistant Supervised. A restore overwrites current data, so a failed test on the live box could leave you with neither copy.

Install Home Assistant there, open Settings → System → Backups, upload the .tar from the upper-right menu, open its card and select Restore backup. Enter the key from the Emergency Kit when asked; without that secret the restore cannot proceed. Let it restart, then give video-tools-init its 3-8 minutes.

Now open pi-web and check four things. Anything less is not a test:

• Session list — every previous conversation is there.
• Models panel — every provider is present, and Test succeeds on each.
• Skills panel — every installed Skill appears.
• A new conversation — the selected provider answers a simple question.

If the video pipeline is still unresponsive after ten minutes, or the log shows an error rather than video-tools-init done, force a clean rebuild: turn on reset_video_tools on the add-on's Configuration tab, the page that also holds log_level and timezone, then save and restart the add-on. The switch is not new; 0.13.0 only added the automatic clean-up afterwards, when the add-on sets the option back to false itself. Older releases leave it on, so turn it off yourself.

Configuration tabFour provider keys entered, three left blank — and every one of them is add-on state a backup has to carry.

• Configuration is one of four tabs across the top — Info, Documentation, Configuration, Log. Whatever the add-on lets you set sits behind it.
• The Options panel is a plain list of fields, cut off below groq_api_key on this screen. Nothing here is recreated for you.
• The eye icon beside each filled row shows the key in clear text. What the screen can reveal in one click, an unencrypted archive reveals to anyone holding it.

The archive holds credentials in plain text

Pi Agent stores provider keys as plain text in models.json, and rclone stores its Google Drive refresh token in rclone.conf. Both are included when the add-on is backed up. That is convenient on restore day and dangerous every other day.

So keep a second copy of every key in a password manager — 1Password, Bitwarden, iCloud Keychain — for two reasons:

Label each entry when you create the key: what it is for, the date, the provider site. Update it whenever you replace the key in the Models panel. Encrypt every archive that leaves the device, and never attach a backup to a support thread.

The two times a backup stops being optional

Before every add-on update

The Pi Agent add-on page has no Downgrade button, and the add-on store normally offers only the current release. If an update changes behavior or refuses to start, a pre-upgrade backup is the practical route back.

Note this before you updateThe version you are on now is the number you will wish you had written down.

• Current version — 0.12.0 here. Write it into the backup name, so the archive says what it can restore.
• Autoupdate should stay off. An update that arrives on its own arrives without a fresh backup behind it.
• There is no Downgrade button on this page. That absence is the whole argument for the backup.

The whole routine is one line: Settings → System → Backups → Backup now → Manual backup, name it “Before upgrade <date>”, wait for it to finish, then go back to the add-on page and select Update.

Moving to a new host

Same mechanism, higher stakes, because the new machine becomes production. Take a final clean backup on the old host, then stop using it — conversations you start after that point are not in the archive. Install Home Assistant on the new hardware but install no add-ons; the restore brings Pi Agent and its data back together. Enter the key, then allow the 3-8 minutes for the video tools. Chats and Session history work while that runs.

Where to go from here