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.12.8 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.12.8 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.12.8 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.12.8
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.

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