ai-sandbox-cloudflare: upgrade @cloudflare/sandbox to 1.x for container snapshots #1983
Send to my agentOpen
tombeckenham opened this issue ·0 comments
Upgrade @cloudflare/sandbox from ^0.12.1 to 1.x in @tanstack/ai-sandbox-cloudflare and in examples/sandbox-cloudflare. Cloudflare now documents 0.x only "for existing applications".
Why#
Sandbox SDK 1.0 lets your own Durable Object control each container through ctx.container, with the durable_object scheduling policy. That unlocks features that our provider cannot use today:
- Container snapshots.
ctx.container.snapshotContainer()saves the whole container disk.ctx.container.start({ containerSnapshot })restores it. Snapshots live 30 days, and each restore renews them. With this, the provider can setsnapshots: trueand implementhandle.snapshot()andrestoreSnapshot(). Today it declaressnapshots: falseanddurableFilesystem: false. - Directory backups without R2 keys. In 1.0,
DirectoryBackupsends backups through aDirectoryBackupGatewayin the Worker. The container gets no R2 credentials. In 0.12,createBackup()needs R2 API keys as Worker secrets. - Instance size per container.
start({ instance })picks the size at runtime. In 0.12, oneinstance_typeapplies to the whole app.
Context#
- PR #1982 benchmarked the provider for computer use. A
standard-4container took about 180 ms for each command. The disk is wiped on each restart, so a signed-in browser does not survive. Snapshots fix that second part. - PR #1982 also fixed a bug in the provider. 0.12 runs every command in one shared shell, so a command that called
exitended the session. When we migrate, check how 1.0 runs commands, and keep the subshell wrap if it is still needed.
Work#
- Read the migration guide: https://developers.cloudflare.com/sandbox/sdk/migrate/
- Move the provider to 1.0. The 0.12
Sandboxclass is replaced by your own Durable Object class. - Set
snapshots: trueand implement container snapshots. Guide: https://developers.cloudflare.com/containers/guides/snapshots/ - Update
examples/sandbox-cloudflareand itsDockerfilebase tag. - Update
docs/for the provider (setup, thedurable_objectpolicy, snapshots).
References#
- Sandbox SDK 1.0 changelog: https://developers.cloudflare.com/changelog/post/2026-09-30-sandbox-sdk-1-0/
- Container snapshots changelog: https://developers.cloudflare.com/changelog/post/2026-09-30-snapshots/
- Durable Object container API: https://developers.cloudflare.com/containers/api/durable-object-container/
- DirectoryBackup API: https://developers.cloudflare.com/sandbox/reference/directory-backups/
github-actions[bot](GitHub profile, opens in a new tab) assignedjherr
github-actions[bot](GitHub profile, opens in a new tab) added labelswaiting-on: maintainer
Sign in to join this conversation.