Getting Started/Deploying Trinity/Backup and Restore

Backup and Restore

Protect your Trinity database with regular backups. The database contains all agent state, schedules, chat history, and credentials metadata.

When to Run This

•Before every upgrade — always take a backup before pulling new code
•Daily on production instances — automate with cron
•Before any destructive operation — deleting agents, bulk changes, schema migrations

What to Back Up

Component	Back up?	Where it lives	Notes
trinity.db	Yes — primary target	Named volume `trinity_trinity-data` (dev) or bind-mount at `TRINITY_DATA_PATH` (prod)	Agents, schedules, chat history, credentials metadata, audit log
.env file	Yes	Host filesystem	Not in git. Losing it means losing `CREDENTIAL_ENCRYPTION_KEY`, making all encrypted credentials unrecoverable.
Agent code	Not separately	Git repositories	Each agent's code lives in a git repo — already versioned there.
Redis data	Not separately	Named volume `trinity_redis-data`	Ephemeral: JWT tokens, capacity counters. All regenerated on next start.
Platform config	Not separately	Git repo	`docker-compose.yml`, `config/`, `scripts/` — all in version control.

Backup Procedure

Step 1: Back Up the Database

Run on the host with services running — it does not require stopping anything:

Development (named volume)

docker run --rm \
  -v trinity_trinity-data:/data \
  -v ~/backups:/backup \
  alpine cp /data/trinity.db /backup/trinity-$(date +%Y%m%d-%H%M%S).db

Production note: On a server using docker-compose.prod.yml, the database lives at ${TRINITY_DATA_PATH}/trinity.db (a bind-mount directory), not in the named volume:

cp /srv/trinity-data/trinity.db ~/backups/trinity-$(date +%Y%m%d-%H%M%S).db

Step 2: Back Up `.env`

cp .env ~/backups/trinity-env-$(date +%Y%m%d).bak
chmod 600 ~/backups/trinity-env-$(date +%Y%m%d).bak

Store this in a secure location (password manager, encrypted storage). Never commit it to git.

Verify

sqlite3 ~/backups/trinity-YYYYMMDD-HHMMSS.db ".tables"

Expected: a list of table names with no errors. If sqlite3 is not installed locally:

docker run --rm \
  -v ~/backups:/backup \
  alpine sh -c "apk add -q sqlite && sqlite3 /backup/trinity-YYYYMMDD-HHMMSS.db '.tables'"

Restore Procedure

1. Stop the backend and scheduler to release the SQLite write lock

# Development
docker compose stop backend scheduler

# Production
docker compose -f docker-compose.prod.yml stop backend scheduler

2. Copy the backup into the volume

docker run --rm \
  -v trinity_trinity-data:/data \
  -v ~/backups:/backup \
  alpine cp /backup/trinity-YYYYMMDD-HHMMSS.db /data/trinity.db

3. Restart services

# Development
docker compose start backend scheduler

# Production
docker compose -f docker-compose.prod.yml start backend scheduler

4. Verify health

curl -s http://localhost:8000/health
curl -s http://localhost:8001/health

Automation

Add a cron job to back up the database daily and retain 14 days of history:

crontab -e

Add this line (adjust paths as needed):

0 3 * * * docker run --rm -v trinity_trinity-data:/data -v ~/backups:/backup alpine cp /data/trinity.db /backup/trinity-$(date +\%Y\%m\%d-\%H\%M\%S).db && find ~/backups -name "trinity-*.db" -mtime +14 -delete

This runs at 03:00 daily, creates a timestamped backup, and deletes backups older than 14 days.

Verify the cron job is working after the first scheduled run:

ls -lh ~/backups/trinity-*.db

What Is and Is Not in the Database

In trinity.db

•All agent metadata (names, ownership, settings)
•All schedules and execution history
•All chat sessions and message history
•Credentials metadata (not plaintext values)
•Encrypted channel bot tokens (Slack, Telegram, WhatsApp)
•Audit log
•User accounts and sharing configuration

Not in trinity.db

•Agent source code (in git)
•Runtime secrets held by Redis (ephemeral)
•Container logs (in Vector log files)
•Platform images (rebuild from source)

Upgrading Monitoring