Backup and restore

Three things make up an installation. Back up all three; each is useless for a full restore without the others.

What	Where (Compose)	Contains
Database	pgdata volume	Tasks, transcripts, events, memory, schedules, settings, the owner password hash, encrypted provider keys
Data files	data volume (/data)	Workspace files and generated artifacts
Encryption key	PCMD_ENCRYPTION_KEY in .env	The key that decrypts stored provider keys

Keep the encryption key somewhere other than the database backup. Anyone with both can read your stored provider keys. If you lose the key, the rest of a restore still works, but stored provider keys must be entered again. Keys supplied through environment variables are not in the database at all; back up .env as a whole for those.

Back up

Run these from the project directory. They work while the services are running.

Database

docker compose exec -T postgres pg_dump -U poietes -d poietes --format=custom > poietes-$(date +%F).dump

Data files

docker compose exec -T api tar -C /data -czf - workspace artifacts > poietes-data-$(date +%F).tar.gz

Configuration and key

cp .env poietes-env-$(date +%F).backup

Store the .env copy with the care you give a password manager export.

For a consistent pair, take the database dump first and the data archive right after. An artifact row without its file is reported as missing in the console rather than served empty; a file without a row is simply not listed.

Restore

On a fresh checkout with the same .env:

docker compose up -d postgres
docker compose exec -T postgres pg_restore -U poietes -d poietes --clean --if-exists < poietes-2026-01-31.dump
docker compose up -d --build
docker compose exec -T api tar -C /data -xzf - < poietes-data-2026-01-31.tar.gz

Then sign in with the owner password from the time of the backup. Tasks that were running when the backup was taken are picked up by the worker once their lease has expired, and continue from their last checkpoint.

What a backup keeps that you may have deleted

A backup is a copy of the past. Memory entries, tasks and artifacts deleted after a backup was taken still exist in that backup. Delete old backups if that matters.

Rotating the encryption key

There is no in-place rotation in this version. To change the key: note which connections use stored keys, set the new PCMD_ENCRYPTION_KEY, restart, and enter those keys again. Connections that read from environment variables are unaffected.

Without Docker

In development the database is in .local/pg-dev and data files are in ./data. Use pg_dump against 127.0.0.1:15791 and copy the data folder. The development encryption key is in .local/dev-encryption-key.