Persistent workspace policy — Phase 1 (capture on eviction)
On this page
Date: 2026-10-31
Status: Implemented, flag-gated off (runtime prerequisite below)
Parent: docs/plans/persistent-workspace-phase0.md (measurement)
1. Scope
Phase 1 adds Tier 1 capture: immediately before an idle container is evicted, take a platform filesystem snapshot and commit its handle. Boot still uses the archive, so this cannot reduce recoverability — it only starts producing the artifact that Phase 2 will boot from.
Explicitly out of scope:
- Booting from the snapshot (Phase 2). The recovery ladder is unchanged.
- Retention/GC beyond overwriting the single head handle.
- Any change to the archive cadence, lease, or restore path.
- An encryption envelope for the snapshot (platform-managed storage; the F4E1 archive remains the compliance artifact — see the Phase 0 design, decision 01).
2. Runtime prerequisite (hard)
Cloudflare only supports snapshots for a container application that uses
scheduling_policy: "durable_object". The tenant container
(containers[].class_name: "Sandbox" in wrangler.jsonc) uses the default
policy: the legacy SDK calls container.start(startConfig) with no image,
which is exactly what the default policy provides and the DO policy forbids.
A policy flip is not available. Verified against Cloudflare’s docs (2026-10-31):
- The scheduling policy is immutable: “To use a different policy, create a new Container application.” The replacement also needs a new Durable Object class and namespace; the old and new applications cannot attach to the same namespace, and the existing entry must stay untouched so traffic can be routed back.
- The legacy
Sandboxclass extends the ContainersContainerclass, which does not support thedurable_objectpolicy. The replacement class must drivectx.containerdirectly and rebuild the helpers the tenant runtime relies on (exec/processes, port readiness, HTTP/WS proxying, sleep timeout). instance_type: "basic"has no equivalent:instanceacceptsliteorstandard-1..4, and custom instance types require at least 1 vCPU, sobasic’s 1/4 vCPU cannot be expressed. A replacement must chooselite(smaller) orstandard-1(4 GiB) — a per-tenant cost/behaviour decision.- Named images must be a Dockerfile or a digest-pinned Cloudflare-registry
reference;
max_instances, placement constraints and application-wide image rollouts are unsupported. Deploys stop rolling the image; application code stops and starts each container.
Consequences:
- There is no snapshot-only migration. Tier 1 needs the Sandbox 1.0 workload
adapter (exec/processes, files, HTTP/WS, readiness/recovery) plus the
.sqsh→DirectoryBackupbridge — the S2–S4 slices of #380. SandboxV1already provides the new class, thedurable_objectapp,DirectoryBackup+ F4E1 andsnapshotWorkspace(); it has nofetch(), exec/files/process surface and no routing.- On today’s tenant runtime
ctx.container.snapshotContainer()is unavailable. Capture is classifiedunsupported, logged, and eviction continues to the archive/stop path.WORKSPACE_SNAPSHOTstaysfalsein every environment.
3. What ships
| Piece | Location | Behaviour |
|---|---|---|
| Handle record + catalog | src/workspace-snapshot.ts | workspace/snapshot.json in BACKUP_BUCKET; versioned, image-pinned, parsed defensively |
| Capture | captureWorkspaceSnapshot() | never throws; captured / unsupported / failed / skipped |
| Eviction hook | TenantSandbox.onActivityExpired() | runs after the idle verdict, before the archive/stop branch, only when WORKSPACE_SNAPSHOT=true |
| Legacy capability | TenantSandbox.snapshotWorkspace() | ctx.container.snapshotContainer({ name: 'workspace' }) |
| 1.0 capability | SandboxV1.snapshotWorkspace() | same, on a durable_object container |
| Telemetry | workspace-snapshot | durationMs, bytes, trigger=evict, outcome, classified detail |
Handle shape
{
"format": 1,
"id": "<platform snapshot id>",
"size": 123456789,
"image": "<image the container ran>",
"committedAt": 1761900000000,
"trigger": "evict"
}
- One live handle. Snapshots cannot be deleted through the API, so the only retention lever is creation rate; the head is overwritten and unreferenced handles expire after the platform’s 30-day TTL.
- Image-pinned.
isWorkspaceSnapshotUsable(record, currentImage)is false for an empty or mismatched image, so Phase 2 falls back to the archive rather than restoring an incompatible filesystem.
4. Rollout
Tier 1 is only reachable through the v1 cutover, so the rollout follows #380’s slices rather than a policy flip:
- S2 — v1 workload adapter + serving foundation (
convertToV1, HTTP, readiness, recovery) for an explicitly opted-in, non-production instance. - S3 — WebSocket + forwarded-header parity.
- S4 — v1 owner operations: freeze, backup/checkpoint, restore-settled
latch, and the
.sqsh→DirectoryBackupconversion (existing tenants keep their recovery points). - Enable
WORKSPACE_SNAPSHOT=trueon that instance and verifyworkspace-snapshotrows:outcome=captured,bytes > 0, zerounsupportedfor a full idle cycle. - Only then widen to staging tenants, dev, and production.
None of this is a prerequisite for merging Phase 1: the capture code is inert while the flag is off, and the flag is off everywhere.
Gate (from the Phase 0 plan)
Every eviction produces a handle: captured for 100% of idle evictions over a
week, with unsupported/failed at zero. Only then does Phase 2 (boot from the
snapshot when the image matches) start.
5. Failure behaviour
- Flag off → no call, no row.
- No
BACKUP_BUCKET→skipped(no-bucket). - Runtime rejects the API →
unsupported, warning, eviction continues. - Capture or catalog write fails →
failed, warning, eviction continues. - The archive/stop path is unchanged in every case, so Phase 1 has no fail-closed obligation: the recovery point is still the archive.
5b. Snapshot and archive must restore the same tree
The two tiers are only interchangeable if they hold the same content. The
archive is a complete image today: SNAPSHOT_EXCLUDES (.npm, *.log,
*.tmp, .cache, workspace/*node_modules*) is gated behind
BACKUP_ARCHIVE_EXCLUDES, which is off by default precisely so an
archive restore cannot diverge from a snapshot restore.
Phase 2 must not weaken that. If an instance opts into the excludes, an archive-restored tenant is missing those paths while a snapshot-restored one has them, so the fallback in the boot ladder is not byte-equivalent and a tenant that depends on the excluded paths would behave differently after a snapshot miss. Before booting from snapshots anywhere the excludes are enabled, either keep the archive complete for that instance or make the fallback regenerate the excluded paths explicitly.
6. Tests
src/workspace-snapshot.test.ts— flag parsing, record parsing, catalog round-trip, image validity, error classification, every capture outcome.src/sandbox-do.test.ts— capture before eviction, flag off,unsupportedstill enqueues the archive-then-stop job, failure does not block eviction.src/sandbox-v1.test.ts—snapshotWorkspace()on adurable_objectcontainer.src/metrics.test.ts—workspace-snapshotrow layout.- Corpus:
test/business-rules/cost-tracking.txt.