Upgrading and backups

> For operators of a running Agent Taskbay. At the end you will know what to back up, how to upgrade without losing data, and how to restore.

Taskbay keeps three kinds of state that must stay consistent with each other: the database, the artifact directory, and the vault keys. Backups, upgrades and restores are all about treating those three as one unit. Backup and restore tooling is not provided; this page tells you what to copy and what to check.

The project is pre-1.0 (0.2.0). Interfaces and migrations may change in any minor version. Read CHANGELOG.md before each upgrade.

Before you startCopy Anchor Link

• A source checkout deployment as described in Production deployment. The migration and rebuild commands are npm scripts in the repository.
• Database access for dumps (pg_dump and pg_restore for PostgreSQL).

What to back upCopy Anchor Link

Take the database dump and the artifact copy at the same time, and do not restore one without the other. The store writes artifact bytes before the database transaction commits, so a newer artifact directory than the database is harmless (extra files are never referenced). A newer database than the artifact directory is not: the database then points at archives that are missing.

For PGlite, stop the web process before copying the directory; only one process may own it, and a copy of a live directory is not known to be consistent.

pg_dump --format=custom --file=taskbay.dump "$A2A_DATABASE_URL"

Then copy the artifact directory, for example with rsync -a, immediately after.

UpgradeCopy Anchor Link

1. Read the changelog for anything that needs manual steps.

2. Back up (above).

3. Stop the workers and the web process. This is the supported order: nothing runs against a schema it was not built for.

4. Update the code and rebuild:

   Copy Text

   git pull

   Copy Text

   npm ci

   Copy Text

   npm run build

5. Apply migrations (see below).

6. Start web, then workers.

7. Check curl -i https://YOUR_ORIGIN/api/auth/session (expect 401 Sign in to continue.), sign in, open a task that existed before the upgrade, and send a message.

MigrationsCopy Anchor Link

Migration files are applied in order and recorded in the agent_taskbay_migrations table.

When migrations run by themselves:

Migrations are numbered (Migration0001_Baseline, Migration0002_…), and the number of the newest one is the schema version of a release (DB_SCHEMA_VERSION in src/server/adapters/db/schema-version.ts, kept equal to the files by a test). A database at version N reaches the current version by running every migration after N, in order.

When automatic migration is on, startup says which case it found:

Releases up to 0.2.0 shipped sixteen timestamp-named migrations; they were squashed into Migration0001_Baseline. A database from 0.2.0 or earlier that has all sixteen applied is recognised and adopted: its tables are kept and the migrations table is rewritten to the single baseline. It is shown as schema v0 in the messages and backup name until then. A database that is missing some of the sixteen is refused with This database was created by an older Agent Taskbay release…. Start it once with agent-taskbay@0.2.0, then start the new version.

With more than one web replica keep A2A_AUTO_MIGRATE off and run db:migrate once per release. Replicas racing to migrate is the case the default avoids.

The migrations add append-only triggers on the security audit table and on the fixed core of approval requests. Updates and deletes on those rows fail with audit records are append-only or decision request core is immutable. Do not try to clean them up; take them into account when you write data fixes.

Treat db:migrate:down as a developer tool. It is not a substitute for restoring a backup: whether every migration can be reverted without losing data is not verified, and projection data may need rebuilding afterwards.

Rebuild projectionsCopy Anchor Link

The task views Taskbay shows are projections of an append-only event ledger. A rebuild recomputes them from the retained events and original artifact archives. It does not send messages to agents and does not modify the ledger. You need it when:

• you upgrade across a version whose notes say so (older tasks stay readable but may use an older projection until they are observed again or rebuilt), or
• tasks with binary artifacts predate artifact permission records. A rebuild creates the server-side references that authorize downloads.

Apply migrations first, then:

npm run db:projections:rebuild

With PostgreSQL the web process can stay up and keeps serving the last readable projection. It prints one line per task, Rebuilt task <id> with projector 2., and ends with Rebuilt <n> task projections. Re-running safely resumes by task. Interrupted runs can simply be repeated.

Use the same database and artifact settings as the web and worker. If the environment differs, the rebuild looks at the wrong data.

Rebuild failuresCopy Anchor Link

A failed task keeps its previous projection. The script stops at the first error.

RestoreCopy Anchor Link

1. Stop web and workers.

2. Restore the database into an empty database from the dump:

   Copy Text

   pg_restore --dbname="$A2A_DATABASE_URL" --no-owner taskbay.dump

3. Restore the artifact directory from the copy made at the same time or later.

4. Restore the vault keys into A2A_VAULT_KEYS and A2A_VAULT_ACTIVE_KEY, plus your other server secrets.

5. Run npm run db:migration:pending. It should list nothing if the dump came from the same version; if you restore into a newer code version, run npm run db:migrate.

6. Start web, then workers. Workers pick up unfinished work after leases expire (15 seconds for streams, 60 seconds for command dispatch).

7. Run the checks from the upgrade steps, and open a task that has an artifact to confirm the download works.

Practice this on a copy before you need it. Whether a restored deployment resumes cleanly after losing a worker or host has not been tested by the project.

After a restore, a command that was dispatched but whose outcome is not recorded is shown as needing investigation. Taskbay never resends it on its own, because the agent may have processed it.

Moving between database profilesCopy Anchor Link

There is no tool to move data from PGlite to PostgreSQL, or back. Start production on PostgreSQL. If you need to keep a PGlite demo's data, that is not supported by anything in this repository.

When it failsCopy Anchor Link

LimitsCopy Anchor Link

• No scripted backup, restore or retention. No online consistent snapshot across database and artifacts.
• Artifacts are never deleted by Taskbay; the directory grows with use.
• No version-to-version upgrade notes exist yet beyond the changelog. The published versions are 0.1.0, 0.1.1 and 0.2.0. 0.1.1 changed no runtime behavior. 0.2.0 redesigns the console and adds a Home screen; it changes no HTTP API, database schema or configuration, so there is nothing to migrate when upgrading from 0.1.x. The theme preference is stored under a new key, so the console falls back to your system theme once.

RelatedCopy Anchor Link

• Production deployment
• Running and workers
• Troubleshooting
• Durable tasks