Backups & Disaster Recovery

The supported backup is a verified cold backup of the data directory, built into the server from 0.12.2 (cortexdb backup, cortexdb restore, cortexdb backup-verify), so the image needs nothing else:

• cold: stop the server first. A backup of a data directory a running server still holds is refused (exit code 3).
• complete: the memories and their indexes, the license (license.json), the token minter's keys (minter-keys/, so the credentials it issued keep working), the generated API key and the console's settings. A restored server comes back as itself.
• verified: every file is recorded with its SHA-256, and a restore writes nothing into place until every byte verifies.

Taking a backup

docker stop -t 120 cortexdb      # 120 s lets the server finish its shutdown
docker run --rm -v cortexdb-data:/data -v "$PWD":/backup --entrypoint cortexdb \
  cortexdb/cortexdb:v0.14.0 backup /data /backup/cortexdb-$(date +%F).tar.gz
docker start cortexdb

Copy the archive off the host; that step is yours to run.

Verifying an archive

docker run --rm -v "$PWD":/backup --entrypoint cortexdb \
  cortexdb/cortexdb:v0.14.0 backup-verify /backup/cortexdb-2026-10-16.tar.gz

Run it after moving an archive between hosts, and from time to time on the archives you keep.

Restoring

Restore into a new, empty volume (a restore never writes over data), then run the server on it:

docker volume create cortexdb-restored
docker run --rm -v cortexdb-restored:/data -v "$PWD":/backup --entrypoint cortexdb \
  cortexdb/cortexdb:v0.14.0 restore /backup/cortexdb-2026-10-16.tar.gz /data
docker run -d --name cortexdb --restart unless-stopped --stop-timeout 120 \
  -p 127.0.0.1:3141:3141 -v cortexdb-restored:/data -e CORTEX_EMBEDDING_API_KEY=$OPENAI_API_KEY \
  cortexdb/cortexdb:v0.14.0
curl -s 'http://127.0.0.1:3141/v1/admin/ready?deep=1'

The restored files take the owner of the directory restored into, so the server can open them. The same credentials, memories and license work as before; check with a recall your application makes.

Without Docker the commands are the same on the binary: cortexdb backup DATA_DIR ARCHIVE, cortexdb restore ARCHIVE NEW_DIR, cortexdb backup-verify ARCHIVE.

A restored 0.14.0 copy waits for an acknowledgement

A backup of a 0.14.0 data directory holds its access state (rosters, sets, holds) as it was when the backup was taken, and access may have changed since: someone left, a channel became private. So a restored copy holds each tenant root until it is acknowledged: every request naming the root answers 503 ACCESS_RESTORE_PENDING (not retriable) until the root's access sources have sent their state again and acknowledged, or the operator acknowledges:

curl -sS -X POST "$CORTEX_URL/v1/admin/access/restore" \
  -H "Authorization: Bearer $CORTEX_API_KEY" -H "Content-Type: application/json" \
  -d '{"acknowledge": true, "reason": "restored from the 2026-10-29 backup"}'
# {"scope":null,"restored_from":"…","acknowledged_at":"2026-10-29T08:27:54.456141346Z","pending_sources":[]}

Without ?scope= it acknowledges every root of the node; ?scope=<root> acknowledges one. When you know access did not change since the backup, mark the restored directory before its first start instead, and it serves at once:

docker run --rm -v cortexdb-restored:/data --entrypoint cortexdb \
  cortexdb/cortexdb:v0.14.0 restore-check --data-dir /data --access-state unchanged

While a root waits it serves only what a resync needs (the registry listing, the acknowledgements, watch, a connector's rehomes, watermarks and account resolution), the operator's forgets and erasures, and the token routes. A consistency token issued before the restore is answered with consistency_reset: true.

What to keep separately

No data-directory backup holds these; keep them with your own secrets:

• the environment the server runs with: provider keys and CORTEX_API_KEY (CORTEX_LICENSE is optional, since the license is in the archive);
• keys kept outside the data dir: CORTEX_V1_MINTER_KEY_DIR, CORTEX_ICE_KEY_FILE;
• with the segment store on, the bucket itself.

On 0.12.1

0.12.1 has no built-in backup and its image has no Python for the older scripts/cold_backup.py. Take a cold copy of the volume instead, and record its checksum:

docker stop -t 120 cortexdb
docker run --rm -v cortexdb-data:/data -v "$PWD":/backup busybox \
  tar -czf /backup/cortexdb-$(date +%F).tar.gz -C /data .
sha256sum cortexdb-$(date +%F).tar.gz > cortexdb-$(date +%F).tar.gz.sha256
docker start cortexdb

To restore one, check it, unpack it into a new, empty volume, and run the server on that volume:

sha256sum -c cortexdb-2026-10-16.tar.gz.sha256
docker volume create cortexdb-restored
docker run --rm -v cortexdb-restored:/data -v "$PWD":/backup busybox \
  tar -xzf /backup/cortexdb-2026-10-16.tar.gz -C /data

A copy made this way is not a cortexdb backup archive: after upgrading to 0.12.2, take a new backup with cortexdb backup.

Recovery point and scheduling

Backups are cold, so your recovery point is set by how often you can afford the stop, backup, start window:

• a nightly window: stop, back up, start, copy off the host;
• verify each archive after copying it, and again before you rely on it;
• keep several generations off the host. A backup you have never restored is not a backup.

Related docs

• Export & Import: logical export of events, not a full backup
• Enterprise Security
• Deployment Presets