Back up and restore a self-hosted vault

Use this for local-only daemon vaults and self-hosted full-experience vaults. Hosted vault backup and restore are operated by KB-1 as part of the Hosted runtime. See Export and backups for Hosted vaults for the Hosted workflow.

What to back up

Back up the vault folder under the daemon state directory:

$KB1_HOME/vaults/<vault-id>/

That folder includes the Markdown files, attachments, vault metadata, and the .kb1/vault.json identity file. Keep daemon runtime configuration, relay tokens, service files, and private-network settings in a separate secrets backup.

Cloud organization membership is not stored inside the local vault folder. A self-hosted backup preserves your vault content, not your Cloud account state.

Flush before snapshotting

Before copying a live vault, force dirty editor sessions to disk:

curl -fsS -X POST http://127.0.0.1:7382/api/vaults/<vault-id>/ops/flush

A successful response looks like this:

{ "ok": true, "flushed": 0, "durableAsOf": "2026-06-12T09:00:00.000Z" }

flushed can be greater than zero when KB-1 had live edits to materialize.

Create a backup

kb1_home="${KB1_HOME:-$HOME/.kb1}"
vault_id="<vault-id>"
backup_root="$HOME/kb1-backups/$(date +%Y%m%d-%H%M%S)"

mkdir -p "$backup_root"
rsync -a --delete   "$kb1_home/vaults/$vault_id/"   "$backup_root/$vault_id/"

For high-value vaults, store at least one copy offline or in a private backup system you control.

Restore on the same machine

Stop the daemon.
Move the damaged vault folder aside instead of deleting it.
Copy the backup to $KB1_HOME/vaults/<vault-id>.
Confirm .kb1/vault.json exists in the restored folder.
Start the daemon.
Verify the vault appears:

curl -fsS http://127.0.0.1:7382/api/vaults
curl -fsS http://127.0.0.1:7382/api/vaults/<vault-id>/vault

Restore on a new machine

Install the daemon, choose the intended KB1_HOME, restore the vault folder under $KB1_HOME/vaults/, and start the daemon. If this vault uses Cloud relay, configure fresh relay settings for the new daemon runtime instead of copying old machine secrets blindly.