Skip to content

Backup & Restore

Your Kenzy server accumulates state you'd hate to lose — most of it recreatable with some effort, one part not at all:

  • Enrolled voice profiles — the only way to "restore" these without a backup is re-enrolling every person in the house.
  • Per-room node settings (rooms, calibrated thresholds, sounds, volume)
  • Backend service settings (models, voices, skills configuration)
  • Your Home Assistant curation (aliases, room defaults, exclusions)
  • Custom skills and dependency pins (constraints.txt)
  • Remembered facts and lockbox secrets (data/memory/ — the ledger, the encrypted lockbox, and by default its decryption key)
  • Active timers, alarms, and reminders

A backup is a single small .tar.gz of all of it — and it's complete even when your services run on different machines: the server fetches the voice profiles from the speaker host and the skills/curation from the LLM host and merges them into the one archive. (If a service is unreachable at backup time, the archive is still produced and the gap is recorded in its manifest.)

Downloading a backup

Open the dashboard → Settings → Backup → Download backup. That's it — the file (kenzy-backup-<date>.tar.gz) downloads to your browser. Keep a copy somewhere that isn't the server.

The archive carries the lockbox key by default — a backup's job is to bring everything back, and the key is data (without it, restored secrets are unreadable ciphertext). That also means the default archive can decrypt your stored secrets: treat it like a password file, or untick Include the lockbox key for a shareable archive that carries only unreadable ciphertext. (Restoring a key-less archive later: the lockbox preserves the unreadable file aside and starts fresh — drop the matching lockbox.key beside it to recover.)

Two more things stay out by default, each with an opt-in checkbox:

  • Include secrets adds .env (your API keys). Off by default because the archive then carries live credentials — whatever your setup keeps there, which for most installs means keys that can spend money with a cloud provider or control your smart home. Turn it on for a true one-file recovery, and then treat the file like a password: keep it somewhere encrypted, not in a synced Downloads folder.
  • Include everything adds models/. Off by default because models are bulky and kenzy-setup re-downloads them — but turn it on if you've placed a custom model on the server that exists nowhere else.

Restoring

From the dashboard

Settings → Restore from a backup… — pick your backup file, type RESTORE to confirm, and it's uploaded to the server and applied: configuration, Home Assistant curation, enrolled voice profiles, memories and lockbox secrets, schedules, and any custom skills. The server then restarts, and the rest of the fleet re-pulls its config and repopulates its own data automatically — so a whole-deployment recovery is one browser round-trip.

Two things to know: it overwrites the server's live settings (that's why it asks you to type RESTORE), and because a backup can contain custom skills — Python you authored, loaded at startup — the upload runs code under your admin session, the same trust the dashboard's in-place upgrade already carries. Only restore backups you made. Very large archives that bundled models/ (?full=1) exceed the upload path — use the CLI below for those.

From the command line

On a fresh install (after running the installer or kenzy-init):

kenzy-init --restore kenzy-backup-20260703-120000.tar.gz

Then finish up:

  1. Add your API keys to ~/.config/kenzy/.env (skip if the backup was made with Include secrets — they're already restored)
  2. kenzy-setup (re-download models; skip for an Include everything backup)
  3. Restart the services: systemctl --user restart 'kenzy-*'

TLS survives a restore — even onto a new machine

A backup never contains your TLS certificate or private key (host security material stays on its host, like .env — the one deliberate exception is the lockbox key, which is data). If the restored config had TLS enabled, the restore mints a fresh self-signed certificate in its place, so the restored server keeps speaking https/wss — Kenzy's clients don't pin certificates, so a new one is seamless. And because server.yaml stores an absolute cert path, a restore into a different folder (a new machine) relocates the certificate under the new config home and rewrites the tls: block to match — so recovery works anywhere, not just the original path.

On a multi-host deployment, restore the same archive on each host — every service reads only its own part of the config home, so one archive serves them all. (Custom wake-word model files living on room nodes are the one thing outside the archive — keep your own copy of those.)

Your rooms, tuning, voice profiles, curation, and skills are back; room nodes reconnect and pull their restored settings automatically.

Restore won't overwrite without permission

If any file in the archive already exists in the config home, the restore refuses and lists the collisions — nothing is written at all. Re-run with --force to overwrite (e.g. restoring over a freshly scaffolded config home, which is the common case).

Good habits

  • Download a fresh backup after enrolling voices, curating Home Assistant devices, or any calibration session you'd rather not redo.
  • Before a big upgrade or hardware change, grab one — it's one click.
  • The archive contains your configuration (including the node join token) and, by default, the lockbox and its key — treat it like a password file: private and preferably encrypted at rest, never posted anywhere public.