Back up conversations and keys with Home Assistant

Why you should make regular backups

Your Home Assistant host may run lighting automations, door locks, energy monitoring, and now Pi Agent. That means a host failure can cost you much more than it once did: you could lose every AI conversation, each provider key you configured, every installed Skill, and the rclone authorization used to upload files to Google Drive. Together, that can represent weeks of work.

• Storage failure: an SD card or drive can become unreadable without warning.
• Failed upgrade: a Home Assistant release or Pi Agent add-on update can prevent the service from starting. Without a recent backup, rollback is difficult (see Chapter 21).
• Accidental deletion: a mistyped command in File editor or SSH can remove important configuration.
• Host migration: backups are the supported way to move from a Pi 4 to a Pi 5, from a Pi to a NUC, or to another location.

Home Assistant Backup packages the selected system configuration, databases, shared data, and each selected add-on's /data/ directory into a .tar archive. You can download it, copy it off-device, upload it to cloud storage, or restore it on another Home Assistant installation.

Pi Agent runs as a Home Assistant add-on so that its persistent data can travel with the same backup. You do not need a separate backup system or another scheduled job. You do, however, need to include the Pi Agent add-on and verify that the backup can be restored.

Pi Agent's /data/pi-agent/ directory map

You do not need to inspect this directory over SSH, but understanding its layout makes the backup boundary clear. The final column shows whether Home Assistant includes each item in a Pi Agent backup:

A useful rule is: back up your results, not the rebuildable toolchain. Conversations, keys, Skills, rclone authorization, and finished MP4 files are your results. The virtual environment, Chromium download, and intermediate video files can be downloaded or generated again.

Why four directories are deliberately excluded

The backup excludes venv/, playwright-cache/, clips/, and segments/ for three reasons:

1. They make every backup much larger

   venv/ and playwright-cache/ together use about 720 MB. These are the dependencies downloaded during the initial installation described in Chapter 2 and Chapter 18. Including them would add nearly 1 GB to every backup; retaining ten backups could consume roughly 10 GB of space for data that can be downloaded again.

2. Video clips and segments can be regenerated

   projects/<a-video>/clips/ contains scenes captured by Playwright, while segments/ contains intermediate files produced by ffmpeg. As long as the script, narration, and finished files under projects/<a-video>/, including final.mp4, are preserved, the workflow can generate those intermediate files again.

3. video-tools-init rebuilds the tools automatically

   At startup, pi-web-start.sh launches video-tools-init.sh in the background (see Chapter 18). Its check requires both the sentinel file and venv/bin/python3. Because a backup excludes venv/ and playwright-cache/, the missing executable triggers a fresh download even if the sentinel file was restored. Allow 3-8 minutes after the first start.

The policy is simple: back up data that cannot be reconstructed elsewhere. Sessions, keys, Skills, rclone tokens, and finished videos belong in the archive; dependencies and intermediate media can be downloaded or generated again.

Make a full backup

The first backup takes only a few steps. Once you know the process, make it a regular monthly routine—or automate it more frequently.

1. Open the Home Assistant backup page

   In the Home Assistant sidebar, select Settings → System → Backups. The page may be empty the first time you open it, or it may show a backup created by an existing schedule. On releases from before 2023, the feature appeared under Settings → System → Server Controls; that route no longer exists in current releases.

2. Select “Backup now,” then “Manual backup”

   In the Home Assistant 2024 and later interface, select Backup now → Manual backup. Older tutorials may refer to “Create backup” or “Full backup.” On the data-selection screen, keep everything selected for your first backup: Home Assistant configuration, each installed add-on, shared folders, and media. This includes the Pi Agent add-on and its /data/pi-agent/ directory. To reduce archive size, you may omit large media and share directories, but leave Pi Agent selected.

3. Give the backup a descriptive name

   Replace the generic version-and-timestamp name with something you will recognize later, such as 2026-08-14-full, before-pi-agent-upgrade, or provider-keys-configured. A clear name makes the right restore point easier to identify.

4. Protect the encryption key and Backup Emergency Kit

   Home Assistant 2025 releases automatically generate a backup encryption key and prompt you to download the Backup Emergency Kit, a .txt file containing that key. Store the kit in a password manager or print it and keep it securely. If both the original Home Assistant system and this key are lost, the encrypted backup cannot be restored; there is no official backdoor. Keep the kit separate from both the host and the backup archive—not beside the archive in the same cloud folder.

