Backups and restore
In version 3.0, the server stores database state in SQL (SQLite or PostgreSQL) and experiment files on disk. The server provides an online backup tool that captures consistent snapshots while the server continues running.
Data directory structure
Section titled “Data directory structure”<data>/├── workspaces/│ └── <workspace_id>/│ ├── store/│ │ ├── runs/│ │ │ └── <run_id>/│ │ │ ├── meta.json│ │ │ ├── events.jsonl│ │ │ ├── scalars/│ │ │ ├── media/│ │ │ └── artifacts.json│ │ └── objects/ # Local blobs (when --objects file://)│ └── lineage/ # Shadow Git repositories└── server/ ├── agenticml.db # SQLite database (permissions 0600) ├── server.lock # Single-process lock (SQLite only) └── tmp/ # Ingest staging directoryWhen using Amazon S3 (--objects s3://...), content-addressed blobs live in the bucket under {workspace_id}/objects/{hh}/{sha256}.
Consistent online backup: server backup
Section titled “Consistent online backup: server backup”Run agenticml server backup while the server is live:
agenticml server backup --to /backups/20261109-0000Consistency rule
Section titled “Consistency rule”- Database snapshot first:
- SQLite: The command uses the SQLite Online Backup API to create a consistent point-in-time snapshot of
agenticml.db. - PostgreSQL: Take a database dump first using
pg_dump, then pass--files-only:Terminal window pg_dump --format=custom "$DATABASE_URL" > /backups/20261109-0000/server.dumpagenticml server backup --to /backups/20261109-0000 --files-only
- SQLite: The command uses the SQLite Online Backup API to create a consistent point-in-time snapshot of
- Committed run files second: The backup tool copies each run file only up to the committed size recorded in the database snapshot (
run_filestable). Any trailing bytes appended after the snapshot are excluded, guaranteeing file consistency with the database. - Objects and lineage: Content-addressed objects on local disk and shadow Git lineage repositories are copied.
- S3 objects: When using S3, blobs are not copied. S3 objects are protected via bucket versioning and AWS Backup.
- Manifest: A summary manifest with file and object counts is written to
BACKUP.json.
Restoring a backup
Section titled “Restoring a backup”Restoring SQLite
Section titled “Restoring SQLite”- Point
agenticml server servedirectly to the backup directory:Terminal window agenticml server serve --data /backups/20261109-0000 - Or copy the backup directory contents to your standard data directory and ensure proper file ownership:
Terminal window sudo systemctl stop agenticml-serversudo cp -a /backups/20261109-0000/* /var/lib/agenticml-server/sudo chown -R agenticml:agenticml /var/lib/agenticml-serversudo systemctl start agenticml-server - Run
agenticml server verify --data /var/lib/agenticml-serverto verify data integrity.
Restoring PostgreSQL
Section titled “Restoring PostgreSQL”- Restore the PostgreSQL dump into an empty database:
Terminal window pg_restore --clean --if-exists -d "$DATABASE_URL" /backups/20261109-0000/server.dump - Start the server pointing to the restored data directory and database:
Terminal window agenticml server serve --data /backups/20261109-0000 --database "$DATABASE_URL"
Continue to Upgrades and troubleshooting for maintenance and version migration procedures.