FrootAI.dev AgentSpace
On this page 5
Administer Worker + D1

Persistence, tenancy & operations

Operate AgentSpace safely across local development and Cloudflare Worker + D1 deployments with OIDC auth, migrations, and checksum backups.

Status: Available Architecture: O2 · Operations Read: 7 min Verified: 2026-11-16

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-Match version 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
Cloudflare D1 production backups

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.

Verified against repository suites
tests/backend/auth.test.tstests/backend/migration.test.tstests/backend/backup.test.tstests/backend/health.test.ts
Markdown specification

Persistence, tenancy & operations