Sandbox SDK 0.x API map

Last updated Oct 23, 2026 This page maps each public API of @cloudflare/sandbox 0.12 to its replacement: a 1.0 class, a platform API, another Cloudflare product, or code that you write. Some APIs are no longer needed. For the migration steps, refer to Migrate from Sandbox SDK 0.x.

In the tables, container is this.ctx.container in your Durable Object, and files is a Files instance. The Kind column uses these values:

Kind Meaning
Native Call container or another platform API directly.
Package Use a class from @cloudflare/sandbox 1.0, such as Files.
Pattern Write it yourself. When a page shows how, the note links it.
Product Use another Cloudflare product.
Removed Not needed. The note says what to do instead.

Class, identity, and lifetime

For the steps, refer to Replace the Sandbox class. These APIs create a sandbox and control how long its container runs:

0.12 Kind Replacement Notes
class X extends Sandbox, export { Sandbox } Removed class X extends DurableObject Construct the classes of the package from container.
getSandbox(ns, id, options) Native env.NS.getByName(id) Validate names yourself.
normalizeId, setSandboxName() Removed Lowercase names yourself Needed only when names become hostnames.
sleepAfter, setSleepAfter() Native container.setInactivityTimeout(ms) At most 6 hours. Call it after start(), and again in the constructor.
keepAlive, setKeepAlive() Pattern An alarm that sends the container a request while work remains Refer to Sandbox lifetime.
renewActivityTimeout() Native Any request to the Durable Object The timeout counts from when the Durable Object becomes inactive.
containerTimeouts, setContainerTimeouts() Removed AbortSignal
transport, setTransport(), SANDBOX_TRANSPORT Removed Not needed container.exec() and Files reach the container directly. Remove the setting.
labels, setLabels() Native container.start({ image, enableInternet, labels })
configure() Removed Options on each call
setEnvVars(), class envVars Native container.start({ env }) or container.exec(argv, { env }) exec() does not inherit start() variables, except PATH.
Class entrypoint, enableInternet Native container.start({ entrypoint, enableInternet }) enableInternet defaults to false. It defaulted to true in 0.12.
Class defaultPort, requiredPorts Native container.getTcpPort(port)
start() Native container.start({ image, enableInternet }) Does not wait for the container.
startAndWaitForPorts(), waitForPort() Pattern Retry getTcpPort(port).fetch() Preview a web application shows a readiness check.
stop(), destroy() Native container.signal(), container.destroy()
getState() Native container.running, container.monitor()
getContainerPlacementId() Pattern Read CLOUDFLARE_PLACEMENT_ID from /proc/1/environ with container.exec() The main process of the container has the variable. Commands do not.
onStart, onStop, onError, onActivityExpired Pattern Your code around start() and monitor()
schedule(), listSchedules(), getSchedule(), deleteSchedules(), alarm() Native Durable Object alarms One alarm per object. Store your own schedule if you need several.
fetch(), containerFetch() Native container.getTcpPort(port).fetch()

Commands

For the steps, refer to Change command calls. These APIs run commands:

0.12 Kind Replacement Notes
exec(command, options) Native container.exec(argv, options) output() returns bytes and exitCode. success is exitCode === 0.
stream, onOutput, onComplete, onError Native Read stdout and stderr, and await exitCode
execStream() Native The stdout stream from container.exec(argv) Set Content-Type: text/event-stream on the response. Refer to Stream output.
timeout, signal Native Run the command under timeout, or pass signal from a timer you clear Exit code 124 or 137 means the time passed. Refer to Replace timeouts.
cwd, env Native The same options Pass cwd: "/workspace" and env, which 0.12 set by default.
encoding Removed Decode bytes yourself
isExecResult(), isProcess(), isProcessStatus() Removed Not needed exec() returns an ExecProcess. TypeScript types replace the guards.

Processes

For the steps, refer to Move background processes. Each replacement builds on the process directories from Run background processes. These APIs run and manage background processes:

0.12 Kind Replacement Notes
startProcess() Pattern startProcess(id, argv), which writes the process ID, output, and exit code to files Pass cwd: "/workspace" and env, which 0.12 set. Refer to Add the process methods.
Process.getStatus(), getProcess(), listProcesses() Pattern status(), and a listProcesses() method over the process directories
getProcessLogs(), Process.getLogs() Pattern logs() for each stream
streamProcessLogs() Pattern follow(), which streams tail -F --pid Named stdout, stderr, and exit events, not LogEvent objects.
Process.waitForLog() Pattern waitForLog(), which polls the log files with grep -E Escape 0.12 string patterns. Refer to Wait for output or exit.
Process.waitForExit() Pattern A waitForExit() method that calls status() until the process ends
Process.waitForPort() Pattern Retry getTcpPort(port).fetch() Preview a web application shows a readiness check.
Process.kill(), killProcess() Pattern stop(), which sends SIGTERM to the process group 0.12 sent SIGKILL 5 seconds later.
killAllProcesses() Pattern stop() for each process that listProcesses() returns
cleanupCompletedProcesses(), autoCleanup Removed Not needed Both did nothing in 0.12. Delete ended process directories with rm -rf.
onStart, onOutput, onError Pattern Code after startProcess(), follow(), and a start that throws or returns false
onExit Pattern The alarm that checks each process every minute Refer to Replace callbacks.

