Backups & disaster recovery

AiHummer’s state is small and well-defined, which makes backups straightforward — as long as you remember that the master key is not in the database and must be protected on its own. This page covers what to back up, how, and how to recover.

What to back up

There are three independent things to protect:

What	Where	Why
Database	PostgreSQL	The source of truth — agents, conversations, memory, settings, encrypted secrets
Blobs	`AIHUMMER_BLOB_DIR`	Media and file attachments referenced by the database
Master key	`AIHUMMER_MASTER_KEY`	Decrypts the vault; never stored in the database

[!DANGER] Back up AIHUMMER_MASTER_KEY separately and store it somewhere other than the database dump. The vault is envelope-encrypted under this key — lose the master key and the encrypted secrets are unrecoverable, even with a perfect database backup.

PostgreSQL is the source of truth

Treat the database as authoritative. The recommended baseline is a daily pg_dump plus WAL archiving for point-in-time recovery (PITR) so you can roll forward to any moment between dumps.

# Daily logical dump
pg_dump "$AIHUMMER_DATABASE_URL" --format=custom --file=aihummer-$(date +%F).dump

Pair the dumps with continuous WAL archiving (PITR) for fine-grained recovery between snapshots.

Backing up blobs

Media and file attachments live under AIHUMMER_BLOB_DIR. Back this directory up alongside the database so restored conversations can still resolve their attachments. If AIHUMMER_BLOB_DIR is not configured, the media/file service is not active and there is nothing extra to copy.

The aihummer backup & restore commands

The CLI bundles the routine into two commands:

aihummer backup [dir]      # write a backup into [dir]
aihummer restore <file>    # restore from a backup file

Use these for ordinary operational backups and restores. See the CLI reference for related commands.

[!WARNING] A database restore alone is not a full recovery. Restore the blob directory too, and make sure the same AIHUMMER_MASTER_KEY is present on the target host — otherwise the vault cannot be decrypted.

Disaster recovery

For a full host-loss scenario, follow the disaster-recovery runbook (docs/runbooks/disaster-recovery.md). The recovery order is:

Provision a host and install the same AiHummer version.
Restore the master key into AIHUMMER_MASTER_KEY.
Restore the database (latest dump, then roll forward via WAL/PITR if used).
Restore the blob directory at AIHUMMER_BLOB_DIR.
Bring services up (aihummer up) and verify with /readyz and deploy/host/smoke.sh.

[!TIP] Also keep AIHUMMER_MEDIA_TOKEN_SECRET with your master key. It keeps signed media download URLs valid across restarts and rebuilds.

Where to next

Probes and the smoke test used to verify a restore: systemd & health checks.
Versioning and migrations during an upgrade: Upgrade policy.