Persistence, tenancy & operations
Operate AgentSpace safely across local development and Cloudflare Worker + D1 deployments with OIDC auth, migrations, and checksum backups.
Local vs remote persistence architecture
Build-time variable PUBLIC_AGENTSPACE_PERSISTENCE controls how the frontend repository layer persists state:
local(default local build): Uses deterministic browser storage with instant sample reset—ideal for zero-cost workflow design and demos.remote(production Worker build): Routes mutations through authenticated/api/v1/tenants/:tenantId/*endpoints with serialized writes,If-Matchversion headers, and 1-second cursor delta polling.
OIDC verification and tenant RBAC
Every tenant operation verifies caller membership and enforces least-privilege roles:
| Role | Workspace & work | Connectors, extensions & secrets | Audit & Flight Recorder |
|---|---|---|---|
owner | Read & write | Create, approve, disable, revoke | Full read access |
admin | Read & write | Create, approve, disable, revoke | Full read access |
member | Read, write & queue allowed runs | Read ready connectors | Full read access |
auditor | Read-only | Read-only metadata | Full read access |
D1 schema migrations (0001–0007)
Apply SQL migrations in migrations/ strictly in numerical order against a backed-up non-production database before promoting:
0001_agentspace.sql— Core users, tenants, memberships, workspaces, idempotency, and hash-chained audit tables.0002_transaction_support.sql&0003_workspace_request_correlation.sql— Transactional guards and trace correlation.0004_connector_lifecycle.sql— Governed connector states and outbound policy columns.0005_work_execution.sql— Work-linked jobs, tenant concurrency policy, single-active-attempt index, and cancellation columns.0006_execution_flight_recorder.sql— Append-only Flight Recorder event journal and replay ancestry.0007_platform_kernel.sql— Normalized entities, ordered change cursor feed, extension manifests, and secret references.
Atomic SQLite backup and checksum restore
For local SQLite databases, use the bundled atomic backup utility, which writes a companion SHA-256 manifest and refuses unconfirmed or checksum-mismatched restores:
node scripts/backend/sqlite-backup.mjs backup path\to\database.sqlite path\to\backups
node scripts/backend/sqlite-backup.mjs restore path\to\database.sqlite.TIMESTAMP.backup.json path\to\restored.sqlite --confirm Do not substitute local file copies for cloud D1 recovery. Production migrations require capturing the D1 Time Travel bookmark and running an explicit D1 logical export beforehand.
Pre-deployment readiness & rollback gate
Before any production Worker deployment, run the deterministic configuration gate:
npm run validate
PUBLIC_AGENTSPACE_PERSISTENCE=remote npm run backend:production-check backend:production-check blocks remote Worker release if wrangler.agentspace.jsonc still contains placeholder D1 IDs, placeholder OIDC URLs, non-HTTPS outbound origins, missing Queue bindings, or non-oidc authentication mode, while default wrangler.jsonc keeps static site deployments unblocked prior to backend activation.
tests/backend/auth.test.tstests/backend/migration.test.tstests/backend/backup.test.tstests/backend/health.test.ts