Backup & restore

A Hiveloom backup is a single tarball containing everything stateful in your instance. Make one before every upgrade and on a schedule for disaster recovery.

Where the data lives

The default <data-dir> is /var/lib/hiveloom; check hiveloom doctor --data-dir <path> if you’ve changed it.

Create a backup

hiveloom backup create --output /var/backups/hiveloom-$(date +%F).tar.gz
hiveloom backup list

Both commands hit the running service and operate online — there is no need to stop hiveloom serve first.

The archive contains all three pieces (platform DB, tenant DBs, master key). Treat it as top-tier secret material: anyone with this archive can decrypt every stored credential. Store it in encrypted off-VPS storage, not on the same VPS.

Recommended cadence

• Manual: before every upgrade.
• Automated: nightly cron running hiveloom backup create --output <dir>/hiveloom-$(date +%F).tar.gz, then a sync to off-VPS storage. Rotate to keep ~30 days locally.

Restore from a backup

sudo systemctl stop hiveloom
hiveloom backup restore --input /var/backups/hiveloom-2026-04-25.tar.gz
sudo systemctl start hiveloom
hiveloom health

Restore is destructive: it replaces the running data directory’s contents with what’s in the archive. Anything created after the archive was made is lost.

Verifying a backup

After creating an archive, do a dry-run integrity check on a non-prod host:

1. Spin up a fresh VPS or container with the same Hiveloom binary version.
2. hiveloom backup restore --input <archive> against an empty /var/lib/hiveloom.
3. hiveloom doctor — every check should be ok.
4. hiveloom tenant list and hiveloom agent list --tenant <slug> — confirm the tenant and agent counts match what you expect.

This is the only way to know the archive actually decrypts and deserialises before you need it.

Common failure modes