5. Choose storage destinations and wait for completion

   Choose one or more destinations: local storage, Nabu Casa, mounted network storage, or a destination supplied by a third-party add-on such as Google Drive Backup or Samba Backup. A home backup usually takes 1-10 minutes, depending on data volume and installed add-ons. When it appears in the list, use its menu to download the .tar archive and keep an off-device copy.

Important: a backup is not proven until you test a restore

Creating an archive is only the first step. The real test is whether that archive can restore a working system. An untested backup may fail when you need it most.

1. Prepare a Home Assistant system that is not your production host

   Use another Pi, an idle NUC, a Home Assistant OS virtual machine in VirtualBox, or a small VPS running Home Assistant Supervised. Do not run the test restore on your production host. A restore overwrites current data, so a failed test there could leave you without either copy.

2. Install Home Assistant, upload the backup, and restore it

   On the test system, open Settings → System → Backups, use the menu in the upper-right corner to upload the downloaded .tar file, open its backup card, and select Restore backup. For an encrypted backup, enter the key from the Backup Emergency Kit or the password you set. Without that secret, the restore cannot proceed. Allow Home Assistant to restart when prompted.

3. Wait for Pi Agent and video-tools

   Pi Agent should return to the sidebar after the restore. During the first 3-8 minutes, video-tools-init downloads the 720 MB Python environment and Chromium bundle described in Chapter 18. You can open pi-web during this period, but the video pipeline is not ready yet.

4. Open pi-web and verify every item

   Confirm the restored data and service directly:

   • Session list: all previous conversations are present
   • Models panel: every provider is present, and Test succeeds
   • Skills panel: every installed Skill appears in the list
   • New conversation: the selected provider answers a simple question
   Only then have you demonstrated that the backup can recover Pi Agent. If any check fails, use the troubleshooting section below.

Not recommended: manually rsync /data/pi-agent/ to another host

Although copying /data/pi-agent/ with rsync over SSH may appear equivalent to a backup, it introduces three practical risks:

