Migrate from Sandbox SDK 0.x

To move an application from Sandbox SDK 0.x to 1.0, replace the Sandbox class with a Durable Object class that you write. Then replace each 0.x feature that your application uses. Your class starts a container that uses the Durable Object scheduling policy, which is in public beta. For the reasons behind these changes, refer to Changes in Sandbox SDK 1.0.

Sandboxes on 1.0 start faster. On a prepared image, the median time from start() to the first command is under 600 ms, compared with about 4 s on 0.x. Each start() call also chooses its own image, and a deploy does not restart running sandboxes.

Support for Sandbox SDK 0.x

Sandbox SDK 0.x receives bug and security fixes until 2026-12-31, and no new features. After that date, deployed 0.x applications keep running, and @cloudflare/sandbox 0.x stays on npm.

The migration pages compare 1.0 with 0.12, the last 0.x release. If your application uses an earlier release, upgrade to @cloudflare/sandbox 0.12.10 and the docker.io/cloudflare/sandbox:0.12.10 image first.

Plan for a one-way switch

You can move every sandbox in one deploy, or run a 1.0 class next to the 0.x class and move sandboxes one at a time. Rehearse either way on a staging Worker first. To choose a way and prepare for the deploy, refer to Plan the move to Sandbox SDK 1.0.

Find the pages your application needs

Every application needs the first two pages in the following table. To find the others, search your source directory for 0.x calls:

grep -rhow \
	-e getSandbox -e sleepAfter -e keepAlive \
	-e envVars -e onStart -e onStop \
	-e onActivityExpired -e createSession \
	-e readFile -e writeFile -e listFiles -e watch \
	-e startProcess -e streamProcessLogs \
	-e exposePort -e proxyToSandbox -e wsConnect \
	-e tunnels -e terminal -e SandboxAddon \
	-e outboundByHost -e setOutboundHandler \
	-e allowedHosts -e deniedHosts -e gitCheckout \
	-e enableInternet -e interceptHttps \
	-e mountBucket -e createBackup -e restoreBackup \
	-e runCode -e createCodeContext \
	-e sandbox/opencode -e sandbox/openai \
	-e sandbox/bridge -e WarmPool \
	src | sort | uniq -c

The command prints each name it finds and how often it appears. Some names, such as watch and terminal, can also match code that does not use the SDK. The 0.12 codex-app-server template prints:

      1 enableInternet
      6 getSandbox
      1 gitCheckout
      2 interceptHttps
      1 outboundByHost
      2 proxyToSandbox
      1 readFile
      2 sleepAfter
      1 startProcess
      1 writeFile

Each name leads to one page:

0.x code	Page	Work in 1.0
`Sandbox`, `getSandbox()`, `sleepAfter`, `keepAlive`, `envVars`, `onStart()`, `onStop()`, `onActivityExpired()`	Replace the Sandbox class	Write the class
`exec()`, `execStream()`, `createSession()`	Change command calls	Change calls
`readFile()`, `writeFile()`, `listFiles()`, `watch()`	Change file calls	Change calls
`startProcess()`, `streamProcessLogs()`	Move background processes	Add code
`exposePort()`, `proxyToSandbox()`, `wsConnect()`	Move preview URLs	Add code
`tunnels`	Move tunnels	Add code
`terminal()`, `SandboxAddon`	Move browser terminals	Add code
`outboundByHost`, `setOutboundHandler()`, `allowedHosts`, `deniedHosts`, `enableInternet`, `interceptHttps`, `gitCheckout()`	Move outbound rules	Add code
`mountBucket()`	Move bucket mounts	Change calls
`createBackup()`, `restoreBackup()`	Move backups	Add code
`runCode()`, `createCodeContext()`	Replace the code interpreter	Add code
`sandbox/opencode`, `sandbox/openai`, `sandbox/bridge`, `WarmPool`	Move other 0.x features	Add or remove code
`FROM docker:dind-rootless` in a `Dockerfile`	Run Docker inside the sandbox	Change the image

Work through the pages on your staging Worker, test it with your own checks, and then deploy to production. For every 0.x API and its replacement, including features with no equivalent in 1.0, refer to the API map.

Stay on 0.x until you move

Until you move, pin @cloudflare/sandbox to 0.12.10 and your image to docker.io/cloudflare/sandbox:0.12.10. The deprecation changelog entry lists 0.x features to avoid in new work: the HTTP and WebSocket transports, exposePort(), default sessions, and separate streaming methods.