Backups, restore and owner recovery

Back up more than source#

Git stores code. A recoverable installation also needs PostgreSQL, private package storage while its files are required, the authentication secret, the envelope key, and operator-controlled agent identity backups. Store keys separately from the database dump and restrict access to both.

Pause new work, stop writers and copy database/package state consistently. Record the source revision, migration state, backup time and key identifiers without recording secret values in the inventory. Encrypt off-host backups and test restore into a separate environment.

umask 077
pg_dump --format=custom --no-owner --no-acl --file=bridge.dump

Configure PGHOST, PGPORT, PGUSER, PGDATABASE and a permission-restricted PGPASSFILE before running the command. They must point to the intended installation. Do not put a database password in a command argument. Use a client compatible with PostgreSQL 18.

Restore into a separate database#

1. Create a new, empty private database and stop the target app.
2. Restore the dump with errors treated as fatal.
3. Restore matching package storage and required encryption keys.
4. Point the isolated application environment to the restored database.
5. Invalidate restored access before exposing it.
6. Verify sign-in, projects and records. Inspect unfinished work and deliberately issue replacement agent access.

pg_restore --no-owner --no-acl --exit-on-error --single-transaction --dbname="$PGDATABASE" bridge.dump

BRIDGE_MAINTENANCE_ACTION=prepare-restore BRIDGE_MAINTENANCE_SCOPE=all BRIDGE_CONFIRM_RESTORE=DISABLE_RESTORED_ACCESS pnpm exec tsx scripts/maintain.ts

The maintenance command revokes credentials, fences agent sessions, pauses projects and marks unfinished tasks for reconciliation. It is deliberately disruptive. Verify the target before execution; never run it against the only working production database merely to test the procedure.

Lost administrator password#

For ordinary changes use My account. For owner recovery, back up first and load the intended database environment. Supply BRIDGE_OWNER_EMAIL, a new protected BRIDGE_OWNER_PASSWORD, and BRIDGE_RECOVERY_ACTION=RESET_OWNER_PASSWORD to:

pnpm exec tsx scripts/recover-owner.ts

Recovery invalidates owner access, revokes agent credentials and pauses work. Use the recovery procedure for an existing account. If another platform administrator can resolve the problem through Administration, assess that narrower route before using global recovery.

Verify recovery#

Check record counts and representative conversations, task evidence, package metadata and any files that should still exist. Attempt an old credential and confirm it cannot resume work. Provision a replacement in the restored environment, perform a harmless task, and test backup access before switching traffic.

The upstream restore-drill.ts exercises a synthetic Windows development restore. For deployment recovery, follow the procedure above and retain the results of your own restore check. See the verification record for recorded documentation scenarios.