Sessions

For the steps, refer to Replace sessions. These APIs keep state between commands:

0.12 Kind Replacement Notes
createSession(), getSession(), deleteSession() Removed cwd and env on each call
enableDefaultSession Removed cwd and env on each call cd and export do not carry over.
isolation Removed Separate sandboxes
commandTimeoutMs Removed timeout in each command

ExecutionSession methods map like the top-level methods.

Files

For the steps, refer to Change file calls. These APIs read and write files:

0.12 Kind Replacement Notes
readFile(), readFileStream() Package files.readFile() Returns a Response. Use .text(), .arrayBuffer(), or the body, which holds file bytes, not server-sent events.
writeFile() Package files.writeFile() Create missing parent directories with mkdir() first. Pass bytes instead of base64.
mkdir() Package files.mkdir()
deleteFile() Package files.remove() Also removes directories with recursive: true.
renameFile(), moveFile() Package files.rename() Fails with EXDEV across filesystems. Does not move a source into an existing directory, as mv did.
listFiles() Package files.readDirectory() One level. Includes hidden entries.
listFiles({ recursive: true }) Pattern Walk readDirectory() Refer to List files.
exists() Package files.stat() Catch SandboxFileError with ENOENT.
File metadata Package files.stat(), files.lstat()
watch(), checkChanges() Pattern inotifywait -m through container.exec() Refer to Replace file watching.
collectFile(), streamFile() Removed The Response body
parseSSEStream(), responseToAsyncIterable(), asyncIterableToSSEStream() Removed The ReadableStream objects on ExecProcess To send output to a browser as server-sent events, refer to Stream command output.
WriteFileResult, ReadFileResult, and other result types Removed void, Response, or SandboxFileStat Failures throw SandboxFileError.

Ports, preview URLs, and tunnels

For the steps, refer to Move preview URLs and Move tunnels. These APIs make a server in the container reachable from outside it:

0.12 Kind Replacement Notes
exposePort(), unexposePort(), getExposedPorts(), isPortExposed() Pattern Methods over the 0.12 portTokens key URLs that 0.12 issued keep working. Refer to Replace the preview calls.
validatePortToken() Pattern A constant-time check of the stored token
proxyToSandbox(), SandboxEnv Pattern Route <port>-<name>-<token> hostnames to getByName()
wsConnect(request, port) Native container.getTcpPort(port).fetch(request) Bridge the WebSocket to keep the container running.
tunnels.get(port), tunnels.list(), tunnels.destroy(port) Pattern openTunnel(), listTunnels(), and closeTunnel(), which run cloudflared Needs enableInternet: true. Refer to Run cloudflared from your Durable Object.
tunnels.get(port, { name }) Pattern resumeTunnel() and deleteTunnel() over the 0.12 tunnels key Hostnames that 0.12 created keep working. Refer to Keep named tunnels that 0.12 created.
CLOUDFLARE_API_TOKEN Pattern The same secret Keep it while you run or delete named tunnels that 0.12 created.
CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_TUNNEL_ACCOUNT_ID, CLOUDFLARE_ZONE_ID Removed Not needed The code reads the account and zone that 0.12 stored.

Terminals

For the steps, refer to Move browser terminals. These APIs connect a browser terminal to a shell:

0.12 Kind Replacement Notes
terminal(), session.terminal() Pattern getByName(name).fetch(request), and a handler that attaches a tmux client with exec(argv, { pty }) Start the shell in /workspace with env, which 0.12 set. Refer to Attach terminals to tmux.
proxyTerminal() Pattern The same fetch() call, with the session in the query string Refer to Forward the WebSocket.
cwd and env of a session that a terminal opens Pattern The -c and -e options of tmux new-session tmux applies them when it creates the session.
shell option Pattern A command after the session name in the tmux command
@cloudflare/sandbox/xterm, SandboxAddon, SandboxAddonOptions, ConnectionState, ConnectionTarget Pattern xterm.js with a WebSocket that the page reopens Send {"type":"ready"} so that pages loaded before the switch keep working. Refer to Replace SandboxAddon.
Terminal reconnect and replay Pattern tmux keeps the session and redraws the screen Earlier output stays in the tmux history. Refer to What changes at the terminal.

Outbound network and Git

For the steps, refer to Move outbound rules. These APIs control the requests that code in the container sends: