Back up and restore

AgentArea ships no backup tooling. There is no CronJob in the chart, no pg_dump script in the repository, and no snapshot command. Backup is entirely your responsibility, and a default install has none. This guide lists what has to be captured, in what order to restore it, and the one item whose loss cannot be recovered from — the secret encryption key.

Prerequisites

Administrative access to the PostgreSQL instance
Credentials for the object store
kubectl access to the namespace, or shell access to the Compose host

Steps

Inventory what holds state

Store	Contents	Loss means
PostgreSQL `agentarea`	Agents, tasks, MCP server records, audit events, encrypted secrets	Everything the product is
PostgreSQL `temporal`	Workflow history for in-flight and completed tasks	Running tasks cannot resume
PostgreSQL `kratos`	Identities and credentials	Every user must re-register
PostgreSQL `openfga`	Authorization tuples	All access grants; the platform fails closed
PostgreSQL `keto`	Authorization tuples, when `keto.enabled=true`	As above
Object store: documents bucket	Uploaded files	User content
Object store: artifacts bucket	Task artifacts, content-addressed	Task outputs
`SECRET_MANAGER_ENCRYPTION_KEY`	The Fernet key for `encrypted_secrets`	Every stored credential, unrecoverably
Kubernetes Secrets	Database and object-store credentials, the Kratos JWKS, sandbox HMAC secrets	Recoverable by regenerating, except the encryption key

Valkey holds Redis Streams for sandbox execution requests and channel inbound traffic. It is working state, not a system of record. valkey.dataStorage is disabled by default in the chart. Losing it drops in-flight stream entries; it does not lose committed data.

Back up the encryption key first, and separately

SECRET_MANAGER_ENCRYPTION_KEY decrypts the encrypted_secrets table. A database backup without it restores ciphertext nobody can open, and there is no recovery path and no re-encryption command in the platform.Store it somewhere that is not the database backup — otherwise one compromised artifact yields both the ciphertext and the key.

kubectl get secret -n agentarea agentarea-app-secrets \
  -o jsonpath='{.data.encryption-key}' | base64 -d

Capture the other generated values at the same time, from agentarea-app-secrets (auth-secret, api-auth-header-value, sandbox-activation-secret), <release>-agentarea-sandbox-cleanup-auth (token), and <release>-kratos-jwks (jwks_b64).Losing the Kratos JWKS invalidates every issued session token — recoverable, but every user is logged out. Losing the sandbox HMAC secrets is harmless as long as you regenerate both sides together.

Back up PostgreSQL

Back up all databases on the instance, not just agentarea. A restore that brings back the platform database while leaving openfga behind produces a system where every authorization check fails closed.

pg_dumpall -h "$POSTGRES_HOST" -U "$POSTGRES_USER" \
  | gzip > agentarea-$(date +%Y%m%d_%H%M%S).sql.gz

Or per-database, if you prefer restoring them independently:

for db in agentarea temporal kratos openfga; do
  pg_dump -h "$POSTGRES_HOST" -U "$POSTGRES_USER" -Fc "$db" \
    > "${db}-$(date +%Y%m%d).dump"
done

On a managed instance, use the provider’s automated backups and point-in-time recovery instead. That is the main practical argument for setting postgresql.enabled=false — the bundled StatefulSet has no replication, no backup, and no PITR, which is why the chart’s own values file marks it as not for production.Under Compose the database is a bind mount at ./data/postgres. A filesystem copy of a running PostgreSQL data directory is not a valid backup; stop the container first, or use pg_dump against the running instance.

Back up the object store

The artifacts bucket is content-addressed, so objects are immutable once written — an incremental sync is sufficient and never needs to re-transfer.

rclone sync rustfs:agentarea-documents s3-backup:agentarea-documents
rclone sync rustfs:artifacts           s3-backup:artifacts

Bucket names come from global.storage.bucket and, under Compose, from DOCUMENTS_BUCKET and ARTIFACTS_BUCKET in .env. The Compose stack already uses rclone for bucket creation, so the image and configuration pattern are present in docker-compose.yaml to copy from.Artifacts are referenced by checksum from rows in the agentarea database. Back up the database and the artifacts bucket close together in time, or a restore yields task records pointing at objects that are not there.

Restore

Order matters.

Provision infrastructure. Empty PostgreSQL and object store, reachable at the same names.

Restore the Secrets first, with the original encryption key. Create them before installing so the chart’s lookup finds them and does not generate replacements.

kubectl create secret generic agentarea-app-secrets -n agentarea \
  --from-literal=encryption-key='<original key>' \
  --from-literal=auth-secret='<original>' \
  --from-literal=api-auth-header-value='<original>' \
  --from-literal=sandbox-activation-secret='<original>'

Restore PostgreSQL, all databases.

gunzip -c agentarea-20260729_020000.sql.gz | psql -h "$POSTGRES_HOST" -U "$POSTGRES_USER"

Restore the object store.

rclone sync s3-backup:agentarea-documents rustfs:agentarea-documents
rclone sync s3-backup:artifacts           rustfs:artifacts

Install or start the platform. The migration step runs agentarea-api migrate, which finds an existing revision and applies only what is outstanding — correct behaviour when restoring a backup taken from an older version. See database and migrations.
Restore Kratos, if it was not part of the dump. Identities live in the kratos database.

Restoring the database before the Secrets is the mistake that costs you the data: the chart generates a fresh encryption key on install, and the restored ciphertext then cannot be read with it.

Understand what a restore does not bring back

In-flight tasks. Temporal workflow history restores, but the worker reconnects to a cluster whose view of time has jumped. Treat tasks that were running at backup time as lost and re-run them.
Sandbox state. Sandboxes are ephemeral; nothing about a live sandbox survives.
Valkey stream entries not yet consumed at backup time.

Verify

A backup you have not restored is a hypothesis. Restore into a scratch namespace and check all four layers. Confirm the schema is at a known revision:

kubectl exec -n agentarea-restore deploy/agentarea-backend -- \
  sh -c 'cd /app/apps/api && alembic current'

Confirm the encryption key matches the restored ciphertext — this is the check that catches the failure mode that matters:

kubectl exec -n agentarea-restore deploy/agentarea-backend -- \
  python -c "
from cryptography.fernet import Fernet
import os
Fernet(os.environ['SECRET_MANAGER_ENCRYPTION_KEY'])
print('key is well-formed')
"

Then read a secret back through the application — open a configured LLM provider in the UI. If the key is wrong, the read fails with InvalidToken, and a well-formed key proves nothing on its own. Confirm row counts against the source:

psql -h "$POSTGRES_HOST" -U "$POSTGRES_USER" -d agentarea \
  -c "SELECT 'agents', count(*) FROM agents
      UNION ALL SELECT 'tasks', count(*) FROM tasks
      UNION ALL SELECT 'secrets', count(*) FROM encrypted_secrets;"

Confirm artifacts resolve: open a completed task in the UI and download its artifact. That exercises the database reference, the object store, and the presigned URL path together.

Troubleshooting

Everything restores, and every stored credential fails with InvalidToken

The encryption key does not match the ciphertext. Restore the original key. There is no way to recover the plaintext without it; the secrets have to be re-entered by hand.

The API starts but every authorization check denies

The openfga database was not restored, or OpenFGA bootstrapped a new store. The authorization reader fails closed, which presents as a working platform where nothing is permitted.

Users cannot log in after a restore

The kratos database or the JWKS secret is missing. A regenerated JWKS invalidates all existing sessions; users must sign in again.

helm install against a restored database generates new credentials that do not match it

The chart generates secrets only when lookup finds none. Create the Secrets before installing.

Task rows exist but artifacts 404

The database backup is newer than the object-store copy. Restore the object store from a point at or after the database backup, and re-run affected tasks.

A filesystem copy of ./data/postgres will not start

A hot copy of a running data directory is not consistent. Use pg_dump , or stop the container before copying.

Choose a secrets backend

Configure where AgentArea stores workspace secrets

Run database migrations

Apply, inspect, and recover Alembic migrations for the AgentArea schema, on Kubernetes and on

Upgrade a deployment

Move an AgentArea deployment to a new version safely

Deploy on Kubernetes with Helm

Install the agentarea Helm chart, decide which bundled dependencies to keep

Start here

Concepts

Guides

Self-host

Reference

API reference

API endpoints

Community

Back up and restore

Prerequisites

Steps

Inventory what holds state

Back up the encryption key first, and separately

Back up PostgreSQL

Back up the object store

Restore

Understand what a restore does not bring back

Verify

Troubleshooting

Choose a secrets backend

Run database migrations

Upgrade a deployment

Deploy on Kubernetes with Helm

​Prerequisites

​Steps

Inventory what holds state

Back up the encryption key first, and separately

Back up PostgreSQL

Back up the object store

Restore

Understand what a restore does not bring back

​Verify

​Troubleshooting

​Related

Choose a secrets backend

Run database migrations

Upgrade a deployment

Deploy on Kubernetes with Helm

Prerequisites

Steps

Verify

Troubleshooting

Related