• Data and add-on versions may not match. The formats of models.json and sessions/*.jsonl may change between Pi Agent releases. Copying older data into a newer add-on—or newer data into an older one—can prevent pi-web from reading it. A Home Assistant backup records add-on information with the data, making version alignment easier to preserve.
• You can omit add-on state. Add-ons also store data under /data/ as well as settings such as options.json, configuration values, environment variables, and log_level. Home Assistant backs up the selected add-on as a unit; a hand-built copy can easily miss part of it.
• You can create an inconsistent video-tools installation. A manual copy may carry /data/pi-agent/.video-tools-installed without a complete virtual environment. When video-tools-init.sh runs, its normal startup check also looks for venv/bin/python3, but a partial or mismatched toolchain can still fail when the video pipeline runs. If necessary, enable reset_video_tools in Configuration and restart the add-on (see Chapter 18).

Use Home Assistant Backup for complete Pi Agent recovery. It is the supported mechanism and is less likely to produce an incomplete or version-mismatched restore.

Store API keys separately

Pi Agent stores provider keys as plaintext in /data/pi-agent/models.json. When Pi Agent is selected, Home Assistant places that file inside the backup archive. Keep a second copy of every API key in a password manager such as 1Password, Bitwarden, or iCloud Keychain for two reasons:

• Independent recovery: if a backup is missing, corrupt, or too old, the password-manager copy can restore provider access.
• An unencrypted backup exposes the key. A .tar archive can contain plaintext data/pi-agent/models.json and rclone.conf. If an archive leaks, revoke and replace every exposed provider key and storage token. Your password manager tells you exactly which credentials to rotate.

When you create a key (as in Chapter 5), save it immediately with a clear label such as Pi Agent provider key / creation date / official provider site. Update the password-manager entry whenever you replace the key in the Models panel. Encrypt every archive stored off-device, and never share a backup archive as a troubleshooting attachment.

Create a backup before upgrading Pi Agent

Before every Pi Agent add-on update, make a fresh backup. Treat this as a requirement for major releases with breaking changes, such as v0.13.0, rather than as optional housekeeping.

The Pi Agent add-on page has no Downgrade button. Home Assistant's add-on store normally offers only the current release. If an update changes behavior or prevents startup, a pre-upgrade backup provides the practical route back to the earlier state.

Known high-risk transitions are summarized below. See the current notes in Chapter 21 before upgrading:

Recommended procedure: Settings → System → Backups → Backup now → Manual backup → select a full backup → name it “Before upgrade <date>” → wait for completion → return to the add-on page and select Update. About 5 minutes of preparation gives you a recovery point.

Move to a new Home Assistant host

Use the same backup mechanism when moving from a Pi to a NUC, upgrading from an older Pi to a Pi 5, or relocating the system. The process resembles a restore test, but this time the new host becomes production:

1. Create a final, clean backup on the old host

   Take extra care with this last backup. After it completes, do not start new conversations or change settings on the old host, because those changes will not be in the archive. Encrypt the backup, store an off-device copy on a USB drive, upload it to Nabu Casa, or use all three for the strongest protection.

2. Install Home Assistant on the new host, but no add-ons

   Install Home Assistant OS or Home Assistant Supervised on the new hardware and connect it to the network. Do not install Pi Agent manually. The restore installs the backed-up add-on and its data together.

3. Restore the old backup on the new host

   Open Settings → System → Backups, upload the backup, and select Restore. Enter the encryption key or password when prompted. Home Assistant restarts, and Pi Agent should then appear in the sidebar.

4. Allow 3-8 minutes for video-tools to download again

   The new host has no restored venv/ or playwright-cache/. During startup, s6-overlay triggers the background download. pi-web, chats, and Session history are available while it runs, but the video pipeline is not. Wait until the log shows video-tools-init done.

5. Test a conversation and confirm provider access

   Open a new Session, choose a configured provider, and ask a simple question. A response confirms the key and network path are working. A 401 or 403 response may mean the provider rejected the changed network IP, requires an IP allowlist update, or has revoked the credential. Those are provider-account issues rather than Pi Agent restore failures.

Common pitfalls

1. Is a backup larger than 1 GB normal?

   Yes. A full backup includes the selected /data/ directories for all add-ons, which may include InfluxDB, Node-RED, an MQTT broker, and File editor in addition to Pi Agent. If you need only Pi Agent, create a partial backup and select Home Assistant Core and the Pi Agent add-on. Depending on Session history and project output, that archive may be only tens or hundreds of megabytes. A partial backup restores only the components you selected; it does not protect other add-ons.

2. Pi Agent is empty after the restore

   The Pi Agent add-on was probably omitted when the backup was created. Open the completed backup card and inspect its included content. If Woow HA Pi Agent is absent from the Add-ons section, create another backup. Under Backup now → Manual backup, select Woow HA Pi Agent. Current Home Assistant versions package an add-on and its data as one selection, including /data/pi-agent/. If your interface has separate add-on and add-on-data checkboxes, it is very old; create a full backup before upgrading, as described in Chapter 21.

3. The key was restored, but the Models test fails

   First determine whether the credential remains valid. If it does, the API service may have changed its endpoint or path; update the provider's base URL in the Models panel using the current values in Chapter 11, then run Test again. If the credential has expired or been revoked—or you replaced it in the provider console—create a new key and save it in both Pi Agent and your password manager. A backup cannot reactivate a revoked credential.

4. The video pipeline does not respond

   For 3-8 minutes after a restore, video-tools-init may still be running. Check the Home Assistant add-on log for video-tools-init done. If it has not completed after more than ten minutes or the log shows an error, enable reset_video_tools on the add-on Configuration page, restart the add-on, and wait for another download (see Chapter 18).

5. The Skills panel is empty, but files exist under /data/pi-agent/skills/

   This rare condition means the files were restored but pi-web has not rescanned them. Start a new conversation rather than merely refreshing the page; opening a new Session forces a scan of the Skills directory. If the Skills still do not appear, restart the Pi Agent add-on from its Home Assistant add-on page.

6. rclone no longer uploads to Google Drive after the restore

   The OAuth token in rclone.conf can expire or be revoked, particularly when restoring an old backup. As described in Chapter 19, open a shell in the add-on container and run rclone config reconnect gdrive:, replacing gdrive: with your remote name and retaining the colon. This repeats the OAuth authorization flow without rebuilding the entire rclone config. Errors such as oauth2: token expired are also covered in Chapter 19.

7. The Backup Emergency Kit is missing, and restore requests a password

   Home Assistant 2025 scheduled backups use an automatically generated encryption key recorded in the Backup Emergency Kit. If the original Home Assistant system still works, open Settings → System → Backups → upper-right menu → Show encryption key and copy it to your password manager. If the original system and the kit are both gone, the encrypted backup cannot be recovered; there is no official backdoor. See Chapter 22 for general restore troubleshooting.

FAQ