Storage and backup

Jatevo stores console state and encrypted provider credentials under DATA_DIR. Native source installs default to ./data; the Mac installer uses ~/Library/Application Support/Jatevo/data; Docker uses the named data volume mounted at /data.

The optional codex-lb engine stores its database and encryption key in the separate codexlb-data volume. The engine-bootstrap volume contains only its generated bootstrap token; it can be recreated from secrets.json by initialization.

Encrypted backup

Requirements: Node 24 or later, GnuPG, OpenSSL and tar. A backup contains provider credentials and must remain private.

For the default Docker deployment:

COMPOSE=1 bash scripts/backup.sh /path/to/backups

Not run here: this block was not executed on the server that serves this page.

For Docker with subscription engines:

COMPOSE=1 COMPOSE_FILE=compose.yml:compose.engines.yml bash scripts/backup.sh /path/to/backups

Not run here: this block was not executed on the server that serves this page.

The script briefly stops the running console and engines, copies the actual container-mounted volumes, checks the console database, and restarts services that were previously running. Stopping the writers keeps the console and engine databases consistent. Services are also restarted if a backup step fails. Schedule this short interruption outside busy periods. Do not run concurrent backups or change the Compose project during a backup.

For a native installation:

COMPOSE=0 DATA_DIR=/path/to/jatevo/data bash scripts/backup.sh /path/to/backups

Not run here: this block was not executed on the server that serves this page.

The native path uses SQLite's backup API and includes secrets, provider credentials and authentication files. Stop native services while backing up if you need all file changes and database changes captured at exactly the same point. Any separately managed engine database or external database server needs its own backup.

COMPOSE=auto is the default: it detects the current project's console container, otherwise it uses local DATA_DIR. Explicit COMPOSE=1 refuses to silently fall back if the expected container is missing. COMPOSE_FILE and COMPOSE_PROJECT_NAME select the deployment.

The output is a dated .tar.gz.gpg archive. The script refuses missing console database or encryption secrets, checks database integrity, then verifies that the archive decrypts and can be listed. Diagnostic payload logs are excluded. Retain your deployment's .env separately and securely if it carries externally supplied secrets; it is outside the data volume.

The passphrase file defaults to ~/.config/jatevo/backup.pass and is generated with mode 0600 on the first backup. Keep a separate copy off the host. An encrypted archive without its passphrase cannot be restored. BACKUP_PASS_FILE, BACKUP_DIR and BACKUP_KEEP_DAYS override the passphrase location, destination and 14-day archive retention. A positional destination takes precedence over BACKUP_DIR.

Restore

Test a restore into a separate installation before relying on a backup. Extract privately:

umask 077
mkdir restored
gpg --decrypt --output backup.tar.gz /path/to/jatevo-backup.tar.gz.gpg
tar -xzf backup.tar.gz -C restored

Not run here: this block was not executed on the server that serves this page.

The extracted directory contains MANIFEST.txt, data/ and, when enabled, codexlb/. Stop the target services, then replace their data with the corresponding saved directories. Do not overlay a live database or retain an unrelated console.db-wal/console.db-shm from the target installation. Preserve secrets.json with its database so encrypted credentials remain readable.

For Docker, create the target containers without starting them (docker compose create), copy the saved data/. into console:/data/, and copy saved codexlb/. into codexlb:/var/lib/codex-lb/ when present. Use the same Compose override as the original deployment. Restore file ownership before starting: console data belongs to the image's node user; codex-lb data belongs to its app user. For example, after copying into an empty console volume:

docker compose run --rm --no-deps --user root console sh -c 'chown -R node:node /data'

Not run here: this block was not executed on the server that serves this page.

With the engine override, use the init service instead of console for that ownership command. A stopped sidecar has no network namespace for the console to join, while init can mount the data volume independently:

docker compose run --rm --no-deps --user root init sh -c 'chown -R node:node /data'

Not run here: this block was not executed on the server that serves this page.

For a codex-lb volume, use its image with --user root --entrypoint sh to run chown -R app:app /var/lib/codex-lb. Start with docker compose up -d; the initializer reconstructs the separate bootstrap token volume from the restored secret. Check sign-in, key policy and one request through each provider before routing team traffic to the restored gateway.

Retention

Request metadata is kept for 90 days and history for 180 days by default. Adjust requests_retention_days and events_retention_days with the operator CLI. The console records request attribution and token usage rather than retaining message bodies. Optional upstream engines have their own logging behavior; sidecar diagnostic logs use a temporary filesystem in Docker.

This page as markdown · llms.txt