Backup & migrate.

A .sudo-bundle is a single zip file that contains everything you need to recreate an install on a new device. Export one from the Ready screen, restore it on a fresh Pi, and the wizard skips straight to starting services.

What's inside

The zip contains two entries:

1. bundle.json

json
{
  "schemaVersion": 1,
  "sudoRelease": "0.1.0",
  "createdAt": "2026-04-21T10:15:00.000Z",
  "host": { "os": "linux", "arch": "arm64", "platform": "pi" },
  "secrets": {
    "algo": "xchacha20poly1305",
    "kdf": "argon2id",
    "kdfParams": { "opslimit": ..., "memlimit": ..., "salt": "..." },
    "nonce": "...",
    "ciphertext": "..."
  },
  "assistant": { "wakeWord": "Hey Sudo", "accentColor": "amber", "homeName": "Home" },
  "voiceLoop": { "wake_word": { ... }, "stt": { ... }, ... },
  "ha": {
    "exposedEntities": ["light.living_room", "switch.fan", ...],
    "areas": [{ "id": "...", "name": "Bedroom" }],
    "sudoAgentUser": { "username": "sudo_agent", "name": "Sudo Agent" }
  },
  "haConfigArchiveSha256": "ab12…"
}

2. ha-config.tar.gz

A tarball of homeassistant/config/ — your automations, scripts, helpers, areas, and storage. Excludes logs, the SQLite history DB, and auth-provider storage (unless you opt in during export).

Crypto

  • The secrets field holds your .env contents (CLAUDE_API_KEY, HA_TOKEN) encrypted with XChaCha20-Poly1305.
  • The encryption key is derived from your passphrase via Argon2id with a random salt per bundle.
  • The passphrase is chosen at export time. Don't lose it; there is no recovery.
The bundle passphrase is unrelated to any device login — Sudo does not have one. It only protects the encrypted secrets inside the archive, so the bundle can be carried on a USB stick or emailed without leaking your API key.

Exporting

On the Ready screen, type a passphrase into the Export field and click Save bundle. The browser downloads the file; a copy is also kept under onboarding/data/bundles/sudo-<timestamp>.sudo-bundle so you have a local history.

Importing

  1. Run the installer on your new Pi. When the onboarding opens, pick Restore on the second stage.
  2. Upload the .sudo-bundle and enter its passphrase. Sudo decrypts, restores .env, extracts the Home Assistant config tarball, and replaces voice-loop/config.yaml.
  3. The flow continues — Engines and Hello detect the already-onboarded HA and reuse the restored token. You land on Ready without ever filling out a fresh form.

Manual inspection

A .sudo-bundle is just a zip. You can inspect it without running Sudo:

bash
unzip -l sudo-2026-04-21.sudo-bundle
#   Length      Date    Time    Name
#   --------  ----------  -----   ----
#       1842  04-21 10:15   bundle.json
#    1238491  04-21 10:15   ha-config.tar.gz

You can't read secrets.ciphertext without the passphrase, but everything else is plain JSON and a normal tarball.