Sandbox

Sandboxes on Cloudflare
import {
CardGrid,
Description,
LinkTitleCard,
Plan,
RelatedProduct,
LinkButton,
} from "~/components";
Start a sandbox and run untrusted or generated code
A sandbox is an isolated place to run code. The code cannot directly read the memory or data of your application. Your Worker decides which application APIs and data the code receives, and whether the code can reach the public Internet.
You can use a sandbox for agent-written code, user-uploaded applications, data analysis, development previews, build pipelines, or any other work that should not share a process with your application.
Cloudflare provides two sandbox environments. Both are accessible through a Worker, the application that already handles your traffic.
If your application uses 
@cloudflare/sandbox 0.x, refer to Sandbox SDK 0.x, or move it to the current version with Migrate from Sandbox SDK 0.x.
Containers
Containers run an image you provide. The instance is a full Linux environment, so you can run any language and keep processes running. Your Worker starts the instance and sends it work. HTTP from the Internet reaches the instance only through your Worker.
Each instance is a microVM with its own kernel and network, so no other workload shares it.
A sandbox container uses the Durable Object scheduling policy, which is in public beta.
A Durable Object in your Worker starts the instance from an image and runs a command in it:
container.start({
	image: "cloudflare/debian-trixie",
	entrypoint: ["sleep", "infinity"],
	enableInternet: false,
});
const process = await container.exec(["uname", "-a"]);
const output = await process.output();
	Run a Linux command
	Build a coding agent runner
Dynamic Workers
Dynamic Workers create a new Worker at runtime. The untrusted code can be JavaScript, Python, or WebAssembly. Compile TypeScript to JavaScript before loading it.
The Workers runtime runs each Dynamic Worker apart from your Worker and from other Dynamic Workers. A Dynamic Worker reaches your application only through the methods and data you pass to it.
Your Worker loads the untrusted module as a new Worker, blocks its outbound requests, and calls it:
const sandbox = env.LOADER.load({
	compatibilityDate: "$today",
	mainModule: "code.js",
	modules: { "code.js": untrustedModule },
	globalOutbound: null,
});
const entrypoint = sandbox.getEntrypoint<CodeEntrypoint>("Code");
const result = await entrypoint.evaluate();
	Run JavaScript
	Build an AI code interpreter
Concepts
<LinkTitleCard
title="Choose a sandbox environment"
href="/sandbox/concepts/"
icon="seti:info"
Decide whether a job needs Linux or only calls methods that your Worker
provides.
<LinkTitleCard
title="Sandbox lifetime"
href="/sandbox/concepts/lifetime/"
icon="database"
Understand what keeps a Linux sandbox running, what stops it, and which files
a snapshot brings back.
<LinkTitleCard
title="Sandbox security"
href="/sandbox/concepts/security/"
icon="ph:shield-check"
Decide what each sandbox holds, because its code can use everything you place
inside it.
Guides
	Run Python code and tests, stream output, keep processes running, and open a
	terminal.
	Move files, keep a workspace between instances, and mount an R2 bucket.
<LinkTitleCard
title="Preview applications"
href="/sandbox/previews/"
icon="external"
From your browser, open a web server that runs in a sandbox.
<LinkTitleCard
title="Credentials and network"
href="/sandbox/network/"
icon="seti:lock"
Keep credentials in your Worker, and decide which services a sandbox reaches.
<LinkTitleCard
title="Manage sandboxes"
href="/sandbox/manage/"
icon="list-format"
List a user's sandboxes, and record when and why each one stops.
<LinkTitleCard
title="Coding agents"
href="/sandbox/coding-agents/"
icon="laptop"
Run coding agents such as Claude Code, Codex, and Devin in a sandbox that
belongs to one task.
Related products
The serverless platform these sandbox environments run on.
Identity and coordination for an attached container.
Run models on Cloudflare, then execute the code they generate in a sandbox.
More resources
Topic
Links
Deploy and debug
Deploy Containers, Local development, Logs
Reference
@cloudflare/sandbox, Durable Object container API, Dynamic Workers API
Pricing and limits
Containers pricing, Container limits, Dynamic Workers pricing
Related
Code Mode, Workers security model

Run Claude Code in a sandbox
import { PackageManagers, Steps, WranglerConfig } from "~/components";
Run Claude Code in a Linux sandbox to edit a GitHub repository from a prompt, then read its changes as a diff. Claude Code calls Anthropic models through AI Gateway. Your Worker adds the gateway token to those requests, and the sandbox can reach only your gateway and 
github.com.
Prerequisites
The 
sandbox-coding-agent project from Build a coding agent runner. The tutorial builds the runner with Claude Code. Use this page to switch back to Claude Code after you run another agent, or to change its settings.
Anthropic credentials in AI Gateway, either Unified Billing credits or an Anthropic API key stored as a provider key.
Switch the Worker to Claude Code
Replace the 
Dockerfile:
FROM node:24-trixie-slim
RUN apt-get update \
	&& apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
	&& rm -rf /var/lib/apt/lists/*
RUN npm install --global @anthropic-ai/claude-code@2.1.308
COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim
WORKDIR /workspace
CMD ["sleep", "infinity"]
The install script from the Claude Code package puts its native binary in place. The image pins the version, because the flags and event format of Claude Code can change between releases.
In 
wrangler.jsonc, set 
MODEL to an Anthropic model ID that your gateway can serve:
{
	"vars": {
		"AI_GATEWAY_ACCOUNT_ID": "<ACCOUNT_ID>",
		"AI_GATEWAY_ID": "default",
		"MODEL": "claude-sonnet-5",
	},
}
In 
src/outbound.ts, make sure the 
Outbound entrypoint removes the 
x-api-key header before it adds the gateway token:
const headers = new Headers(request.headers);
headers.delete("x-api-key");
headers.set("cf-aig-authorization", `Bearer ${this.env.AI_GATEWAY_TOKEN}`);
Claude Code sends a placeholder API key. If the 
x-api-key header stays, AI Gateway forwards it to Anthropic, and the model request fails with 
Invalid API key.
In 
src/sandbox.ts, replace the 
ResultEvent constant with a schema for the final event from Claude Code:
const ResultEvent = z.object({
	type: z.literal("result"),
	subtype: z.string(),
	is_error: z.boolean(),
	result: z.string().optional(),
});
Replace the 
agentCommand() and 
agentEnv() methods:
	private agentCommand(prompt: string): string[] {
		return [
			"claude",
			"--print",
			"--output-format",
			"stream-json",
			"--verbose",
			"--dangerously-skip-permissions",
			"--no-session-persistence",
			"--model",
			this.env.MODEL,
			"--",
			prompt,
		];
	}
	private agentEnv(): Record<string, string> {
		return {
			ANTHROPIC_BASE_URL: `https://gateway.ai.cloudflare.com/v1/${this.env.AI_GATEWAY_ACCOUNT_ID}/${this.env.AI_GATEWAY_ID}/anthropic`,
			ANTHROPIC_API_KEY: "provided-by-worker",
			CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1",
			IS_SANDBOX: "1",
		};
	}
--print runs Claude Code without an interactive terminal.
--output-format stream-json --verbose writes one JSON event per line, including a final 
result event.
--dangerously-skip-permissions lets Claude Code run commands and edit files without asking. The container limits what its commands can reach. Claude Code requires 
IS_SANDBOX=1 to allow this as 
root.
ANTHROPIC_BASE_URL sends model requests to the Anthropic endpoint of your gateway.
ANTHROPIC_API_KEY is a placeholder, because Claude Code does not start without an API key.
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC turns off update checks, telemetry, and error reporting, so Claude Code calls only your gateway.
If the repository has a 
CLAUDE.md file, Claude Code reads it, so the instructions in that file apply to the task.
Replace the 
outcome() method:
export class AgentSandbox extends DurableObject<Env> {
	// ...
	private async outcome(exitCode: number): Promise<TaskStatus> {
		let result: z.infer<typeof ResultEvent> | undefined;
		const events = await this.files.readFile(eventsPath);
		for await (const line of readLines(events.body)) {
			const parsed = ResultEvent.safeParse(parseJson(line));
			if (parsed.success) {
				result = parsed.data;
			}
		}
		if (result === undefined) {
			const stderr = (await this.readOptionalText(stderrPath)) ?? "";
			return {
				state: "failed",
				error: `claude exited with ${exitCode}: ${stderr.slice(-2000)}`,
			};
		}
		if (result.is_error) {
			return { state: "failed", error: result.result ?? result.subtype };
		}
		return { state: "succeeded", result: result.result ?? "" };
	}
}
Claude Code exits successfully even when a model request fails, so the outcome comes from the 
is_error field of the final 
result event instead of the exit code. Claude Code retries a failing model request 10 times. A rejected gateway token fails the task after about three minutes with 
Failed to authenticate. API Error: 401 Unauthorized.
Deploy your Worker:
A running container keeps the image it started with, so use a new sandbox name for Claude Code.
Run a task
Clone a repository into a sandbox named 
claude-1:
curl "$WORKER_URL/sandboxes/claude-1/repository" \
	--json '{"url": "https://github.com/octocat/Hello-World"}'
Start a task:
curl "$WORKER_URL/sandboxes/claude-1/task" \
	--data "Add a file NOTES.md with a one-sentence summary of this repository. Do not commit."
Check the task until its state is 
succeeded or 
failed:
curl "$WORKER_URL/sandboxes/claude-1/task"
A 
succeeded task includes the final reply from Claude Code.
Read the changes:
curl "$WORKER_URL/sandboxes/claude-1/diff"
The diff shows the new 
NOTES.md file.
Related resources
Build a coding agent runner: how the runner starts the sandbox, runs the task, and reads the diff.
Claude Code example: a separate deployable Worker that runs Claude Code.
Claude Code in AI Gateway: route Claude Code through AI Gateway from other environments.

Run Claude Managed Agents in a sandbox
import { LinkButton } from "~/components";
Claude Managed Agents runs its agent loop on the Anthropic platform. A self-managed environment runs the actions of the agent in your Cloudflare account instead. Cloudflare publishes an open-source template for that environment. Fork it, deploy it to your account, and change it as you need.
	Get the template
:::caution
The template is alpha software. It is not yet stable and may contain bugs.
:::
How it works
When an agent session starts or ends, Anthropic sends a webhook to a Worker that the template deploys in your account. The Worker gives each session its own sandbox, applies an egress policy to its outbound traffic, saves the sandbox state while the session sleeps, and shuts the sandbox down when the session ends.
Each agent runs in one of two sandbox types:
A Linux sandbox on Containers gives the agent a shell and any process it needs to run. The template builds these sandboxes with Sandbox SDK 0.x.
A Dynamic Worker starts in milliseconds and costs less than a container session, but runs code in the Workers runtime without a Linux shell or processes.
For more information about the trade-offs, refer to Choose a sandbox environment.
What the template adds
The template also gives agents access to other Cloudflare products:
Agents reach private services over Workers VPC and Cloudflare Mesh without exposing those services to the Internet.
Outbound traffic passes through proxies that you configure. A proxy can add credentials to requests without the agent seeing them, restrict the domains an agent can reach, or run your own code on each request.
Each session can have its own email address for sending and receiving messages with Email Service.
Agents can use headless browsers from Browser Run to fetch pages, take screenshots, and control a browser over the Chrome DevTools Protocol.
Agents can generate images with Workers AI.
You add a tool by adding a function to one file. Tools run in the Worker with access to all of its bindings.
A dashboard lists agents and sessions, shows logs, and opens a shell in a running Linux sandbox.
When to use it
Use a self-managed Cloudflare environment when you need:
Control over the sandbox infrastructure your agents run in
Secure connections to private internal services
Custom egress policies for credential injection and domain restrictions
Custom tools that use Cloudflare bindings, such as R2, D1, KV, and Vectorize
A choice between Linux sandboxes and Dynamic Workers for each agent
Deploy the template
Follow the onboarding guide in the repository. It covers the Anthropic environment and webhook, secrets, D1 migrations, R2 credentials for snapshots, and dashboard security. Deploy with the Deploy to Cloudflare button, which builds the template in Workers Builds, or run 
npm run deploy from your terminal.
:::note
You need a Workers Paid plan or an Enterprise account. The template runs Linux sandboxes on Containers, and runs Dynamic Workers and egress proxies through Worker Loader bindings.
:::
Template documentation
The repository documents each capability:
Topic
What it covers
Connecting to private services
Reach services in other clouds, on-premises, or on your laptop with Workers VPC bindings
Applying egress policies
Allow and deny lists, header injection, custom Worker proxies, and VPC routing
Choosing a sandbox type
When to run an agent in a Dynamic Worker or a Linux sandbox
Agent email
Email addresses and sending for agents
Browser tools
Browser Run tools for agents
Adding custom tools
Declaring new tools in 
src/tools/custom-tools.ts
Customizing sandboxes
The 
Dockerfile and 
instance_type of Linux sandboxes
Snapshots and state persistence
How both sandbox types keep their state while a session sleeps
Architecture
The request path from webhook to sandbox, and every binding the Worker uses
Securing access
Securing the dashboard and API

Run Codex in a sandbox
import { PackageManagers, Steps, WranglerConfig } from "~/components";
Run the Codex CLI in a Linux sandbox to edit a GitHub repository from a prompt, then read its changes as a diff. Codex calls OpenAI models through AI Gateway. Your Worker adds the gateway token to those requests, and the sandbox can reach only your gateway and 
github.com.
Prerequisites
The 
sandbox-coding-agent project from Build a coding agent runner. This page replaces the image, the model, and the parts of the Durable Object that are specific to the agent.
OpenAI credentials in AI Gateway, either Unified Billing credits or an OpenAI API key stored as a provider key.
Switch the Worker to Codex
Replace the 
Dockerfile. Only the highlighted line differs from the 
Dockerfile in the tutorial:
FROM node:24-trixie-slim
RUN apt-get update \
	&& apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
	&& rm -rf /var/lib/apt/lists/*
RUN npm install --global --ignore-scripts @openai/codex@0.156.1
COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim
WORKDIR /workspace
CMD ["sleep", "infinity"]
The Codex npm package ships its native binaries as dependencies, so it installs without running install scripts. The image pins the version, because the flags and event format of Codex can change between releases.
In 
wrangler.jsonc, set 
MODEL to an OpenAI model ID that your gateway can serve:
{
	"vars": {
		"AI_GATEWAY_ACCOUNT_ID": "<ACCOUNT_ID>",
		"AI_GATEWAY_ID": "default",
		"MODEL": "gpt-6-sol",
	},
}
Codex sends requests in the OpenAI Responses format, so it works only with OpenAI models that support the Responses API.
In 
src/sandbox.ts, replace the 
ResultEvent constant with a path for the final message from Codex and a schema for its failure events:
const lastMessagePath = `${taskDirectory}/last-message.txt`;
const FailureEvent = z.union([
	z.object({
		type: z.literal("turn.failed"),
		error: z.object({ message: z.string() }),
	}),
	z.object({ type: z.literal("error"), message: z.string() }),
]);
Replace the 
agentCommand() and 
agentEnv() methods:
export class AgentSandbox extends DurableObject<Env> {
	// ...
	private agentCommand(prompt: string): string[] {
		const baseUrl = `https://gateway.ai.cloudflare.com/v1/${this.env.AI_GATEWAY_ACCOUNT_ID}/${this.env.AI_GATEWAY_ID}/openai`;
		return [
			"codex",
			// Run one task without an interactive terminal
			"exec",
			// Write one JSON event per line to the events file
			"--json",
			// Skip the session files that Codex would otherwise save
			"--ephemeral",
			"--dangerously-bypass-approvals-and-sandbox",
			// Write the final message to a file outside the repository
			"--output-last-message",
			lastMessagePath,
			"--model",
			this.env.MODEL,
			// Add a custom provider that sends requests to the OpenAI endpoint of your gateway
			"--config",
			'model_provider="cloudflare-ai-gateway"',
			"--config",
			`model_providers.cloudflare-ai-gateway={ name = "Cloudflare AI Gateway", base_url = ${JSON.stringify(baseUrl)}, wire_api = "responses" }`,
			// Stop the analytics and update requests from Codex
			"--config",
			"analytics.enabled=false",
			"--config",
			"check_for_update_on_startup=false",
			// Stop Codex from syncing its plugin marketplace, which clones a
			// repository from `github.com` on every run
			"--config",
			"features.plugins=false",
			"--",
			prompt,
		];
	}
	private agentEnv(): Record<string, string> {
		return {};
	}
}
--dangerously-bypass-approvals-and-sandbox turns off the approval prompts and the built-in command sandbox of Codex. The container limits what commands from Codex can reach instead.
A custom provider sends no API key, and the 
Outbound entrypoint adds the gateway token.
Codex reads the certificate for intercepted HTTPS from 
SSL_CERT_FILE, which 
trustEnv in the runner sets.
Replace the 
outcome() method:
export class AgentSandbox extends DurableObject<Env> {
	// ...
	private async outcome(exitCode: number): Promise<TaskStatus> {
		if (exitCode === 0) {
			return {
				state: "succeeded",
				result: (await this.readOptionalText(lastMessagePath)) ?? "",
			};
		}
		let failure: string | undefined;
		const events = await this.files.readFile(eventsPath);
		for await (const line of readLines(events.body)) {
			const parsed = FailureEvent.safeParse(parseJson(line));
			if (parsed.success) {
				failure =
					parsed.data.type === "error"
						? parsed.data.message
						: parsed.data.error.message;
			}
		}
		if (failure === undefined) {
			const stderr = (await this.readOptionalText(stderrPath)) ?? "";
			return {
				state: "failed",
				error: `codex exited with ${exitCode}: ${stderr.slice(-2000)}`,
			};
		}
		return { state: "failed", error: failure };
	}
}
Codex exits with a nonzero code when its turn fails, so the exit code decides the outcome. A failed task returns the message from the last 
turn.failed or 
error event. Codex retries a failing model request five times, and the task fails after about 20 seconds.
Deploy your Worker:
The 
AI_GATEWAY_TOKEN secret from the tutorial stays in place. A running container keeps the image it started with, so use a new sandbox name for Codex.
Run a task
Clone a repository into a sandbox named 
codex-1:
curl "$WORKER_URL/sandboxes/codex-1/repository" \
	--json '{"url": "https://github.com/octocat/Hello-World"}'
Start a task:
curl "$WORKER_URL/sandboxes/codex-1/task" \
	--data "Add a file NOTES.md with a one-sentence summary of this repository. Do not commit."
Check the task until its state is 
succeeded or 
failed:
curl "$WORKER_URL/sandboxes/codex-1/task"
A 
succeeded task includes the final message that Codex wrote.
Read the changes:
curl "$WORKER_URL/sandboxes/codex-1/diff"
The diff shows the new 
NOTES.md file.
Related resources
Build a coding agent runner: how the runner starts the sandbox, runs the task, and reads the diff.
Codex example: a separate deployable Worker that runs Codex.
OpenAI Codex in AI Gateway: route Codex through AI Gateway from your own terminal.

Run Cursor Cloud Agents in a sandbox
import { Steps } from "
/components";
import { VendorAgentConnections } from "/components/react/sandbox/VendorAgentConnections";
Run Cursor Cloud Agents on Cloudflare through self-hosted machines. Each Cursor session assigned to the deployment runs in its own Linux sandbox: a Container that one Durable Object starts for that session.
Cursor hosts the agent loop, inference, and planning. Cloudflare runs commands, file edits, repository operations, and other tools inside infrastructure that you control.
Prerequisites
You need:
A Cursor Enterprise plan with self-hosted machines turned on
A Cursor team service-account API key with agent scope
A Cloudflare Workers Paid account with access to Containers and R2
Node.js 20 or later
A running Docker daemon for deployment and local development
Configure a Cursor team pool
To create a team pool, set 
CURSOR_API_KEY in your shell. Then, start a local worker with the Cursor Agent CLI:
CURSOR_API_KEY="$CURSOR_API_KEY" agent worker --pool cloudflare-test start
The command registers the pool and temporarily connects your local machine as a worker. After the pool appears in Cursor, stop the worker with 
Ctrl+C and run 
unset CURSOR_API_KEY. Record the pool name for 
CURSOR_POOL. Keep the local worker stopped while testing the Cloudflare deployment so it does not claim the agent request.
For more information, refer to Cursor team pools.
Deploy the template
The template deploys a Worker, a Durable Object namespace, a container application, an R2 bucket binding, and a cron trigger.
1. Clone the template and install its dependencies:
git clone https://github.com/anysphere/cloudflare-workers.git
cd cloudflare-workers
npm install
Log in to your Cloudflare account:
npx wrangler login
Create the R2 bucket for optional repository snapshots:
npx wrangler r2 bucket create cursor-pool-worker-snapshots
To use another bucket name, update 
bucket_name in 
wrangler.jsonc.
Store the required Cursor service-account key as a Worker secret:
npx wrangler secret put CURSOR_API_KEY
Enter a team service-account key with agent scope. Personal API keys do not work with pool workers.
To access private repositories, store your Git credentials as Worker secrets:
npx wrangler secret put GIT_USERNAME
npx wrangler secret put GIT_TOKEN
For GitHub, set 
GIT_USERNAME to 
x-access-token. Set 
GIT_TOKEN to a token with access to the repositories that the agents use.
In 
wrangler.jsonc, set 
vars.CURSOR_POOL to the Cursor team pool name:
{
  "vars": {
    "CURSOR_POOL": "default"
  }
}
Set 
containers[].max_instances to the maximum number of concurrent sessions that the deployment must support.
Deploy the Worker and container:
npx wrangler deploy
Wrangler builds the image and deploys the Worker, Durable Object, container application, and cron trigger.
A new container image rollout stops running containers. Wait for active Cursor sessions to finish before you deploy an update.
Run a repository-bound agent
Repository-bound agents route work by Git remote and by team pool name.
1. Go to [Cursor Cloud Agents](https://cursor.com/agents).
Start an agent and select a repository.
Select Self-hosted, then select the name configured in 
CURSOR_POOL.
Wait for Cursor to assign the session to the deployment. The Worker then starts a container for the session. The initial scheduled controller run can take up to five minutes to begin.
The request provides the repository URL. The container restores or clones that repository into 
$HOME/workspaces/repo-0. It then starts the Cursor worker:
agent worker --worker-dir "$HOME/workspaces/repo-0" --pool "$CURSOR_POOL" start --verbose
The Cursor worker derives its repository label from the Git remote. Do not configure 
repo= labels manually.
Run an any-repository agent
Any-repository agents route work by team pool name. They start with an empty working directory and no Git remote.
1. Go to [Cursor Cloud Agents](https://cursor.com/agents).
Start an agent and select the Any repo group.
Select the team pool name configured in 
CURSOR_POOL.
The container creates 
$HOME/workspaces/repo-0 without a Git remote. The agent or a project hook can clone a repository during the session.
Configure repository snapshots
Repository snapshots are an optional cache for repository-bound agents. A snapshot stores the post-clone working tree in R2. An any-repository agent does not use this cache.
1. Store a secret that protects the snapshot routes:
npx wrangler secret put SNAPSHOT_AUTH_TOKEN
In 
wrangler.jsonc, set 
vars.WORKER_PUBLIC_URL to the deployed Worker URL:
{
  "vars": {
    "CURSOR_POOL": "default",
    "WORKER_PUBLIC_URL": "https://cursor-pool-workers.<ACCOUNT_SUBDOMAIN>.workers.dev"
  }
}
Deploy the updated configuration:
npx wrangler deploy
A cache miss performs a normal Git clone. It does not prevent the agent from starting.
How the template works
The template manages one container for each assigned Cursor session.
Your Worker connects to Cursor on a cron trigger and claims sessions. It sends each session to its own Durable Object, which starts and stops a container. The Cursor worker in the container connects to Cursor and runs the session. Every connection to Cursor starts on Cloudflare, so nothing connects in.
A cron trigger runs the Worker every five minutes. Each run lists the sessions that wait for 
CURSOR_POOL. The run then keeps the server-sent events stream from Cursor open until shortly before the next run, so the Worker also receives sessions that arrive between runs.
The Worker claims each session with a unique worker ID. Cursor then assigns the session only to that Worker. A Durable Object for the session starts one container with the session environment and repository information.
The container stops after five minutes without work, or after 
WORKER_IDLE_RELEASE_TIMEOUT_SECONDS if you set that variable. The Durable Object also stops the container after eight hours, or after 
MAX_RUN_LIFETIME_SECONDS if you set that variable.
The container connects out to Cursor, so it needs no inbound port or public IP address. The Worker exposes only its health route and the optional snapshot routes.
Security
Each session runs in its own container and does not share files or processes with other sessions. The container receives the 
CURSOR_API_KEY service-account key. It also receives 
GIT_USERNAME, 
GIT_TOKEN, and 
SNAPSHOT_AUTH_TOKEN if you set them. Code that runs in a session can read these values. Give 
GIT_TOKEN access only to the repositories that the agents use.
For more information, refer to Sandbox security.
Monitor the deployment
To stream controller and container logs, run:
npx wrangler tail
To list container instances, find the ID of the container application, then list its instances:
npx wrangler containers list
npx wrangler containers instances <APPLICATION_ID>
To test one scheduled controller run during local development, start 
wrangler with scheduled-event testing:
npx wrangler dev --test-scheduled
In another terminal, invoke the scheduled route:
curl "http://localhost:8787/cdn-cgi/local/scheduled?cron=*/5+*+*+*+*"
If you change the cron interval, update both 
triggers.crons in 
wrangler.jsonc and 
CONTROLLER_RUN_BUDGET_MS in 
src/config.ts.
Troubleshooting
Symptom
Cause
Resolution
No sessions are assigned
The cron does not run, the key is missing, or the team pool name does not match
Run 
npx wrangler tail. Check controller runs, 
401 responses, and the configured team pool name.
The controller returns 
401
The key is personal or lacks agent scope
Replace 
CURSOR_API_KEY with a team service-account key that has agent scope.
The team pool is absent for a repo
The worker started without repository labels
Select Any repo, or start a repository-bound agent with a configured Git remote.
The session is assigned but does not start
The container cannot start, clone the repository, or authenticate
Run 
npx wrangler containers list and inspect 
npx wrangler tail. Check capacity and Git secrets.
The container exits with 
Error: Container exited with unexpected exit code: 1 and an earlier log reports 
cursor-agent CLI not found on PATH
Cloudflare WARP or another TLS-inspecting proxy may have prevented Docker from downloading the Cursor CLI. An unguarded shell pipeline can hide the installation failure and produce an incomplete image.
Run 
npx wrangler tail and inspect the preceding container logs. If the Cursor CLI is missing, disconnect WARP, clear the Docker build cache, and run 
npx wrangler deploy again. Or configure Docker to trust the root certificate of your organization.
The first repository start is slow
The snapshot cache is empty or not configured
Configure both 
WORKER_PUBLIC_URL and 
SNAPSHOT_AUTH_TOKEN, or allow a cold Git clone.
Related resources
Cursor Cloudflare Workers template
Cursor self-hosted machines overview
Cursor team pools
Cloudflare Containers
R2

Run Devin in a sandbox
import { PackageManagers, Steps } from "
/components";
import { VendorAgentConnections } from "/components/react/sandbox/VendorAgentConnections";
Devin runs its agent loop in its own service. Each session works on a machine where Devin runs commands, edits files, and opens a browser. A Devin Outpost moves that machine to infrastructure that you choose. The Devin Outpost template runs each session in its own Linux sandbox: a Container that one Durable Object starts for that session.
Prerequisites
You need:
A Devin Enterprise organization with permission to manage outposts and service users
A Cloudflare account on the Workers Paid plan with access to Containers
For manual deployment, Node.js 24 and a running Docker daemon
Get your Devin credentials
1. Open your Devin organization outpost settings. In this URL, replace both occurrences of `my-org` with your organization slug:
https://my-org.devinenterprise.com/org/my-org/settings/enterprise-environment?tab=outposts
Create or select an outpost, and copy its outpost ID for 
DEVIN_OUTPOST_ID.
For 
DEVIN_API_TOKEN, use a Devin service-user token with the Run outpost workers permission.
For more information about outposts, refer to the Devin Outposts overview.
Deploy with one click
The Deploy to Cloudflare button creates the Worker, the cron trigger, the Durable Object namespace, and the container application.
Enter these values when the deployment flow prompts for them:
Variable
Value
DEVIN_OUTPOST_ID
Your Devin Outpost ID
DEVIN_API_TOKEN
A Devin service-user token with the Run outpost workers permission
After the deployment finishes, select your outpost from the Virtual environment menu when you create a Devin session.
Customize and deploy manually
Deploy manually when you need to add dependencies, tools, or environment variables to the container image.
1. Create a project from the Devin Outpost template:
<PackageManagers
type="create"
pkg="cloudflare@latest"
args={
"cloudflare-devin-outpost --template=cloudflare/sandbox-sdk/templates/devin"
}
/>
Go to the project directory and log in to your Cloudflare account:
cd cloudflare-devin-outpost
npx wrangler login
In 
wrangler.jsonc, replace the empty 
DEVIN_OUTPOST_ID value with your outpost ID.
The default 
DEVIN_API_URL is 
https://api.devin.ai/opbeta. Change this value only if your Devin environment uses another API URL.
Store your Devin API token as a Worker secret:
npx wrangler secret put DEVIN_API_TOKEN
Enter your service-user token when Wrangler prompts you. Do not add the token to 
wrangler.jsonc.
Deploy the Worker and container:
npm run deploy
Wrangler builds the container image and deploys the Worker, the container application, and the cron trigger.
Check the deployment with the Worker URL from the Wrangler output:
curl https://<YOUR_WORKER>.workers.dev/
The Worker returns:
{
	"service": "devin-outpost",
	"status": "ok"
}
Run a Devin session
In Devin, create a session and select your outpost from the Virtual environment menu. The Worker checks for new sessions every 10 seconds by default, so the sandbox for the session starts shortly after you create it.
How the template runs sessions
A cron trigger runs the Worker once a minute. During each run, the Worker asks Devin for the sessions of your outpost every 10 seconds, or every 
DEVIN_RECONCILE_INTERVAL_MS milliseconds if you set that variable. The Worker sends the status of each session to the Durable Object for that session:
Devin status
What the template does
pending, 
running
Starts the sandbox for the session if it is not running, from its snapshot if it has one.
suspended
Waits for the Devin CLI to exit, saves a snapshot of the sandbox, then stops it.
terminated
Stops the sandbox and forgets its snapshot.
The Durable Object only starts and stops its container. Inside the sandbox, the Devin CLI (
devin worker start) claims the session and runs it.
Your Worker connects to Devin on a cron trigger and lists sessions. It sends each session to its own Durable Object, which starts and stops a container. The Devin CLI in the container connects to Devin, claims the session, and runs it. Every connection to Devin starts on Cloudflare, so nothing connects in.
When Devin suspends a session, the Devin CLI exits. The sandbox keeps running until the Durable Object saves a snapshot of its disk. When the session continues, the sandbox starts from that snapshot and the Devin CLI claims the session again. The snapshot keeps the files and installed packages of the session. It does not keep running processes. If the Devin CLI exits while the session is still running, the template saves a snapshot and starts a new sandbox from it.
For more information, refer to Save and restore a sandbox with snapshots.
:::note
The template saves a snapshot only after the Devin CLI exits. If a sandbox stops before then, the session continues from its previous snapshot, or from the image if it has none. The Worker API cannot delete snapshots, so the snapshot of a terminated session stays in your account.
:::
Security
Each session runs in its own container and does not share files or processes with other sessions. Inside the container, Devin runs as root, can reach the Internet, and holds the Devin API token. Code that runs in a session can read that token. Deploy a separate outpost for each group of users that must not share access.
For more information, refer to Sandbox security.
Related resources
Devin Outposts overview
Devin Outpost template
Containers
Save and restore a sandbox with snapshots

Run coding agents in a sandbox
import { CardGrid, LinkTitleCard } from "~/components";
Coding agents such as Claude Code, Codex, and OpenCode can run a task on their own: they read a repository, edit files, and run commands until the task is done. Run the agent in a Linux sandbox so its commands stay inside a Container that belongs to one task.
The agent runs in your sandbox
Your Worker starts the sandbox, holds the credentials, and decides which hostnames the sandbox can reach. The agent calls its model over HTTP, for example through AI Gateway. Your Worker adds the API token to each request, so the sandbox never receives it.
Each guide in this section changes only the agent-specific parts of one runner. Build the runner first:
Then switch the runner to another agent:
	
	
	
	
The vendor runs the agent loop
Devin, Cursor, Claude Managed Agents, and the OpenAI Agents API run their agent loop in their own service. The loop sends commands and file edits to sandboxes in your Cloudflare account. Each vendor template gives every session its own sandbox. In the Devin, Cursor, and OpenAI Agents API templates, the vendor worker process runs inside the sandbox, so the sandbox also holds a vendor credential.
	
	
	
	
Build your own agent
To give an agent that runs in a Durable Object a container to run commands in, refer to Sandbox in the Agents SDK documentation.

Run Codex with the OpenAI Agents API in a sandbox
import { CURL, Details, Steps } from "~/components";
The OpenAI Agents API runs the Codex agent loop at OpenAI. With a self-hosted environment, Codex runs commands and edits files in your Cloudflare account instead. The Cloudflare template runs the Codex executor of each session in its own Linux sandbox: a Container that one Durable Object starts for that session.
The template contains the Worker and the container image that this guide deploys.
How it works
OpenAI sends signed webhooks to a Worker in your account as a session starts, needs an environment, works, and goes idle. The Worker verifies each webhook, retrieves the session from OpenAI, and passes it to the Durable Object named for that session. The Durable Object starts a container that runs 
codex exec-server. The executor connects out to OpenAI with a restricted API key. It runs commands from the agent against files in 
/workspace, which stay in your Cloudflare account.
Prerequisites
You need:
A Cloudflare account on the Workers Paid plan with access to Containers
OpenAI Agents API access and an OpenAI API key
curl
For manual deployment, Node.js 24 or later and a running Docker daemon
You also need a restricted OpenAI API key for 
codex exec-server, called the executor key in this guide. It needs the 
api.model.read and 
api.agents.environments.connect permissions. The OpenAI API key that the Worker uses needs 
api.agents.read. Both keys must belong to the same organization, project, and owner, whether that owner is a user or a service account.
Deploy the template
These steps create an OpenAI agent, deploy the Worker and its container with the Deploy to Cloudflare button, register the webhook, and run a test task in 
/workspace.
1. Set your OpenAI API key, then create an agent:
export OPENAI_API_KEY="<OPENAI_API_KEY>"
<CURL
url="https://api.openai.com/v1/agents"
method="POST"
headers={{
"OpenAI-Beta": "agents=v1",
Authorization: "Bearer $OPENAI_API_KEY",
}}
json={{
name: "sandbox-demo",
model: "gpt-5.6-sol",
}}
/>
Copy the 
id field from the response and save it as the agent ID:
export OPENAI_AGENT_ID="agent_..."
Generate a shared secret for the container cleanup endpoint, and save it:
openssl rand -hex 32
Select Deploy to Cloudflare:
Enter these values when prompted:
Variable
Value
OPENAI_API_KEY
The OpenAI key used to retrieve session state
OPENAI_EXECUTOR_API_KEY
The restricted executor key
OPENAI_AGENT_ID
The agent ID from step 1
OPENAI_WEBHOOK_SECRET
pending-webhook-registration for the first deployment
EXECUTOR_CLIENT_SECRET
The shared secret from this step
Save the deployed Worker URL:
export WORKER_URL="https://<YOUR_WORKER>.workers.dev"
The template starts a container as soon as OpenAI creates a session, and snapshots the container when the session goes idle. An idle session keeps its container for 
EXECUTOR_KEEP_ALIVE_SECONDS, which 
wrangler.jsonc in the template sets to 30 seconds.
In OpenAI project webhook settings, register 
https://<YOUR_WORKER>.workers.dev/webhook. OpenAI must be able to reach this URL.
Subscribe to these events:
agent.session.created
agent.session.action_required
agent.session.in_progress
agent.session.idle
agent.session.failed
Copy the signing secret that OpenAI returns. In Settings > Variables and Secrets for the Worker, replace 
OPENAI_WEBHOOK_SECRET with it, then select Deploy. If you deployed manually, run this command in the 
templates/openai-agents-api directory instead:
npx wrangler secret put OPENAI_WEBHOOK_SECRET
Check the setup:
curl --fail-with-body "$WORKER_URL/health"
The Worker is ready when the response contains 
"configured": true and 
"webhook_configured": true.
Create a self-hosted session:
curl https://api.openai.com/v1/agents/sessions \
  --request POST \
  --header "OpenAI-Beta: agents=v1" \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --json '{"agent_id": "'"$OPENAI_AGENT_ID"'", "environment": {"type": "self_hosted", "workspace_directory": "/workspace"}}'
Copy the 
id field from the response and save it as the session ID:
export SESSION_ID="sess_..."
Open the session event stream in one terminal:
curl --no-buffer \
  "https://api.openai.com/v1/agents/sessions/$SESSION_ID/events" \
  --header "OpenAI-Beta: agents=v1" \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header "Accept: text/event-stream"
While the stream is open, submit a task from another terminal. Export 
OPENAI_API_KEY and 
SESSION_ID in that terminal first:
<CURL
url="https://api.openai.com/v1/agents/sessions/$SESSION_ID/events"
method="POST"
headers={{
"OpenAI-Beta": "agents=v1",
Authorization: "Bearer $OPENAI_API_KEY",
}}
json={{
events: [
{
type: "session.input.message",
input: [
{
role: "user",
content: [
{
type: "input_text",
text: "Use the shell to write hello to /workspace/hello.txt, then read it.",
},
],
},
],
},
],
}}
/>
The event stream shows the progress of the agent and its reply.
To deploy from your terminal instead of with the button in step 2:
1. Clone the template repository, install its dependencies, and log in to Cloudflare:
```bash
git clone https://github.com/cloudflare/sandbox-sdk.git
cd sandbox-sdk/templates/openai-agents-api
npm install
npx wrangler login
```
Generate a shared secret for the container cleanup endpoint, and save it:
openssl rand -hex 32
Store the Worker secrets. Enter your OpenAI API key, the executor key, the agent ID, and the shared secret when prompted:
npx wrangler secret put OPENAI_API_KEY
npx wrangler secret put OPENAI_EXECUTOR_API_KEY
npx wrangler secret put OPENAI_AGENT_ID
npx wrangler secret put EXECUTOR_CLIENT_SECRET
Deploy the Worker and its container:
npm run deploy
To change the keep-alive, prewarm, and snapshot settings, edit 
EXECUTOR_KEEP_ALIVE_SECONDS, 
EXECUTOR_PREWARM_ENABLED, and 
EXECUTOR_SNAPSHOTS_ENABLED in 
wrangler.jsonc, then run 
npm run deploy again.
Save the deployed Worker URL, then continue with step 3.
Open the session event stream again, then send more input:
<CURL
url="https://api.openai.com/v1/agents/sessions/$SESSION_ID/events"
method="POST"
headers={{
"OpenAI-Beta": "agents=v1",
Authorization: "Bearer $OPENAI_API_KEY",
}}
json={{
events: [
{
type: "session.input.message",
input: [
{
role: "user",
content: [
{
type: "input_text",
text: "Read /workspace/hello.txt again.",
},
],
},
],
},
],
}}
/>
Build an application on the Agents API
The basic example in the template is a TypeScript application that uses the OpenAI Agents API TypeScript SDK. It creates self-hosted sessions that run on the executor Worker. Its HTTP endpoints send the first input, send follow-up input, and clean up. The 
POST /demo endpoint runs the whole workflow: it creates a session, writes and reads a file in the container, sends a follow-up message, and then deletes the OpenAI session and its executor.
Clean up
Delete the OpenAI session:
<CURL
url="https://api.openai.com/v1/agents/sessions/$SESSION_ID"
method="DELETE"
headers={{
"OpenAI-Beta": "agents=v1",
Authorization: "Bearer $OPENAI_API_KEY",
}}
/>
To stop the container of a session at once, call the cleanup endpoint with the shared secret from deployment:
export WORKER_URL="https://<YOUR_WORKER>.workers.dev"
export EXECUTOR_CLIENT_SECRET="<EXECUTOR_CLIENT_SECRET>"
curl --fail-with-body \
  --request DELETE \
  --header "Authorization: Bearer $EXECUTOR_CLIENT_SECRET" \
  "$WORKER_URL/executors/$SESSION_ID"
Deleting an OpenAI session does not send a webhook to the Worker. The Worker stops a container and deletes its record of the container snapshot when it receives an 
agent.session.failed webhook, when a session lookup returns 
404 Not Found, or when you call the cleanup endpoint. An idle session that still exists keeps its snapshot for its next environment connection.
Session lifecycle
1. The application creates or retrieves an OpenAI session and sends input through the Agents API.
When 
EXECUTOR_PREWARM_ENABLED is 
true, as in the template, an 
agent.session.created webhook makes the Worker retrieve the session and start its container with the environment ID and remote URL of the session.
An 
agent.session.action_required webhook makes the Worker retrieve the session, confirm that the configured agent owns it, and read the environment ID and remote URL that the session needs.
The Durable Object named for the session starts a container with those connection details and the executor key. 
codex exec-server connects out to OpenAI.
Each container start, environment connection, and 
agent.session.in_progress webhook resets a deadline of 
EXECUTOR_KEEP_ALIVE_SECONDS. When the deadline passes, the Worker retrieves the session. If the session is still active, the Worker sets a new deadline.
An 
agent.session.idle webhook makes the Worker snapshot the container and reset the deadline. When the deadline passes, the Worker stops the container and keeps the snapshot.
New input sends another 
agent.session.action_required webhook. The Worker reuses a running container for the same environment ID, or starts the next environment from the saved snapshot.
Keep the workspace between turns
:::note[Public beta]
Container snapshots are in public beta. Features and behavior may change.
:::
When a session goes idle, the Worker snapshots the container filesystem before it stops the container. The next environment connection starts from that snapshot, so the files in 
/workspace come back. Running processes and memory do not. If the snapshot fails, the Worker leaves the container running and schedules another lifecycle check. For more information, refer to Sandbox lifetime.
A session uses its snapshot only while the session lasts. The Worker deletes the snapshot record of a session when the session fails, when a later lookup finds that the session no longer exists, or when you call the cleanup endpoint. The next session then starts from the image. The Worker does not delete the snapshot itself.
With 
EXECUTOR_SNAPSHOTS_ENABLED set to 
false, each new executor starts with an empty 
/workspace. To keep files after a session ends, store them somewhere else, such as an R2 bucket. For more information, refer to Mount an R2 bucket.
Add tools to the container
The 
templates/openai-agents-api/Dockerfile file in the template defines the executor image. Add Debian packages to its 
apt-get install command. For example, to add 
jq and Python:
RUN apt-get update \
    && apt-get install --yes --no-install-recommends \
      ca-certificates \
      curl \
      git \
      jq \
      python3 \
      ripgrep \
    && rm -rf /var/lib/apt/lists/*
You can also install language tools in the image, such as global npm packages. Do not put API keys or other secrets in the Dockerfile. Pass them at runtime through Worker secrets and container environment variables.
To build and deploy the new image, run 
npm run deploy in the 
templates/openai-agents-api directory. New containers start from it. A session that starts from a snapshot keeps the filesystem of its old image, so it does not get the new packages.
Security considerations
The template is a minimal example. Review these defaults before you adapt it for production:
Your OpenAI API key, the webhook secret, and 
EXECUTOR_CLIENT_SECRET stay in Worker secrets. The executor key goes into the container as 
CODEX_API_KEY, where every process in the container can read it. Give the executor key only the two permissions it needs.
The container has Internet access so that 
codex exec-server can reach OpenAI. Every command the agent runs has the same access. To restrict destinations or add credentials to requests from your Worker, refer to Outbound traffic.
OpenAI must reach 
/webhook without an interactive Access login. The Worker checks the signature on each webhook, and the cleanup endpoint requires 
EXECUTOR_CLIENT_SECRET. If you protect other routes with Cloudflare Access, use path-specific policies that leave 
/webhook reachable.
For more information about what a sandbox exposes to the code inside it, refer to Sandbox security.
Related resources
OpenAI Agents API template
OpenAI Agents API documentation
OpenAI Python Cloudflare webhook example
OpenAI TypeScript Cloudflare webhook example
Cloudflare Containers

Run OpenCode in a sandbox
import { PackageManagers, Steps, WranglerConfig } from "~/components";
Run OpenCode in a Linux sandbox to edit a GitHub repository from a prompt, then read its changes as a diff. OpenCode calls models through AI Gateway. Your Worker adds the gateway token to those requests, and the sandbox can reach only your gateway and 
github.com.
Prerequisites
The 
sandbox-coding-agent project from Build a coding agent runner. This page replaces the image, the model, and the parts of the Durable Object that are specific to the agent.
Anthropic credentials in AI Gateway, either Unified Billing credits or an Anthropic API key stored as a provider key.
Switch the Worker to OpenCode
Replace the 
Dockerfile. Only the highlighted lines differ from the 
Dockerfile in the tutorial:
FROM node:24-trixie-slim
RUN apt-get update \
	&& apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
	&& rm -rf /var/lib/apt/lists/*
RUN npm install --global --ignore-scripts opencode-linux-x64-baseline@1.19.4 \
	&& ln -s /usr/local/lib/node_modules/opencode-linux-x64-baseline/bin/opencode /usr/local/bin/opencode
COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim
WORKDIR /workspace
CMD ["sleep", "infinity"]
The image installs the baseline x64 OpenCode binary directly. The baseline binary runs on every x64 CPU. The 
opencode-ai package picks a binary for the CPU of the machine that builds the image. An 
amd64 build on another architecture runs under an emulator, where the package can pick the wrong binary.
OpenCode searches files with 
rg from the image. Without 
ripgrep, it tries to download 
rg from GitHub. The image pins the OpenCode version, because the model list and event format of OpenCode can change between releases.
In 
wrangler.jsonc, set 
MODEL to an OpenCode model ID for AI Gateway:
{
	"vars": {
		"AI_GATEWAY_ACCOUNT_ID": "<ACCOUNT_ID>",
		"AI_GATEWAY_ID": "default",
		"MODEL": "cloudflare-ai-gateway/anthropic/claude-sonnet-5",
	},
}
OpenCode model IDs for AI Gateway have the form 
cloudflare-ai-gateway/<PROVIDER>/<MODEL>. OpenCode uses the model list built into the pinned release. To print that list, run 
opencode models cloudflare-ai-gateway with the same OpenCode version.
In 
src/sandbox.ts, replace the 
ResultEvent constant with a schema for the OpenCode events that carry the reply and errors:
const OpencodeEvent = z.union([
	z.object({ type: z.literal("text"), part: z.object({ text: z.string() }) }),
	z.object({
		type: z.literal("error"),
		error: z.object({
			name: z.string(),
			data: z.object({ message: z.string().optional() }).optional(),
		}),
	}),
]);
Replace the 
agentCommand() and 
agentEnv() methods:
export class AgentSandbox extends DurableObject<Env> {
	// ...
	private agentCommand(prompt: string): string[] {
		return [
			"opencode",
			// Run one task without an interactive terminal
			"run",
			// Write one JSON event per line to the events file
			"--format",
			"json",
			"--auto",
			// Select the AI Gateway model from `MODEL`
			"--model",
			this.env.MODEL,
			"--",
			prompt,
		];
	}
	private agentEnv(): Record<string, string> {
		return {
			CLOUDFLARE_API_TOKEN: "provided-by-worker",
			CLOUDFLARE_ACCOUNT_ID: this.env.AI_GATEWAY_ACCOUNT_ID,
			CLOUDFLARE_GATEWAY_ID: this.env.AI_GATEWAY_ID,
			OPENCODE_DISABLE_MODELS_FETCH: "1",
			OPENCODE_DISABLE_AUTOUPDATE: "1",
			OPENCODE_DISABLE_DEFAULT_PLUGINS: "1",
			OPENCODE_DISABLE_LSP_DOWNLOAD: "1",
			OPENCODE_DISABLE_SHARE: "1",
		};
	}
}
--auto approves every tool call that the OpenCode configuration does not deny. Without it, OpenCode rejects permission requests in a run without a terminal. The container limits what commands from OpenCode can reach.
The built-in 
cloudflare-ai-gateway provider in OpenCode reads the account and gateway IDs from the environment. For Anthropic models, it sends requests to the universal endpoint of the gateway: the gateway path with no suffix. The 
Outbound entrypoint in the runner allows that path and the paths under it. 
CLOUDFLARE_API_TOKEN is a placeholder, because OpenCode does not start without a token. The 
Outbound entrypoint replaces the token header with the gateway token.
The 
OPENCODE_DISABLE_* variables make OpenCode use the model list built into the binary and turn off its update check, default plugins, language server downloads, and sharing. OpenCode still tries to install 
@opencode-ai/plugin from npm in the background. That request gets a 
403 response from the 
Outbound entrypoint, and OpenCode continues.
Replace the 
outcome() method:
export class AgentSandbox extends DurableObject<Env> {
	// ...
	private async outcome(exitCode: number): Promise<TaskStatus> {
		let text = "";
		let error: string | undefined;
		const events = await this.files.readFile(eventsPath);
		for await (const line of readLines(events.body)) {
			const parsed = OpencodeEvent.safeParse(parseJson(line));
			if (!parsed.success) {
				continue;
			}
			if (parsed.data.type === "text") {
				text = parsed.data.part.text;
			} else {
				error = parsed.data.error.data?.message ?? parsed.data.error.name;
			}
		}
		if (exitCode === 0) {
			return { state: "succeeded", result: text };
		}
		if (error === undefined) {
			const stderr = (await this.readOptionalText(stderrPath)) ?? "";
			return {
				state: "failed",
				error: `opencode exited with ${exitCode}: ${stderr.slice(-2000)}`,
			};
		}
		return { state: "failed", error };
	}
}
OpenCode exits with a nonzero code on any model or session error, so the exit code decides the outcome. A successful task returns the last 
text event. A failed task returns the message from the last 
error event, such as the message from the gateway for a rejected token or missing Unified Billing credits.
Deploy your Worker:
The 
AI_GATEWAY_TOKEN secret from the tutorial stays in place. A running container keeps the image it started with, so use a new sandbox name for OpenCode.
Run a task
Clone a repository into a sandbox named 
opencode-1:
curl "$WORKER_URL/sandboxes/opencode-1/repository" \
	--json '{"url": "https://github.com/octocat/Hello-World"}'
Start a task:
curl "$WORKER_URL/sandboxes/opencode-1/task" \
	--data "Add a file NOTES.md with a one-sentence summary of this repository. Do not commit."
Check the task until its state is 
succeeded or 
failed:
curl "$WORKER_URL/sandboxes/opencode-1/task"
A 
succeeded task includes the last text reply from OpenCode.
Read the changes:
curl "$WORKER_URL/sandboxes/opencode-1/diff"
The diff shows the new 
NOTES.md file.
Related resources
Build a coding agent runner: how the runner starts the sandbox, runs the task, and reads the diff.
OpenCode example: a separate deployable Worker that runs OpenCode.
OpenCode documentation

Run Pi in a sandbox
import { PackageManagers, Steps, WranglerConfig } from "~/components";
Run the Pi coding agent in a Linux sandbox to edit a GitHub repository from a prompt, then read its changes as a diff. Pi calls models through AI Gateway with its built-in provider. Your Worker adds the gateway token to those requests, and the sandbox can reach only your gateway and 
github.com.
Prerequisites
The 
sandbox-coding-agent project from Build a coding agent runner. This page replaces the image, the model, and the parts of the Durable Object that are specific to the agent.
Anthropic credentials in AI Gateway, either Unified Billing credits or an Anthropic API key stored as a provider key.
Switch the Worker to Pi
Replace the 
Dockerfile. Only the highlighted line differs from the 
Dockerfile in the tutorial:
FROM node:24-trixie-slim
RUN apt-get update \
	&& apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
	&& rm -rf /var/lib/apt/lists/*
RUN npm install --global --ignore-scripts @earendil-works/pi-coding-agent@0.87.1
COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim
WORKDIR /workspace
CMD ["sleep", "infinity"]
The image pins the version, because the flags and event format of Pi can change between releases.
In 
wrangler.jsonc, set 
MODEL to a model ID from the 
cloudflare-ai-gateway provider in Pi:
{
	"vars": {
		"AI_GATEWAY_ACCOUNT_ID": "<ACCOUNT_ID>",
		"AI_GATEWAY_ID": "default",
		"MODEL": "claude-sonnet-5",
	},
}
Use a model from a provider such as Anthropic. For most Workers AI models in its catalog, Pi 0.87.1 requests as many output tokens as the context window. Workers AI rejects those requests.
In 
src/sandbox.ts, replace the 
ResultEvent constant with a schema for the Pi events that report the outcome:
const PiEvent = z.union([
	z.object({ type: z.literal("agent_settled") }),
	z.object({
		type: z.literal("message_end"),
		message: z.object({
			role: z.literal("assistant"),
			content: z.array(
				z.object({ type: z.string(), text: z.string().optional() }),
			),
			stopReason: z.string(),
			errorMessage: z.string().optional(),
		}),
	}),
]);
type PiMessage = Extract<
	z.infer<typeof PiEvent>,
	{ type: "message_end" }
>["message"];
Replace the 
agentCommand() and 
agentEnv() methods:
export class AgentSandbox extends DurableObject<Env> {
	// ...
	private agentCommand(prompt: string): string[] {
		return [
			"pi",
			// Run one task, write one JSON event per line to the events file, and exit
			"--mode",
			"json",
			// Keep the session in memory instead of saving it to disk
			"--no-session",
			// Select the built-in AI Gateway provider in Pi, which reads the account
			// and gateway IDs from the environment
			"--provider",
			"cloudflare-ai-gateway",
			// Select the model from `MODEL`
			"--model",
			this.env.MODEL,
			"--",
			prompt,
		];
	}
	private agentEnv(): Record<string, string> {
		return {
			CLOUDFLARE_API_KEY: "provided-by-worker",
			CLOUDFLARE_ACCOUNT_ID: this.env.AI_GATEWAY_ACCOUNT_ID,
			CLOUDFLARE_GATEWAY_ID: this.env.AI_GATEWAY_ID,
			PI_OFFLINE: "1",
			PI_SKIP_VERSION_CHECK: "1",
			PI_TELEMETRY: "0",
		};
	}
}
Pi runs its tools without approval prompts. The container limits what commands from Pi can reach.
Pi does not start without an API key, so 
CLOUDFLARE_API_KEY is a placeholder. Pi sends the key in the 
cf-aig-authorization header, and the 
Outbound entrypoint replaces it with the gateway token. 
PI_OFFLINE, 
PI_SKIP_VERSION_CHECK, and 
PI_TELEMETRY turn off the model catalog refresh, version check, and telemetry in Pi.
Pi still loads 
AGENTS.md and 
CLAUDE.md files from the repository. Without the 
--approve flag, it skips the protected project resources in the 
.pi directory of the repository. Leave 
--approve off for repositories you do not trust.
Replace the 
outcome() method:
export class AgentSandbox extends DurableObject<Env> {
	// ...
	private async outcome(exitCode: number): Promise<TaskStatus> {
		if (exitCode !== 0) {
			const stderr = (await this.readOptionalText(stderrPath)) ?? "";
			return {
				state: "failed",
				error: `pi exited with ${exitCode}: ${stderr.slice(-2000)}`,
			};
		}
		let settled = false;
		let final: PiMessage | undefined;
		const events = await this.files.readFile(eventsPath);
		for await (const line of readLines(events.body)) {
			const parsed = PiEvent.safeParse(parseJson(line));
			if (!parsed.success) {
				continue;
			}
			if (parsed.data.type === "agent_settled") {
				settled = true;
			} else {
				final = parsed.data.message;
			}
		}
		if (!settled || final === undefined) {
			return { state: "failed", error: "pi exited before the agent settled" };
		}
		if (final.stopReason === "error" || final.stopReason === "aborted") {
			return {
				state: "failed",
				error: final.errorMessage ?? `pi stopped: ${final.stopReason}`,
			};
		}
		const text = final.content.flatMap((block) =>
			block.type === "text" ? [block.text ?? ""] : [],
		);
		return { state: "succeeded", result: text.join("") };
	}
}
Pi exits successfully even when a model request fails, so the outcome comes from its events. The task succeeds when Pi sends an 
agent_settled event and its last assistant message has a 
stopReason other than 
error or 
aborted. Otherwise, the task fails with the error message from Pi.
Deploy your Worker:
The 
AI_GATEWAY_TOKEN secret from the tutorial stays in place. A running container keeps the image it started with, so use a new sandbox name for Pi.
Run a task
Clone a repository into a sandbox named 
pi-1:
curl "$WORKER_URL/sandboxes/pi-1/repository" \
	--json '{"url": "https://github.com/octocat/Hello-World"}'
Start a task:
curl "$WORKER_URL/sandboxes/pi-1/task" \
	--data "Add a file NOTES.md with a one-sentence summary of this repository. Do not commit."
Check the task until its state is 
succeeded or 
failed:
curl "$WORKER_URL/sandboxes/pi-1/task"
A 
succeeded task includes the text of the last reply from Pi.
Read the changes:
curl "$WORKER_URL/sandboxes/pi-1/diff"
The diff shows the new 
NOTES.md file.
Related resources
Build a coding agent runner: how the runner starts the sandbox, runs the task, and reads the diff.
Pi example: a separate deployable Worker that runs Pi.
Pi in AI Gateway: route Pi through AI Gateway from your own terminal.

Follow a background process
import { PackageManagers, Steps, TypeScriptExample } from "~/components";
Read the output of a background process while it runs, from a request other than the one that started it. A page can show each line as the process prints it, and your Worker can wait until a process prints a line, such as 
ready from a development server.
Prerequisites
A Worker that runs background processes, with the scripts, 
run(), 
status(), and the routes from Run background processes.
Follow the output
Add a method that sends the output of a process as server-sent events while the process runs:
export class MyContainer extends DurableObject<Env> {
	// ...
	async follow(id: string, stream: "stdout" | "stderr"): Promise<Response | undefined> {
		const status = await this.status(id);
		if (!status) {
			return undefined;
		}
		const path = `${ROOT}/${id}/${stream}.log`;
		const argv =
			status.state === "running"
				? ["tail", "-n", "+1", "-F", "--pid", `${status.pid}`, path]
				: ["cat", path];
		const process = await this.ctx.container!.exec(argv, { stderr: "ignore" });
		const { readable, writable } = new TransformStream<Uint8Array, Uint8Array>();
		const writer = writable.getWriter();
		const encoder = new TextEncoder();
		const send = (event: string, data: unknown) =>
			writer.write(
				encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`),
			);
		let exited = false;
		const markExited = () => {
			exited = true;
		};
		process.exitCode.then(markExited, markExited);
		// Signaling a process that has exited records an internal error.
		const stop = () => {
			if (!exited) process.kill();
		};
		// Stop following when the client disconnects.
		writer.closed.catch(stop);
		// Detect a disconnected client while the log is quiet.
		const heartbeat = setInterval(() => {
			writer.write(encoder.encode(": keep-alive\n\n")).catch(() => {});
		}, 5_000);
		const pump = async () => {
			try {
				for await (const text of process.stdout!.pipeThrough(
					new TextDecoderStream(),
				)) {
					await send(stream, text);
				}
				const ended = await this.status(id);
				const exitCode = ended?.state === "exited" ? ended.exitCode : null;
				await send("exit", { exitCode });
				await writer.close();
			} catch (error) {
				stop();
				// End the response, so a connected client does not wait forever.
				await writer.abort(error).catch(() => {});
			} finally {
				clearInterval(heartbeat);
			}
		};
		void pump();
		return new Response(readable, {
			headers: {
				"Content-Type": "text/event-stream",
				"Cache-Control": "no-cache",
			},
		});
	}
}
follow() sends the output so far, then new output until the process exits and 
tail --pid stops. Each event is named after the stream, and holds a JSON-encoded chunk of output, which can be part of a line or several lines. When the output ends, 
follow() sends an 
exit event with the exit code, or 
null when the process recorded none. A page can read the stream with 
EventSource, as in Stream command output.
follow() notices a disconnected client only when a write fails. The keep-alive comment every five seconds makes that write happen while the log is quiet, so 
follow() stops 
tail. Without the comment, 
tail keeps running until the process exits.
In the 
logs branch of your Worker route, follow the output when the query has 
follow. Add this before the call to 
sandbox.logs():
if (url.searchParams.has("follow")) {
	const response = await sandbox.follow(id, stream);
	return response ?? new Response("Not found", { status: 404 });
}
Deploy your Worker:
Start a process named 
ticker, then follow its output. Replace the example hostname with the 
workers.dev URL that Wrangler prints:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/processes/ticker --request POST
curl "https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/processes/ticker/logs?follow" --no-buffer
The second request prints the lines so far as one event, then a new event each second:
event: stdout
data: "ready\ntick 1\ntick 2\ntick 3\ntick 4\n"
event: stdout
data: "tick 5\n"
event: stdout
data: "tick 6\n"
Add 
stream=stderr to the query to follow standard error.
In another terminal, stop the process:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/processes/ticker --request DELETE
The followed output ends with an 
exit event:
event: exit
data: {"exitCode":143}
Wait for a log line
A development server prints a line, such as 
ready, when it accepts requests. To wait for that line before you use the server, check the log files until a line matches or the process exits:
Add a script that checks the logs of a process:
// Prints the first matching line and exits with 0. Exits with 3 when the
// process ends without printing one, 4 when there is no such process, and
// 5 when the process was lost, for example in an earlier instance.
const WAIT = `${CURRENT}
dir=$1; pattern=$2
[ -d "$dir" ] || exit 4
while :; do
  exited=false; [ -e "$dir/exit-code" ] && exited=true
  if ! $exited && [ -e "$dir/pid" ] && ! { current "$dir" && kill -0 "$pid" 2>/dev/null; }; then
    sleep 0.1; [ -e "$dir/exit-code" ] || exit 5; exited=true
  fi
  line=$(grep -h -m 1 -E -e "$pattern" "$dir/stdout.log" "$dir/stderr.log" 2>/dev/null | head -n 1)
  [ -n "$line" ] && { printf '%s\\n' "$line"; exit 0; }
  $exited && exit 3
  sleep 0.2
done`;
Do not pipe 
tail -F into 
grep -m 1 instead: 
tail keeps running after 
grep exits, until the next line arrives.
Add a method that runs the script with a time limit:
export class MyContainer extends DurableObject<Env> {
	// ...
	async waitForLog(id: string, pattern: string, timeoutMs: number) {
		const container = this.ctx.container;
		if (!container?.running) {
			return undefined;
		}
		const result = await run(container, [
			"timeout",
			"--kill-after=5",
			`${timeoutMs / 1000}`,
			"sh",
			"-c",
			WAIT,
			"sh",
			`${ROOT}/${id}`,
			pattern,
		]);
		if (result.exitCode === 0) {
			return { state: "matched", line: result.stdout.trimEnd() };
		}
		if (result.exitCode === 3) {
			return { state: "exited" };
		}
		if (result.exitCode === 4) {
			return undefined;
		}
		if (result.exitCode === 5) {
			return { state: "lost" };
		}
		// 124 when the time limit passes, or 137 if timeout also sends SIGKILL.
		if (result.exitCode === 124 || result.exitCode === 137) {
			return { state: "timed-out" };
		}
		throw new Error(`The log check failed with exit code ${result.exitCode}`);
	}
}
timeout stops the script when the time limit passes. If the script is still running five seconds later, 
--kill-after=5 stops it with 
SIGKILL.
Call it after 
startProcess(), for example with the pattern 
^ready:
const ready = await sandbox.waitForLog(id, "^ready", 30_000);
{ "state": "matched", "line": "ready" }
The pattern is an extended regular expression. The state is 
exited when the process ends without printing a matching line, 
lost when it ended without recording an exit code, and 
timed-out when the time limit passes first. The method returns 
undefined when no process uses the ID. A process that was still running when an earlier instance stopped is 
lost, even when its log matches, because 
current() checks the boot ID.
Related resources
Run background processes: start, check, and stop the processes that this page follows.
Stream command output: stream the output of a command that finishes while the request is open.
Run a server in the background: processes that run until the container stops.

Run commands in a sandbox
Each of the following guides runs a command in a sandbox with 
exec(). They differ in how the output reaches the caller and in what ends the command:
Guide
How the output reaches the caller
The command runs until
Run Python code
In the response, after the code exits
The code exits
Run tests from a Git repository
In the response, after the tests finish
The tests finish
Stream command output
As server-sent events, while the command runs
It exits, or a disconnect sends it 
SIGTERM
Run background processes
In files that later requests read
It exits, or a later request stops it
Follow a background process
As server-sent events, from those files
It exits, or a later request stops it
Run a server in the background
Over the server port, and in a log file
The container stops, or a request stops it
Open a terminal in the browser
In an interactive terminal, over a WebSocket
You run 
exit, or your Worker ends the session
For every option that 
exec() accepts, refer to Execute commands in the Containers documentation.

Open a terminal in the browser
import {
PackageManagers,
Render,
Steps,
TypeScriptExample,
WranglerConfig,
} from "
/components";
import { BrowserTerminal } from "/components/react/sandbox/BrowserTerminal";
Expose a live shell in a Linux sandbox on a web page. The page runs xterm.js and connects it over a WebSocket to a shell in a tmux session. The shell keeps running when the page reloads or the connection drops.
<BrowserTerminal
url="https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/sandboxes/ada/"
lines={[
"root@fbed6b5a41ac5bf7fa2b2db27f4d6a8268aab85bdaf6be012a2e881812eb617d:
# stty size",
"21 95",
'root@fbed6b5a41ac5bf7fa2b2db27f4d6a8268aab85bdaf6be012a2e881812eb617d:# for i in $(seq 1 600); do echo "line $i"; sleep 1; done',
"line 1",
"line 2",
"line 3",
"line 4",
"line 5",
]}
status={{
left: "[main] 0:sleep*",
right: '"fbed6b5a41ac5bf7fa2b2" 02:45 25-Sep-26',
}}
/>
Prerequisites
A Worker with a Durable Object that starts a container with the Durable Object scheduling policy. To create one, refer to Run a Linux command.
Open a terminal
Create a 
Dockerfile in the project root with tmux:
FROM node:24-trixie-slim
RUN apt-get update \
	&& apt-get install -y --no-install-recommends tmux \
	&& rm -rf /var/lib/apt/lists/*
# Scroll back with the mouse wheel, and keep more history.
RUN printf 'set -g mouse on\nset -g history-limit 50000\n' > /etc/tmux.conf
CMD ["sleep", "infinity"]
sleep infinity keeps the container running so that it can accept 
exec() calls for each terminal.
In 
wrangler.jsonc, build the 
Dockerfile as a named image in your 
containers entry, then generate types for it:
{
	"containers": [
		{
			"class_name": "MyContainer",
			"scheduling_policy": "durable_object",
			"images": {
				"terminal": {
					"dockerfile": "./Dockerfile",
				},
			},
		},
	],
}
Add an inactivity timeout to your Durable Object. The constructor sets the timeout again when a restarted Durable Object finds the container running:
const INACTIVITY_TIMEOUT_MS = 5 * 60 * 1000;
export class MyContainer extends DurableObject<Env> {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		const container = ctx.container;
		if (container?.running) {
			void ctx.blockConcurrencyWhile(() =>
				container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS),
			);
		}
	}
}
The 5-minute timeout gives a reloaded page or a dropped connection time to attach to the same tmux session.
Then add a 
fetch() handler that attaches a WebSocket to a tmux session:
export class MyContainer extends DurableObject<Env> {
	// ...
	async fetch(request: Request): Promise<Response> {
		const container = this.ctx.container;
		if (!container) {
			throw new Error("No container is configured");
		}
		if (request.headers.get("Upgrade") !== "websocket") {
			return new Response("Expected a WebSocket upgrade", { status: 426 });
		}
		// tmux session names cannot contain "." or ":".
		const url = new URL(request.url);
		const session = url.searchParams.get("session") || "main";
		if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(session)) {
			return new Response("Invalid session name", { status: 400 });
		}
		if (!container.running) {
			container.start({
				image: container.images.terminal,
				// Block commands in the terminal from reaching the Internet
				enableInternet: false,
			});
			await container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS);
		}
		// Attach to the tmux session, or create it. The session keeps the shell
		// running after this WebSocket closes.
		const abort = new AbortController();
		const tmux = await container.exec(
			["tmux", "new-session", "-A", "-s", session],
			{
				// Run the tmux client attached to a pseudo-terminal.
				pty: {
					cols: Number(url.searchParams.get("cols")) || 80,
					rows: Number(url.searchParams.get("rows")) || 24,
				},
				env: { TERM: "xterm-256color" },
				cwd: "/root",
				signal: abort.signal,
			},
		);
		const [client, server] = Object.values(new WebSocketPair());
		// Receive binary messages as ArrayBuffer instead of Blob.
		server.binaryType = "arraybuffer";
		// Keep this Durable Object in memory while the terminal is open.
		server.accept();
		const stdin = tmux.stdin!.getWriter();
		// Listeners must not throw. An exception closes the socket without running
		// the `close` listener, which leaves the tmux client running.
		server.addEventListener("message", (event) => {
			if (typeof event.data === "string") {
				try {
					const { cols, rows } = JSON.parse(event.data);
					tmux.resize(cols, rows);
				} catch {
					// Ignore malformed resize messages so the terminal keeps running.
				}
			} else {
				stdin.write(new Uint8Array(event.data)).catch(() => {});
			}
		});
		let exited = false;
		const markExited = () => {
			exited = true;
		};
		tmux.exitCode.then(markExited, markExited);
		// Stop the tmux client when the browser disconnects. The session and its
		// shell keep running.
		server.addEventListener("close", () => {
			// Signaling a process that has exited raises an error.
			if (!exited) abort.abort();
		});
		const forward = async () => {
			for await (const chunk of tmux.stdout!) {
				server.send(chunk);
			}
			server.close(1000, `Terminal closed with code ${await tmux.exitCode}`);
		};
		void forward().catch(() => server.close(1011, "Terminal output failed"));
		return new Response(null, { status: 101, webSocket: client });
	}
}
Each WebSocket gets its own tmux client. 
tmux new-session -A attaches the client to the named session, or creates the session if it does not exist. The handler writes keystrokes to the standard input of the client, applies resize messages, and forwards the client output unchanged.
The handler accepts the WebSocket with 
accept() instead of the Hibernation WebSocket API. Hibernation would discard the process handle of the tmux client.
The shell runs as 
root. The 
user option of 
exec(), such as 
user: "1000:1000", changes the Linux user of the shell. It does not limit what the shell can read or change. For more information, refer to Sandbox security.
Create a terminal page:
<!doctype html>
<html lang="en">
	<head>
		<meta charset="utf-8" />
		<title>Sandbox terminal</title>
		<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@xterm/xterm@6.0.0/css/xterm.css" />
		<style>
			html, body, #terminal { height: 100%; margin: 0; background: #000; }
		</style>
	</head>
	<body>
		<div id="terminal"></div>
		<script type="module">
			import { Terminal } from "https://cdn.jsdelivr.net/npm/@xterm/xterm@6.0.0/lib/xterm.mjs";
			import { FitAddon } from "https://cdn.jsdelivr.net/npm/@xterm/addon-fit@0.11.0/lib/addon-fit.mjs";
			// With tmux mouse mode on, hold Shift (Option on macOS) to select text.
			const terminal = new Terminal({ macOptionClickForcesSelection: true });
			const fitAddon = new FitAddon();
			terminal.loadAddon(fitAddon);
			terminal.open(document.getElementById("terminal"));
			fitAddon.fit();
			const url = new URL("terminal", location.href);
			url.protocol = location.protocol === "https:" ? "wss:" : "ws:";
			url.searchParams.set("session", new URLSearchParams(location.search).get("session") || "main");
			url.searchParams.set("cols", terminal.cols);
			url.searchParams.set("rows", terminal.rows);
			const socket = new WebSocket(url);
			socket.binaryType = "arraybuffer";
			const encoder = new TextEncoder();
			const send = (data) => {
				if (socket.readyState === WebSocket.OPEN) socket.send(data);
			};
			socket.addEventListener("message", (event) => {
				terminal.write(new Uint8Array(event.data));
			});
			socket.addEventListener("close", (event) => {
				terminal.writeln("");
				terminal.writeln("[" + (event.reason || "Disconnected") + "]");
			});
			terminal.onData((data) => send(encoder.encode(data)));
			terminal.onResize(({ cols, rows }) => send(JSON.stringify({ cols, rows })));
			addEventListener("resize", () => fitAddon.fit());
		</script>
	</body>
</html>
The page sends keystrokes as binary messages and window sizes as JSON text messages. When the connection closes, the page prints the reason, and a reload connects again. For a page that reconnects by itself, refer to the terminal workspace example.
The page loads xterm.js from a CDN. In production, install 
@xterm/xterm and 
@xterm/addon-fit from npm and serve them with static assets.
Add routes to your Worker that serve the page and pass the WebSocket to the sandbox:
const page = `[... HTML from step 4 ...]`;
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);
		const match = /^\/sandboxes\/([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)\/(terminal)?$/.exec(url.pathname);
		if (!match) {
			return new Response("Not found", { status: 404 });
		}
		const sandbox = env.MY_CONTAINER.getByName(match[1]);
		if (match[2]) {
			return sandbox.fetch(request);
		}
		return new Response(page, {
			headers: { "Content-Type": "text/html; charset=utf-8" },
		});
	},
} satisfies ExportedHandler<Env>;
Anyone who opens the page gets a 
root shell in the sandbox named in the URL. Authenticate callers first, and derive the sandbox name from the caller's identity. For more information, refer to Sandbox security.
Deploy your Worker:
Open the terminal for the sandbox named 
ada in your browser. Replace the example hostname with the 
workers.dev URL that Wrangler prints, and keep the trailing slash:
https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/sandboxes/ada/
After the sandbox starts, a shell prompt appears with a green tmux status line at the bottom.
Run 
stty size. The shell prints its rows and columns, such as 
32 109. Resize the browser window and run 
stty size again. The numbers change to match the window, minus one row for the status line.
Start a command that keeps printing, then reload the page:
for i in $(seq 1 600); do echo "line $i"; sleep 1; done
The terminal attaches to the same shell, and the count has kept going while the page was away. tmux keeps earlier output in its history. Scroll back with the mouse wheel, and press 
q to leave the history.
Open the same URL in a second browser tab. Both tabs show the same screen, and you can type in either. When the tabs are different sizes, tmux fits the screen to the tab used most recently and fills the rest of a larger tab with dots. To open a separate shell in the same sandbox, add 
?session=build to the URL.
Run 
exit in the shell to end the session. The page shows 
[Terminal closed with code 0]. To leave the session running, detach with 
CTRL + B then 
D, and reload the page to attach again.
Run another command in the terminal
To run an interactive command instead of the default shell, such as the command-line interface of a coding agent, add it after the session name in the 
exec() call. tmux runs the command when it creates the session:
const tmux = await container.exec(
	["tmux", "new-session", "-A", "-s", session, "claude"],
	{
		// Same options as before.
	},
);
Install the command in the 
Dockerfile.
A coding agent also calls its model over the network, which 
enableInternet: false blocks. To route its requests through your Worker and allow only the hostnames that it needs, refer to 
interceptOutboundHttps().
End a session from your Worker
To end a session without a browser, run 
tmux kill-session in your Durable Object:
await container.exec(["tmux", "kill-session", "-t", `=${session}`]);
The 
= matches the session name exactly instead of as a prefix. To list sessions, run 
tmux list-sessions.
Related resources
Stream command output: run a command without a terminal and stream its output.
Terminal workspace example: a deployable Worker with this terminal, plus routes that list and end sessions.
Durable Object container API: every 
exec() option.
xterm.js documentation: terminal options and add-ons.

Run a server in the background
import { PackageManagers, Steps, TypeScriptExample } from "~/components";
Start a server that runs until the container stops, such as a development server, a tunnel, or a code kernel. Unlike a job, nothing waits for the server to exit. Your Durable Object starts it on first use, waits until it answers, and starts it again in each new container.
For a process that runs until it finishes, such as a build or an agent task, refer to Run background processes. If the sandbox runs one server and keeps no files that you need, you can make the server the main process instead, as in Preview a web application. When the main process exits, the instance stops, and its files end with it.
Prerequisites
A Worker with a Durable Object that starts a container with the Durable Object scheduling policy. To create one, refer to Run a Linux command.
Run a server
Add shell scripts and functions that start a server, check it, and stop it:
const SERVERS = "/var/lib/servers";
const INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000;
// Defines current(), which reads the process ID in a directory into $pid
// when the process started in this instance.
const CURRENT = `current() {
	read -r pid boot 2>/dev/null <"$1/pid" &&
		[ "$boot" = "$(cat /proc/sys/kernel/random/boot_id)" ]
}`;
// Starts the server unless it already runs. The server runs in its own
// process group, and writes its process ID and output to its directory.
const SERVE = `${CURRENT}
dir=$1; shift
current "$dir" && kill -0 "$pid" 2>/dev/null && exit 0
mkdir -p "$dir" && rm -f "$dir/pid"
setsid sh -c 'echo "$$ $(cat /proc/sys/kernel/random/boot_id)" >"$0/pid"; exec "$@"' \\
	"$dir" "$@" >"$dir/log" 2>&1`;
// Prints the end of the log and exits with 0 when the server has exited.
const EXITED = `${CURRENT}
current "$1" || exit 1
kill -0 "$pid" 2>/dev/null && exit 1
tail -n 20 "$1/log"`;
// Stops the process group, with SIGKILL if the server still runs after
// 10 seconds. Once the server exits, removes its process ID.
const STOP = `${CURRENT}
current "$1" || exit 0
kill -s TERM -- "-$pid" 2>/dev/null
timeout 10 sh -c 'while kill -0 "$0" 2>/dev/null; do sleep 0.1; done' "$pid" ||
	kill -s KILL -- "-$pid" 2>/dev/null
while kill -0 "$pid" 2>/dev/null; do sleep 0.1; done
rm -f "$1/pid"`;
type ServerOptions = { cwd?: string; env?: Record<string, string> };
async function startServer(
	container: Container,
	dir: string,
	argv: string[],
	options: ServerOptions = {},
): Promise<void> {
	// Ignoring the output lets the server outlive this request.
	await container.exec(["sh", "-c", SERVE, "sh", dir, ...argv], {
		...options,
		stdout: "ignore",
		stderr: "ignore",
	});
}
async function serverExited(
	container: Container,
	dir: string,
): Promise<string | undefined> {
	const check = await container.exec(["sh", "-c", EXITED, "sh", dir]);
	const output = await check.output();
	return output.exitCode === 0
		? new TextDecoder().decode(output.stdout)
		: undefined;
}
async function waitForServer(
	container: Container,
	dir: string,
	port: number,
	timeoutMs: number,
): Promise<Fetcher> {
	const server = container.getTcpPort(port);
	const deadline = Date.now() + timeoutMs;
	while (Date.now() < deadline) {
		try {
			const response = await server.fetch("http://server/", {
				signal: AbortSignal.timeout(1_000),
			});
			await response.body?.cancel();
			return server;
		} catch {
			const log = await serverExited(container, dir);
			if (log !== undefined) {
				throw new Error(`The server exited: ${log}`);
			}
			await scheduler.wait(500);
		}
	}
	throw new Error("The server did not answer in time");
}
async function stopServer(container: Container, dir: string): Promise<void> {
	const stop = await container.exec(["sh", "-c", STOP, "sh", dir]);
	const exitCode = await stop.exitCode;
	if (exitCode !== 0) {
		throw new Error(`Stopping the server failed with exit code ${exitCode}`);
	}
}
SERVE starts nothing when the server in the directory already runs, and a new container, which has no server, gets one. This also covers a Durable Object that restarts while its container keeps running.
The process ID file also records the boot ID, which changes in every instance. A snapshot restores the file, and a new instance reuses the same process IDs, so a restored process ID can belong to an unrelated process. 
current() ignores a process ID from another instance.
setsid starts the server in a new process group, so 
STOP also stops the processes that the server starts. The shell that runs 
SERVE stays in the container until the server exits. Do not start the server with 
& instead: a shell starts background jobs with 
SIGINT ignored.
STOP removes the process ID once the server exits, so a server started in the same directory right after it never reads as exited. A server that ignores 
SIGTERM receives 
SIGKILL after 10 seconds.
waitForServer() treats any HTTP response as ready. If the server exits first, it throws with the end of the log. The log grows until the server stops, so keep the output of a busy server small, or send it to a mounted bucket.
Add a constructor to your Durable Object. It sets the inactivity timeout again when a restarted Durable Object finds the container running:
export class MyContainer extends DurableObject<Env> {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		const container = ctx.container;
		if (container?.running) {
			void ctx.blockConcurrencyWhile(() =>
				container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS),
			);
		}
	}
}
Then add methods that send a request to the server, starting it first, and stop it:
const WEB = `${SERVERS}/web`;
const WEB_PORT = 8080;
const WEB_SERVER = [
	"node",
	"--eval",
	`require("node:http")
		.createServer((req, res) => res.end("hello from the server\\n"))
		.listen(${WEB_PORT})`,
];
export class MyContainer extends DurableObject<Env> {
	// ...
	// The server start that requests in progress share
	private starting?: Promise<Fetcher>;
	async fetchServer(request: Request): Promise<Response> {
		const container = this.ctx.container;
		if (!container) {
			throw new Error("No container is configured");
		}
		if (!container.running) {
			container.start({
				image: "cloudflare/debian-trixie",
				entrypoint: ["sleep", "infinity"],
				enableInternet: false,
			});
			await container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS);
		}
		this.starting ??= startServer(container, WEB, WEB_SERVER)
			.then(() => waitForServer(container, WEB, WEB_PORT, 30_000))
			.finally(() => {
				this.starting = undefined;
			});
		const server = await this.starting;
		return server.fetch(request);
	}
	async stopWeb(): Promise<void> {
		const container = this.ctx.container;
		if (container?.running) {
			await stopServer(container, WEB);
		}
	}
}
Requests that arrive together share one start. 
startServer() returns before the server records its process ID, so a second 
SERVE in that window would start a second server. The second server fails on the port, overwrites the process ID file, and leaves 
STOP unable to stop the first one. After the server answers, each request runs 
SERVE again, which starts nothing while the server runs and restarts it if it exited.
A running server does not keep the container running. Requests that reach the server through your Durable Object keep it running, as other requests do. When the inactivity timeout ends, the container stops, and the server stops with it. For more information, refer to Sandbox lifetime.
Add routes to your Worker that call these methods:
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);
		if (url.pathname !== "/server") {
			return new Response("Not found", { status: 404 });
		}
		const sandbox = env.MY_CONTAINER.getByName("sandbox");
		if (request.method === "DELETE") {
			await sandbox.stopWeb();
			return new Response(null, { status: 202 });
		}
		// getTcpPort() accepts only http:// URLs.
		const forward = new Request("http://container/", request);
		return sandbox.fetchServer(forward);
	},
} satisfies ExportedHandler<Env>;
Deploy your Worker:
Send a request to the server. Replace the example hostname with the 
workers.dev URL that Wrangler prints:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/server
The first request starts the container and the server, and waits until the server answers:
hello from the server
Stop the server, then send another request:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/server --request DELETE
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/server
The 
DELETE request responds with 
202. The next request starts the server again and prints the same response.
Related resources
Run background processes: processes that run until they finish.
Preview a web application: a web server as the main process.
Sandbox lifetime
getTcpPort()

Run background processes
import { PackageManagers, Steps, TypeScriptExample } from "~/components";
Start a process that keeps running after the request ends, such as a build, a test suite, or an agent task. The process object that 
exec() returns belongs to the request that started it, so later requests manage the process through files in the sandbox. The process writes its process ID, output, and exit code to those files.
For a process that runs until the container stops, such as a development server or a tunnel, refer to Run a server in the background.
Prerequisites
A Worker with a Durable Object that starts a container with the Durable Object scheduling policy. To create one, refer to Run a Linux command.
Run a process in the background
Add shell scripts that run a process and report its state:
const ROOT = "/var/lib/processes";
const INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000;
// Runs the command in its own process group. Records its process ID when
// it starts and its exit code when it ends.
const RUN = `dir=$1; shift
setsid sh -c 'echo "$$ $(cat /proc/sys/kernel/random/boot_id)" >"$0/pid"; exec "$@"' \\
	"$dir" "$@" >"$dir/stdout.log" 2>"$dir/stderr.log"
echo "$?" >"$dir/exit-code.tmp" && mv "$dir/exit-code.tmp" "$dir/exit-code"`;
// Defines current(), which reads the process ID in a directory into $pid
// when the process started in this instance.
const CURRENT = `current() {
	read -r pid boot 2>/dev/null <"$1/pid" &&
		[ "$boot" = "$(cat /proc/sys/kernel/random/boot_id)" ]
}`;
// Prints the state of the process that owns the directory.
const STATUS = `${CURRENT}
dir=$1
if [ ! -d "$dir" ]; then echo missing
elif [ -e "$dir/exit-code" ]; then echo "exited $(cat "$dir/exit-code")"
elif [ ! -e "$dir/pid" ]; then echo starting
elif current "$dir" && kill -0 "$pid" 2>/dev/null; then echo "running $pid"
elif [ -e "$dir/exit-code" ]; then echo "exited $(cat "$dir/exit-code")"
else echo lost
fi`;
type Status =
	| { state: "starting" | "lost" }
	| { state: "running"; pid: number }
	| { state: "exited"; exitCode: number };
async function run(container: Container, argv: string[]) {
	const process = await container.exec(argv);
	const output = await process.output();
	return {
		exitCode: output.exitCode,
		stdout: new TextDecoder().decode(output.stdout),
	};
}
setsid starts the command in a new process group. Stopping the group also stops the processes the command starts, such as the 
node process behind 
npm run dev, unless a process moves to its own group. The script writes the exit code to a temporary file and then renames it, so a reader never sees a partial file. Do not start the command with 
& instead: a shell starts background jobs with 
SIGINT ignored.
Each process keeps its files in its own directory under 
/var/lib/processes on the instance disk. The logs grow until the process ends. When the disk fills, writes from the process fail, so delete old process directories, or send output that you want to keep to a mounted bucket.
Add a constructor to your Durable Object. It sets the inactivity timeout again when a restarted Durable Object finds the container running:
export class MyContainer extends DurableObject<Env> {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		const container = ctx.container;
		if (container?.running) {
			void ctx.blockConcurrencyWhile(() =>
				container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS),
			);
		}
	}
}
Then add a method that starts a process:
export class MyContainer extends DurableObject<Env> {
	// ...
	async startProcess(id: string, argv: string[]): Promise<boolean> {
		const container = this.ctx.container;
		if (!container) {
			throw new Error("No container is configured");
		}
		if (!container.running) {
			container.start({
				image: "cloudflare/debian-trixie",
				entrypoint: ["sleep", "infinity"],
				enableInternet: false,
			});
			await container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS);
		}
		// mkdir fails when another process already uses the ID.
		const dir = `${ROOT}/${id}`;
		await run(container, ["mkdir", "-p", ROOT]);
		const created = await run(container, ["mkdir", dir]);
		if (created.exitCode !== 0) {
			return false;
		}
		// Ignoring the output lets the process outlive this request.
		await container.exec(["sh", "-c", RUN, "sh", dir, ...argv], {
			stdout: "ignore",
			stderr: "ignore",
		});
		// exec() returns before the process records its ID. Wait for it, so
		// a request that follows the output right away finds it running.
		for (let i = 0; i < 50; i++) {
			if ((await this.status(id))?.state !== "starting") break;
			await scheduler.wait(100);
		}
		await this.ctx.storage.put(`process:${id}`, argv);
		await this.ctx.storage.setAlarm(Date.now() + 60_000);
		return true;
	}
}
Add a method that reports the state of a process:
export class MyContainer extends DurableObject<Env> {
	// ...
	async status(id: string): Promise<Status | undefined> {
		const container = this.ctx.container;
		if (!container?.running) {
			return undefined;
		}
		const { stdout } = await run(container, [
			"sh",
			"-c",
			STATUS,
			"sh",
			`${ROOT}/${id}`,
		]);
		const [state, value] = stdout.trim().split(" ");
		if (state === "running") {
			return { state, pid: Number(value) };
		}
		if (state === "exited") {
			return { state, exitCode: Number(value) };
		}
		if (state === "starting" || state === "lost") {
			return { state };
		}
		return undefined;
	}
}
kill -0 checks that the process exists without sending it a signal. A process is 
lost when it ended without recording an exit code, for example because something sent 
SIGKILL to the script that records it.
The process ID file also records the boot ID, which changes in every instance. A snapshot restores the file, and a new instance reuses the same process IDs, so a restored process ID can belong to an unrelated process. 
current() ignores a process ID from another instance, so a process that was running when the snapshot was taken is 
lost.
Add a method that returns the output of a process so far:
export class MyContainer extends DurableObject<Env> {
	// ...
	async logs(id: string, stream: "stdout" | "stderr"): Promise<string | undefined> {
		if (!(await this.status(id))) {
			return undefined;
		}
		const path = `${ROOT}/${id}/${stream}.log`;
		return (await run(this.ctx.container!, ["cat", path])).stdout;
	}
}
To stream the output while the process runs, or to wait until it prints a line, refer to Follow a background process.
Add a method that stops a process:
export class MyContainer extends DurableObject<Env> {
	// ...
	async stop(id: string): Promise<boolean> {
		const status = await this.status(id);
		if (status?.state !== "running") {
			return false;
		}
		// `kill` is a shell built-in. A negative ID signals the process group.
		const { exitCode } = await run(this.ctx.container!, [
			"sh",
			"-c",
			'kill -s TERM -- "$1"',
			"sh",
			`-${status.pid}`,
		]);
		return exitCode === 0;
	}
}
A process stopped by a signal exits with 
128 plus the signal number, such as 
143 for 
SIGTERM.
Add an alarm handler that keeps the sandbox running while any process runs:
export class MyContainer extends DurableObject<Env> {
	// ...
	async alarm(): Promise<void> {
		let running = false;
		for (const [key, argv] of await this.ctx.storage.list<string[]>({
			prefix: "process:",
		})) {
			const id = key.slice("process:".length);
			const status = await this.status(id);
			if (status?.state === "running" || status?.state === "starting") {
				running = true;
			} else {
				console.log({ event: "process.ended", id, argv, status });
				await this.ctx.storage.delete(key);
			}
		}
		if (running) {
			await this.ctx.storage.setAlarm(Date.now() + 60_000);
		}
	}
}
A running process does not keep the container running. The alarm checks every process each minute, and each alarm keeps the container running. A Durable Object that restarted between alarms sets the 10-minute inactivity timeout again in its constructor. The container stops 10 minutes after the alarm finds that the last process has ended. For more information, refer to Sandbox lifetime.
A Durable Object has one alarm. If your class already has an 
alarm() handler, merge the process checks into it, and set the alarm to the earliest time that any check needs. For more information, refer to Alarms.
When a process ends, the alarm writes a 
process.ended log to Workers Logs within a minute. Replace the 
console.log() call with what your application does next, such as sending a notification.
Add routes to your Worker that call these methods:
const command = [
	"sh",
	"-c",
	"echo ready; for i in $(seq 1 300); do echo tick $i; sleep 1; done",
];
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);
		const match = /^\/processes\/([a-z0-9-]{1,63})(\/logs)?$/.exec(
			url.pathname,
		);
		if (!match) {
			return new Response("Not found", { status: 404 });
		}
		const [, id, logs] = match;
		const sandbox = env.MY_CONTAINER.getByName("sandbox");
		if (logs) {
			const stream =
				url.searchParams.get("stream") === "stderr" ? "stderr" : "stdout";
			const output = await sandbox.logs(id, stream);
			return output === undefined
				? new Response("Not found", { status: 404 })
				: new Response(output);
		}
		if (request.method === "POST") {
			return (await sandbox.startProcess(id, command))
				? new Response(null, { status: 201 })
				: new Response("The process ID is in use", { status: 409 });
		}
		if (request.method === "DELETE") {
			return (await sandbox.stop(id))
				? new Response(null, { status: 202 })
				: new Response("The process is not running", { status: 409 });
		}
		const status = await sandbox.status(id);
		return status
			? Response.json(status)
			: new Response("Not found", { status: 404 });
	},
} satisfies ExportedHandler<Env>;
This example command prints 
ready, then prints a line each second for five minutes. Replace it with your own command. The route accepts only process IDs that are safe in a path, because each ID becomes a directory name.
Deploy your Worker:
Start a process named 
ticker, then check it. Replace the example hostname with the 
workers.dev URL that Wrangler prints:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/processes/ticker --request POST
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/processes/ticker
The first request responds with 
201, and a second 
POST with the same ID responds with 
409. The status includes the process ID:
{ "state": "running", "pid": 354 }
Read the output so far:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/processes/ticker/logs
The request prints the lines so far and ends:
ready
tick 1
tick 2
tick 3
Add 
stream=stderr to the query to read standard error.
Stop the process, then check it again:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/processes/ticker --request DELETE
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/processes/ticker
The 
DELETE request responds with 
202. The status shows the exit code:
{ "state": "exited", "exitCode": 143 }
Related resources
Follow a background process: stream the output of a process while it runs, or wait until it prints a line.
Stream command output: commands that finish while the request is open.
Run a server in the background: processes that run until the container stops.
Preview a web application: a web server as the main process.
Process workspace example: a deployable Worker that runs processes with the same approach, plus routes that list processes and wait for one to exit. Its scripts do not record the boot ID.
Sandbox lifetime
Durable Object alarms

Run Python code
import {
PackageManagers,
Render,
Steps,
TypeScriptExample,
WranglerConfig,
} from "~/components";
Run Python code in a sandbox and return its output. The image sets the Python version and the packages the code can import. Files that one run writes stay in the sandbox for the next run.
Prerequisites
A Worker with a Durable Object that starts a container with the Durable Object scheduling policy. To create one, refer to Run a Linux command.
Run Python code
1. Create a file named `sales.py` with the Python code to run. In this example, the code uses `pandas`:
import pandas as pd
sales = pd.DataFrame({"city": ["Lisbon", "Austin", "Lisbon"], "units": [3, 5, 4]})
print(sales.groupby("city")["units"].sum())
Create a 
Dockerfile in your project root with Python and the packages the code can import:
FROM python:3.13-slim
RUN pip install --no-cache-dir numpy pandas matplotlib
WORKDIR /workspace
CMD ["sleep", "infinity"]
Installing packages in the image makes them available as soon as the sandbox starts, without Internet access in the sandbox.
In 
wrangler.jsonc, build the 
Dockerfile as a named image in your 
containers entry, then generate types:
{
	"containers": [
		{
			"class_name": "MyContainer",
			"scheduling_policy": "durable_object",
			"images": {
				"python": {
					"dockerfile": "./Dockerfile",
				},
			},
		},
	],
}
Add an inactivity timeout to your Durable Object. The constructor sets the timeout again when a restarted Durable Object finds the container running:
const INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000;
export class MyContainer extends DurableObject<Env> {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		const container = ctx.container;
		if (container?.running) {
			void ctx.blockConcurrencyWhile(() =>
				container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS),
			);
		}
	}
}
Then add a method that runs Python code:
export class MyContainer extends DurableObject<Env> {
	// ...
	async runPython(code: string) {
		const container = this.ctx.container;
		if (!container) {
			throw new Error("No container is configured");
		}
		if (!container.running) {
			container.start({
				image: container.images.python,
				// Block the code from reaching the Internet
				enableInternet: false,
			});
			await container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS);
		}
		// Each run is a new Python process, so variables do not carry over
		const process = await container.exec(
			[
				// GNU coreutils `timeout` stops code that runs longer than 60 seconds
				"timeout", "--kill-after=5", "60",
				// `python3 -` reads the code from standard input
				"python3", "-",
			],
			{
				stdin: new Response(code).body!,
				// Files that the code writes here stay until the instance stops
				cwd: "/workspace",
			},
		);
		const output = await process.output();
		const decoder = new TextDecoder();
		return {
			stdout: decoder.decode(output.stdout),
			// A Python exception prints its traceback here
			stderr: decoder.decode(output.stderr),
			// `124` or `137` if the code timed out, `1` if it raised an exception
			exitCode: output.exitCode,
		};
	}
}
For how 
timeout stops the processes that the code starts, refer to Stop the processes a command starts.
output() holds everything the code prints in the memory of the Durable Object. For code that prints a lot, stream the output instead.
Add a route to your Worker that runs the request body as Python code:
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);
		const match = /^\/sandboxes\/([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)\/python$/.exec(url.pathname);
		if (!match || request.method !== "POST") {
			return new Response("Not found", { status: 404 });
		}
		const sandbox = env.MY_CONTAINER.getByName(match[1]);
		return Response.json(await sandbox.runPython(await request.text()));
	},
} satisfies ExportedHandler<Env>;
The code can read every file in its sandbox, so give each user their own sandbox name, and authenticate callers first. For more information, refer to Sandbox security.
Deploy your Worker:
Run 
sales.py in a sandbox named 
ada. Replace the example hostname with the 
workers.dev URL that Wrangler prints:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/sandboxes/ada/python --data-binary @sales.py
{
	"stdout": "city\nAustin    5\nLisbon    7\nName: units, dtype: int64\n",
	"stderr": "",
	"exitCode": 0
}
Return a chart
To return an image, such as a 
matplotlib chart, have the code save it in 
/workspace, then read the file in another request:
Add a method to your Durable Object that reads a file from 
/workspace:
export class MyContainer extends DurableObject<Env> {
	// ...
	async readFile(name: string) {
		const container = this.ctx.container;
		if (!container?.running) {
			return null;
		}
		const process = await container.exec(["cat", "--", name], {
			cwd: "/workspace",
			stderr: "ignore",
		});
		const output = await process.output();
		return output.exitCode === 0 ? output.stdout : null;
	}
}
In the 
fetch() handler of your Worker, after the line that parses 
url, add a route that returns the chart:
const chart = /^\/sandboxes\/([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)\/chart\.png$/.exec(url.pathname);
if (chart) {
	const png = await env.MY_CONTAINER.getByName(chart[1]).readFile("chart.png");
	return png
		? new Response(png, { headers: { "Content-Type": "image/png" } })
		: new Response("Not found", { status: 404 });
}
Run code that saves a chart, then open 
/sandboxes/ada/chart.png in your browser:
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
plt.bar(["Austin", "Lisbon"], [5, 7])
plt.savefig("chart.png")
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/sandboxes/ada/python --data-binary @chart.py
matplotlib.use("Agg") draws without a display. For larger files and uploads, refer to Move files in and out of a sandbox.
Run another language
To run another language, change the base image and the command that reads standard input. For example, use 
FROM ruby:3.4-slim and 
["ruby", "-"], or 
FROM node:24-slim and 
["node", "-"].
Related resources
Build an AI code interpreter: run code that a model writes in a Dynamic Worker.
Stream command output: show output while long code runs.
Save and restore a sandbox with snapshots: keep files in 
/workspace after the instance stops.

Run tests from a Git repository
import {
PackageManagers,
Render,
Steps,
TypeScriptExample,
WranglerConfig,
} from "~/components";
Run the tests of a repository in a fresh sandbox. In this example, the Durable Object clones the repository, installs its dependencies, runs its test script, returns the result, and stops the instance.
Prerequisites
A Worker with a Durable Object that starts a container with the Durable Object scheduling policy. To create one, refer to Run a Linux command.
Run the test suite
Create a 
Dockerfile in the project root with Git and the runtime your tests need. This one adds Git to Debian Trixie with Node.js 24:
FROM node:24-trixie-slim
RUN apt-get update \
	&& apt-get install --yes --no-install-recommends ca-certificates git \
	&& rm -rf /var/lib/apt/lists/*
CMD ["sleep", "infinity"]
sleep infinity keeps the container running so that it can accept more 
exec() calls.
In 
wrangler.jsonc, build the 
Dockerfile as a named image in your 
containers entry:
{
	"containers": [
		{
			"class_name": "MyContainer",
			"scheduling_policy": "durable_object",
			"images": {
				"tests": {
					"dockerfile": "./Dockerfile",
				},
			},
		},
	],
}
Add a method to your Durable Object that clones a repository, installs its dependencies, and runs its tests:
export class MyContainer extends DurableObject<Env> {
	// ...
	async runTests(repository: string, revision: string) {
		const container = this.ctx.container;
		if (!container) {
			throw new Error("No container is configured");
		}
		container.start({
			image: container.images.tests,
			// `git` and `npm` need the Internet. Do not pass credentials into this sandbox
			enableInternet: true,
		});
		const decoder = new TextDecoder();
		const run = async (step: string, argv: string[], cwd?: string) => {
			// Limit each step to 10 minutes.
			const process = await container.exec(
				["timeout", "--kill-after=5", "600", ...argv],
				{ cwd },
			);
			const output = await process.output();
			return {
				step,
				stdout: decoder.decode(output.stdout),
				stderr: decoder.decode(output.stderr),
				exitCode: output.exitCode,
			};
		};
		try {
			const clone = await run("clone", [
				"git",
				"clone",
				"--depth=1",
				`--branch=${revision}`,
				"--",
				repository,
				"/workspace",
			]);
			if (clone.exitCode !== 0) {
				return clone;
			}
			const install = await run(
				"install",
				["npm", "ci", "--no-audit", "--no-fund"],
				"/workspace",
			);
			if (install.exitCode !== 0) {
				return install;
			}
			return await run("test", ["npm", "test", "--", "--silent"], "/workspace");
		} finally {
			if (container.running) {
				await container.destroy();
			}
		}
	}
}
-- stops 
git from reading a repository value that starts with 
- as an option.
A step that runs longer than 10 minutes returns exit code 
124, or 
137 if 
timeout also sends 
SIGKILL. 
timeout stops the step together with the processes it starts that stay in its process group. For more information, refer to Stop the processes a command starts. The 
finally block stops the instance after the run.
output() holds the whole output of a step in the memory of the Durable Object. For test suites that print a lot, stream the output instead.
enableInternet: true lets 
git and 
npm download the repository and its packages. It also lets the install and test scripts of the repository reach the Internet, so do not pass credentials into this sandbox. For more information, refer to Sandbox security.
Add a route to your Worker that runs the tests in a new sandbox:
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		if (request.method !== "POST") {
			return new Response("Not found", { status: 404 });
		}
		const sandbox = env.MY_CONTAINER.getByName(crypto.randomUUID());
		const result = await sandbox.runTests(
			"https://github.com/cloudflare/workers-oauth-provider.git",
			"v0.0.6",
		);
		return Response.json(result, {
			status: result.exitCode === 0 ? 200 : 500,
		});
	},
} satisfies ExportedHandler<Env>;
A random sandbox name gives each run a new instance, so one run cannot see files from another.
In this example, the Worker runs the tests of version 
v0.0.6 of the public 
workers-oauth-provider repository. Replace the repository, revision, and 
npm commands with your own. 
exec() does not start a shell, so keep each argument in its own array entry.
Deploy your Worker:
Send a 
POST request to the 
workers.dev URL that Wrangler prints:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev --request POST
The response includes the test output and exit code:
{
	"step": "test",
	"stdout": "...\n Test Files  1 passed (1)\n      Tests  37 passed (37)\n...",
	"stderr": "",
	"exitCode": 0
}
When a step fails, the Worker responds with 
500, and 
step names the step that failed.
Related resources
Stream command output: show test output while the tests run.
Save and restore a sandbox with snapshots: keep installed dependencies between runs.
Handle outbound traffic: allow only the Git server and package registry instead of the whole Internet.
Clone a private repository: clone with a token that stays in your Worker.

Stream command output
import { PackageManagers, Steps, TypeScriptExample } from "~/components";
Show the output of a command in a browser while the command runs. The Durable Object sends standard output and standard error as server-sent events, reports the exit code, and signals the command to stop when the client disconnects.
Prerequisites
A Worker with a Durable Object that starts a container with the Durable Object scheduling policy. To create one, refer to Run a Linux command.
Stream a command
Add a method to your Durable Object that runs a command and returns its output as an event stream:
export class MyContainer extends DurableObject<Env> {
	// ...
	async stream(argv: string[]): Promise<Response> {
		const container = this.ctx.container;
		if (!container) {
			throw new Error("No container is configured");
		}
		if (!container.running) {
			container.start({
				image: "cloudflare/debian-trixie",
				entrypoint: ["sleep", "infinity"],
				enableInternet: false,
			});
		}
		const process = await container.exec(argv);
		const { readable, writable } = new TransformStream<Uint8Array, Uint8Array>();
		const writer = writable.getWriter();
		const encoder = new TextEncoder();
		const send = (event: string, data: unknown) =>
			writer.write(
				encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`),
			);
		const forward = async (
			stream: ReadableStream<Uint8Array>,
			event: "stdout" | "stderr",
		) => {
			for await (const text of stream.pipeThrough(new TextDecoderStream())) {
				await send(event, text);
			}
		};
		let exited = false;
		const markExited = () => {
			exited = true;
		};
		process.exitCode.then(markExited, markExited);
		// Signaling a process that has exited records an internal error.
		const stop = () => {
			if (!exited) process.kill();
		};
		// Signal the process when the client disconnects.
		writer.closed.catch(stop);
		// Detect a disconnected client while the process writes nothing.
		const heartbeat = setInterval(() => {
			writer.write(encoder.encode(": keep-alive\n\n")).catch(() => {});
		}, 5_000);
		const pump = async () => {
			try {
				await Promise.all([
					forward(process.stdout!, "stdout"),
					forward(process.stderr!, "stderr"),
				]);
				await send("exit", { exitCode: await process.exitCode });
				await writer.close();
			} catch (error) {
				stop();
				// End the response, so a connected client does not wait forever.
				await writer.abort(error).catch(() => {});
			} finally {
				clearInterval(heartbeat);
			}
		};
		// Keep streaming after this method returns the response.
		void pump();
		return new Response(readable, {
			headers: {
				"Content-Type": "text/event-stream",
				"Cache-Control": "no-cache",
			},
		});
	}
}
The method returns the response before the command finishes. 
pump() then writes each chunk as the process produces it. 
pump() reads standard output and standard error at the same time, because a stream that nobody reads can block a process that keeps writing to it. 
TextDecoderStream keeps characters that span two chunks intact.
When the client disconnects, the next write fails and the method calls 
kill(), which sends 
SIGTERM to the command. A command can ignore 
SIGTERM; to enforce a limit, refer to Stop a command after a time limit. The keep-alive comment every five seconds makes that write happen while the command is silent.
Add a route to your Worker that streams a command your application chooses:
const build = [
	"sh",
	"-c",
	'for i in 1 2 3; do echo "step $i"; sleep 1; done; echo "warning: almost done" >&2; exit 3',
];
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);
		const match = /^\/sandboxes\/([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)\/build$/.exec(url.pathname);
		if (!match || request.method !== "GET") {
			return new Response("Not found", { status: 404 });
		}
		const sandbox = env.MY_CONTAINER.getByName(match[1]);
		return sandbox.stream(build);
	},
} satisfies ExportedHandler<Env>;
The example command writes a line each second, writes a warning to standard error, and exits with code 
3. Replace it with your build or test command. The Worker chooses the command instead of reading one from the request. For more information, refer to Sandbox security.
Deploy your Worker:
Stream the command in the sandbox named 
ada. Replace the example hostname with the 
workers.dev URL that Wrangler prints:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/sandboxes/ada/build --no-buffer
The events arrive about one second apart:
event: stdout
data: "step 1\n"
event: stdout
data: "step 2\n"
event: stdout
data: "step 3\n"
event: stderr
data: "warning: almost done\n"
event: exit
data: {"exitCode":3}
Read the stream in a browser
Each event has a type and a JSON-encoded 
data value. A 
stdout or 
stderr event can hold part of a line or several lines, so append the text instead of treating each event as a line. The 
exit event comes last. Lines that start with 
: are comments, which clients ignore.
The route answers 
GET requests, so a page can read it with 
EventSource:
const output = document.querySelector("pre");
const events = new EventSource("/sandboxes/ada/build");
for (const type of ["stdout", "stderr"]) {
	events.addEventListener(type, (event) => {
		output.textContent += JSON.parse(event.data);
	});
}
events.addEventListener("exit", (event) => {
	output.textContent += `\nExit code ${JSON.parse(event.data).exitCode}\n`;
	events.close();
});
EventSource reconnects when a stream ends, which would run the command again. The page calls 
close() on the 
exit event to prevent that.
Stop a command after a time limit
A disconnect signals only the process that 
exec() started. Processes that the command starts, such as the commands in an 
sh -c script, keep the output streams open until they exit. To stop a command and the processes it starts after a time limit, run it under GNU coreutils 
timeout:
const build = ["timeout", "--kill-after=5", "60", "sh", "-c", "npm test"];
The command exits with code 
124 when it runs longer than 60 seconds, or 
137 if 
timeout also sends 
SIGKILL. A process that moves to its own process group, for example with 
setsid, keeps running. For more information, refer to Stop the processes a command starts.
Related resources
Execute commands: combine standard error with standard output, send standard input, and handle exit codes.
Run background processes: commands that outlive the request.
exec()

Choose a sandbox environment
import { CardGrid, LinkTitleCard } from "
/components";
import { SandboxEnvironments } from "/components/react/sandbox/SandboxEnvironments";
A sandbox runs code that you did not write and do not trust, such as code that a model generates or the test suite of a repository. Cloudflare runs it in one of two environments: a Container, which runs a Linux image, or a Dynamic Worker, which runs JavaScript against methods that your Worker provides. Your Worker starts either one, and one Worker can use both.
What the code can use
Code in a Container can use everything in its Linux image: runtimes, packages, files, and the processes it starts.
Code in a Dynamic Worker can use the Workers runtime APIs, plus the modules, methods, and values that your Worker passes to it. It does not inherit the bindings, credentials, or data of your Worker. It can reach the Internet unless you set 
globalOutbound to 
null.
Your Worker keeps credentials and policy. It starts a Container, which runs a command in your Linux image and can use runtimes, packages, files, and processes. It also passes methods and values to a Dynamic Worker, which runs generated code and does not inherit your bindings, data, or credentials.
Use a Container when the code expects Linux
Most existing tools expect an operating system as well as a language runtime. 
npm test needs Node.js, dependencies on a filesystem, and child processes. A preview server keeps a process running and listens on a port. A compiler may need a toolchain or native binaries.
JavaScript code can need Linux too. A Dynamic Worker cannot start child processes or load native add-ons, and Workers implements some Node.js modules only in part. For what Workers supports, refer to Node.js compatibility.
Your Worker decides when the container starts, whether it can reach the Internet, and which HTTP requests reach it. The Agents sandbox tool uses a Container to run commands for an agent.
Use a Dynamic Worker when the code calls known methods
When code only needs to call methods that you define, such as a script against a known API, run it in a Dynamic Worker. Your Worker decides what each method can reach before it passes the method in.
For example, your Worker can pass a 
listPullRequests() method that works for one repository and keeps the API token. Generated code can filter the pull requests, but it cannot reach another repository or read the token. For more information, refer to Bindings.
Code Mode uses this for agents. The model writes JavaScript against typed methods, a Dynamic Worker runs it, and only the result returns to the model context.
load() creates a new Dynamic Worker. 
get() with a stable ID lets the runtime reuse a warm Dynamic Worker when the same code runs again. To give a generated application its own storage, use Durable Object facets. That storage does not give the application access to your other resources.
How each environment isolates code
A Container runs in a Firecracker microVM with its own kernel and network, which no other workload shares. Your image runs as a Linux container inside that VM.
V8, the JavaScript engine in Chrome, runs each Dynamic Worker in a sandbox that cannot read memory outside itself. The Workers runtime adds a process-level sandbox around it. For more information, refer to the Workers security model.
What you maintain
With a Container, you build and update the image. Existing tools run without changes, but the container must start before the first command runs. For more information, refer to Container cold starts.
With a Dynamic Worker, you write each method and decide what it returns. When generated code needs another operation, you add a method. The code that loads the Dynamic Worker lists everything the generated code can reach.
Use both in one application
A coding agent can answer questions about a repository through scoped methods in a Dynamic Worker. When the agent proposes a patch, the same Worker starts a Container and runs the test suite of the repository.
<LinkTitleCard
title="Run a Linux command"
href="/sandbox/get-started/"
icon="ph:terminal-window"
Post a command to a Worker and read stdout from Linux.
<LinkTitleCard
title="Run JavaScript"
href="/sandbox/get-started/dynamic-workers/"
icon="ph:code"
Post JavaScript to a Worker and read the sandboxed result.

Sandbox lifetime
import { SandboxLifetime } from "~/components/react/sandbox/SandboxLifetime";
A Linux sandbox is a Durable Object that starts and stops a container. Your Worker reaches the Durable Object by name, for example a session ID, and the same name always reaches the same Durable Object. When work arrives, the Durable Object calls 
this.ctx.container.start(), which starts a container instance: a Linux virtual machine that runs your image, with its own processes and its own disk.
The Durable Object and the instance last for different lengths of time. The Durable Object keeps its storage, such as session details or a snapshot ID, until your code deletes it. An instance runs only until something stops it, and its processes and the files on its disk end with it. The next 
start() creates a new instance.
This page follows a coding agent. The agent clones a repository, installs its dependencies, edits files, and starts a development server. Then it waits an hour for its next instruction and reaches the same sandbox by name. The files are still there if the instance kept running or the application saved a snapshot. The development server is still there only if the instance kept running.
The sandbox of the coding agent, from top to bottom: the name, the Durable Object, the instance, and a mounted R2 bucket. Durable Object storage keeps a snapshot ID. The instance runs the development server and holds the repository and edits on its disk. When the instance stops, its processes and disk files end. The name, the Durable Object, and the objects in the bucket remain. A new instance started from the snapshot has the repository and edits on its disk, and no development server runs until the agent starts it again.
Activity keeps an instance running
An instance keeps running while its Durable Object is active. The Durable Object is active while it handles a request, runs an alarm, streams a response, or holds open a WebSocket that it accepted with 
accept(). The browser terminal keeps a sandbox running this way, even when nobody types.
After the Durable Object becomes inactive, the instance keeps running for the time set with 
setInactivityTimeout(), up to 6 hours. A request that arrives within that time reaches the same instance, with its files and processes. Without a timeout, Cloudflare stops the instance shortly after the Durable Object becomes inactive.
Code that runs inside the instance does not count as activity. If no requests arrive, the instance stops when the inactivity timeout ends, even while a build, a test suite, or an agent task still runs inside it. A Durable Object alarm that runs more often than the timeout and checks the work keeps the instance running until the work ends. For an alarm that runs every minute, refer to Run background processes.
An idle instance is still billed
While an instance runs, Containers bill its memory and disk, whether or not anything inside it does work. After the instance stops, it is not billed. For the rates, refer to Containers pricing.
An inactivity timeout longer than the wait between requests keeps processes running through the wait, and you pay for the instance until the next request. A shorter timeout lets the instance stop. A snapshot then carries its files to the next instance, which starts its processes again. To keep its development server running through the hour, the coding agent needs a timeout longer than an hour, and pays for the instance for that hour.
The timeout does not survive a restart
A Durable Object restarts when it leaves memory and later runs its constructor again, for example after a deploy or between two alarms. Its instance can keep running through the restart. The restarted Durable Object starts without an inactivity timeout, so the instance stops shortly after the Durable Object becomes inactive.
The sandbox examples set the timeout after 
start(), and set it again in the constructor of the Durable Object when the instance is already running. For an example, refer to 
setInactivityTimeout().
What stops an instance
An instance stops when one of these happens:
The inactivity timeout ends.
Your Worker calls 
destroy().
The main process exits.
A platform event stops it, for example a server restart. Cloudflare does not guarantee that an instance runs for a set time.
The main process is the entrypoint passed to 
start(), or the default command of the image. When it exits, the instance stops, and every command started with 
exec() ends with it. The default command of 
cloudflare/debian-trixie exits right away, so the sandbox examples start that image with 
sleep infinity as the entrypoint, or run a web server as the main process.
When the inactivity timeout ends, every process in the instance receives 
SIGTERM, and Cloudflare stops the instance shortly after, whether or not the processes exit. 
destroy() stops the instance at once, with no time for processes to clean up. Do not rely on a 
SIGTERM handler to finish work. Save the files you need before the instance stops, for example in a snapshot.
Cloudflare does not wake the Durable Object when its instance stops. A pending 
monitor() call reports a stop only while the Durable Object is in memory. The call keeps the Durable Object in memory for up to 15 minutes from when the call starts. On compatibility dates before 
2026-10-01, the Durable Object leaves memory after its usual idle period instead, unless the Worker sets the 
durable_object_io_tasks_prevent_eviction flag. The inactivity timeout starts only after the Durable Object leaves memory, so the instance keeps running past the timeout and the Durable Object incurs duration charges until then. When the Durable Object leaves memory, the call ends without reporting the stop that follows.
To record each stop and its reason, refer to Run code when a sandbox stops.
Deploys keep instances running
Deploying a new version of your Worker restarts every Durable Object. A running instance keeps running, and the next request reaches the same instance, with its files and processes. Outbound handlers that the Durable Object set up with 
interceptOutboundHttp() remain in place and run the code of the new version.
A running instance keeps the image, entrypoint, and environment variables that it started with. 
start() throws while an instance runs, so a new image or new startup options apply only to instances that start after the deploy. To move a sandbox to a new image, stop its instance, for example with 
destroy(), and start a new one. The files and processes of the old instance end with it.
Requests, streamed responses, and WebSockets that a sandbox is handling during a deploy can keep running on the previous version. Until that work ends, the previous version can also handle new requests for the sandbox, so new code reaches a busy sandbox late. A deploy is therefore not a way to cancel work. The runtime can still shut down a Durable Object, so make clients such as a browser terminal connect again when their connection closes. For more information, refer to Shutdown behavior.
After the deploy, the instance keeps running for the inactivity timeout that the previous version set. The new version must set the timeout again, as described in The timeout does not survive a restart.
Container rollouts replace instances only in Container applications that use the default scheduling policy, so no rollout replaces a sandbox.
Snapshots carry files to the next instance
The disk of an instance holds the repository, installed packages, configuration files, and output written by commands. Its memory holds running processes, open terminals, and network connections. All of it ends when the instance stops, and the next instance starts from its image or from a snapshot.
:::note[Public beta]
Container snapshots are in public beta. The API and behavior may change.
:::
snapshotContainer() saves the writable root filesystem of a running instance. It does not save separately mounted filesystems, memory, or processes. Starting with a snapshot creates a new instance with the saved files, and the new instance runs its entrypoint. The processes that were running do not continue. The new instance reuses the same process IDs, so a process ID saved in a file can belong to another process after a restore. Files in 
/run are in memory, and a snapshot does not save them.
Your application decides when to save a snapshot. It stores the snapshot, for example in Durable Object storage, and passes it to the next 
start(). Cloudflare does not restore a snapshot on its own. Changes made after the last snapshot exist only in the current instance, and an instance can stop without warning, so save a snapshot after work that you need to keep.
A snapshot expires 30 days after it is created or last restored. To keep files longer, copy them to a bucket.
The repository, dependencies, and edits of the coding agent return from a snapshot. The development server does not, so the agent starts it again. To save and restore a workspace, refer to Save and restore a sandbox with snapshots. To save a sandbox each time it stops for inactivity, refer to Save a sandbox automatically.
Mounted buckets outlive every instance
Files in a mounted R2 bucket are objects in that bucket. They remain after every instance stops, and other sandboxes and Workers with access to the bucket can read them. A snapshot does not include mounted directories, and a mount ends with its instance, so each new instance mounts the bucket again.
Use a snapshot for files that belong to one continuing workspace. Use a bucket for files that other systems read, or that must outlive the workspace. To mount a bucket, refer to Mount an R2 bucket.
Related resources
Sandbox security
Durable Object Container API
Durable Object alarms

Sandbox security
import { SandboxCredentials } from "~/components/react/sandbox/SandboxCredentials";
A sandbox runs code you do not trust, such as code that a model generates, a user writes, or a dependency brings in. Cloudflare isolates the sandbox from your Worker and from other sandboxes. For more information about that isolation, refer to Sandboxes on Cloudflare.
Isolation does not limit what the code does inside its own sandbox. Assume that the code uses everything it can reach there, including the files, credentials, and network access that your Worker provides.
Everything in one sandbox is shared
Every process in a Container runs on the same Linux system. The processes can read the same files, see each other, and connect to the same 
localhost ports. Code loaded into one Dynamic Worker shares its memory in the same way.
A separate Linux user does not keep a command away from files. In a deployed sandbox, every process has the same Linux capabilities as 
root, so file permissions do not restrict it, and it can switch back to 
root. For more information, refer to the 
exec() 
user option.
The sandbox is therefore the smallest unit of trust. When two users share a sandbox, each user's code can read the other's work. A sandbox for each user, or for each job, keeps one user's code away from another user's files and credentials.
Code can read what you put in its sandbox
For example, a coding agent clones a private repository, installs its dependencies, and runs its tests. If your Worker puts a token in the clone URL, Git saves that URL in the 
.git/config file of the repository. The tests, and every dependency they load, run with the same access as the agent. Any of that code can read the token.
Inside the sandbox of a coding agent, the agent runs 
git pull, and code from a test dependency reads 
.git/config. With the token in the clone URL, the dependency reads the token from that file. With the token in your Worker, the file holds no token, your Worker adds the token to requests for 
github.com, and 
git pull still works.
Environment variables, command arguments, and files your Worker writes work the same way. Once a value is in the sandbox, all the code there can read it and send it anywhere the sandbox can reach.
Credentials are safer outside the sandbox. A Container can send its request without the credential, and an outbound handler in your Worker adds the credential after the request leaves the sandbox. Add the credential only to HTTPS requests. The handler fetches with the scheme that the container used, so a credential added to a plain HTTP request crosses the Internet unencrypted.
A Dynamic Worker can receive a method that uses the credential in your Worker and returns only the result. The method and the outbound handler each decide which requests to make, so they limit what the code can do with the service. For both patterns, refer to Call an authenticated API from a sandbox.
The sandbox name decides what a request reaches
A Container keeps its files while it runs. A snapshot saves those files, including a token in 
.git/config, and restoring the snapshot brings them back. Your Worker reaches the same sandbox whenever it calls 
getByName() with the same name.
The name decides which sandbox, and which saved files, a request reaches. It does not show who sent the request. Authenticate the caller in your Worker, and derive the sandbox name from that identity. Reusing a name or a snapshot for someone else gives them the earlier user's files. The how-to guides read the name from the URL only to keep the examples short.
For more information about what a sandbox keeps between instances, refer to Sandbox lifetime.
Every opening is also a way out
A Container starts with 
enableInternet: false by default, so it cannot reach the Internet. Only requests that an outbound handler in your Worker intercepts leave it. A Dynamic Worker has the network access of your Worker unless you load it with 
globalOutbound: null, which makes 
fetch() and 
connect() throw.
Each destination you allow gives the code a way to send out what it can read. If you turn on Internet access so that 
npm install can download packages, a dependency can also send the token to any server. An outbound handler in your Worker can allow the package registry and block every other destination.
Keep Internet access off when you use an outbound handler. A handler receives only the connections that its intercept covers. With Internet access on, every other connection goes out directly. To route requests through your Worker, refer to 
interceptOutboundHttps() for Containers and Egress control for Dynamic Workers.
Output carries the same risk
Results, files, and HTTP responses from a sandbox come from the code you do not trust. They need the same checks as user input before your application stores them, acts on them, or shows them to someone else.
A web preview carries more risk, because it runs in the visitor's browser. When your Worker forwards a page from a sandbox, the page runs under the hostname that served it. On your application hostname, the page can use your application cookies and call its APIs. Serve previews on a separate domain that your application does not use, so that its cookies never reach the page. For an example, refer to Serve previews on their own hostnames.
Related resources
Choose a sandbox environment
Sandbox lifetime
Call an authenticated API from a sandbox
Preview a web application
Workers security model

Back up a directory to R2
import {
PackageManagers,
Render,
Steps,
TypeScriptExample,
WranglerConfig,
} from "~/components";
The 
DirectoryBackup class from 
@cloudflare/sandbox saves one directory as one object in your R2 bucket and restores it as ordinary files. A backup restores after the instance stops or after you deploy a new image. R2 keeps each backup until you delete it. In this example, the directory is a project in 
/workspace/project.
Prerequisites
A Worker with a Durable Object that starts a container with the Durable Object scheduling policy. To create one, refer to Run a Linux command.
Back up and restore a directory
Install the package:
Copy the helper binary into your image. If your project has no 
Dockerfile, create one in your project root:
FROM node:24-trixie-slim
COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim
RUN mkdir /workspace
CMD ["sleep", "infinity"]
Use the 
cloudflare/sandbox tag that matches the installed package version. Replace the 
FROM line with the base image your commands need.
Create a bucket for the backups:
If Wrangler offers to add the bucket to your configuration, answer no. The next step adds the binding.
In 
wrangler.jsonc, add the 
nodejs_compat flag, build the 
Dockerfile as a named image in your 
containers entry, and bind the bucket:
{
	"compatibility_flags": ["nodejs_compat"],
	"containers": [
		{
			"class_name": "MyContainer",
			"scheduling_policy": "durable_object",
			"images": {
				"workspace": {
					"dockerfile": "./Dockerfile",
				},
			},
		},
	],
	"r2_buckets": [
		{
			"binding": "BACKUPS",
			"bucket_name": "sandbox-backups",
		},
	],
}
Then generate types:
In 
src/index.ts, export 
DirectoryBackupGateway, and update the 
MyContainer class so that its methods start the 
workspace image and create 
DirectoryBackup:
import {
	DirectoryBackup,
	type DirectoryBackupRecord,
} from "@cloudflare/sandbox";
import { DurableObject } from "cloudflare:workers";
export { DirectoryBackupGateway } from "@cloudflare/sandbox";
const project = "/workspace/project";
const INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000;
export class MyContainer extends DurableObject<Env> {
	private readonly container: Container;
	private readonly backups: DirectoryBackup;
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		const container = ctx.container;
		if (!container) {
			throw new Error("No container is configured");
		}
		this.container = container;
		this.backups = new DirectoryBackup(
			container,
			ctx.exports.DirectoryBackupGateway,
			{ binding: "BACKUPS", prefix: "backups/" },
		);
		// A restarted Durable Object sets the timeout again.
		if (container.running) {
			void ctx.blockConcurrencyWhile(() =>
				container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS),
			);
		}
	}
	private async startSandbox(): Promise<void> {
		if (!this.container.running) {
			this.container.start({
				image: this.container.images.workspace,
				enableInternet: false,
			});
			await this.container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS);
		}
	}
}
The container sends the backup through 
DirectoryBackupGateway, which writes it to the 
BACKUPS bucket. The container never receives R2 credentials, and it can reach only the object of the operation in progress.
The constructor creates one 
DirectoryBackup object for the Durable Object, because 
this.ctx.container stays the same object for as long as the Durable Object runs.
Add a method to 
MyContainer that adds a line to a file in the project and returns the file, so you can check what a restore brings back:
export class MyContainer extends DurableObject<Env> {
	// ...
	async note(line?: string) {
		await this.startSandbox();
		const script = line
			? `mkdir -p ${project} && printf "%s\n" "$1" >> ${project}/notes.txt && cat ${project}/notes.txt`
			: `cat ${project}/notes.txt`;
		const process = await this.container.exec(["sh", "-c", script, "sh", line ?? ""]);
		const output = await process.output();
		return new TextDecoder().decode(output.stdout);
	}
}
Add a method to 
MyContainer that backs up the project and stores the backup record:
export class MyContainer extends DurableObject<Env> {
	// ...
	async backup() {
		await this.startSandbox();
		const backup = await this.backups.backup({ dir: project });
		await this.ctx.storage.put(`backup:${backup.id}`, backup);
		return { id: backup.id, size: backup.size };
	}
}
backup() returns a record with the ID, size, and SHA-256 of the object. The package keeps no list of backups. The Durable Object stores the record and looks it up by ID, so a request cannot point a restore at another object in the bucket.
Stop the commands that write to the directory before you call 
backup(). A file that changes during the backup can be saved partly old and partly new.
Add a method to 
MyContainer that looks up a record and restores it:
export class MyContainer extends DurableObject<Env> {
	// ...
	async restore(id: string) {
		const backup = await this.ctx.storage.get<DirectoryBackupRecord>(
			`backup:${id}`,
		);
		if (!backup) {
			return false;
		}
		await this.startSandbox();
		await this.backups.restore(backup);
		return true;
	}
}
restore() replaces the directory and removes files that are not in the backup. Before it replaces anything, it checks the object against the SHA-256 in the record. When 
restore() throws 
SandboxFileError or 
SandboxBackupError, it leaves the directory as it was. If the object no longer exists, 
restore() throws 
SandboxBackupError with the code 
BACKUP_NOT_FOUND. If the object does not match the record, the code is 
BACKUP_INTEGRITY. For every error, refer to DirectoryBackup errors.
Replace the default export of your Worker with routes that write a note, back up the project, and restore a backup:
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);
		const match =
			/^\/sandboxes\/([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)\/(notes|backups)(?:\/([0-9a-f-]{36})\/restore)?$/.exec(
				url.pathname,
			);
		if (!match) {
			return new Response("Not found", { status: 404 });
		}
		const [, name, resource, id] = match;
		const sandbox = env.MY_CONTAINER.getByName(name);
		if (resource === "notes" && !id) {
			const line = request.method === "POST" ? await request.text() : undefined;
			return new Response(await sandbox.note(line));
		}
		if (resource === "backups" && request.method === "POST") {
			if (!id) {
				return Response.json(await sandbox.backup(), { status: 201 });
			}
			return (await sandbox.restore(id))
				? new Response(null, { status: 204 })
				: new Response("Backup not found", { status: 404 });
		}
		return new Response("Method not allowed", { status: 405 });
	},
} satisfies ExportedHandler<Env>;
A backup holds every file in the directory, including credentials written in the sandbox. Authenticate callers first, so other people cannot back up or restore the files of another sandbox. For more information, refer to Sandbox security.
Deploy your Worker:
In the sandbox named 
ada, write a note and back up the project. Replace the example hostname with the 
workers.dev URL that Wrangler prints:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/sandboxes/ada/notes --data "Keep this line."
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/sandboxes/ada/backups --request POST
The backup responds with its ID and its size in bytes, such as 
{"id":"<BACKUP_ID>","size":217}.
Write a second note, restore the backup, then read the notes. Replace 
<BACKUP_ID> with the ID from the response:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/sandboxes/ada/notes --data "Lose this line."
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/sandboxes/ada/backups/<BACKUP_ID>/restore --request POST
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/sandboxes/ada/notes
The restore responds with 
204, and the notes are back to the state of the backup:
Keep this line.
Leave out files
To leave out files, pass patterns in 
.gitignore syntax, relative to the directory. 
node_modules/ matches a directory with that name at any depth, and 
/build matches only at the top:
const backup = await this.backups.backup({
	dir: project,
	exclude: ["node_modules/", "/build"],
	// Also apply the `.gitignore` files in the directory and `.git/info/exclude`,
	// without `git` in the image
	gitignore: true,
});
Delete a backup
To delete a backup, delete its object and its record:
export class MyContainer extends DurableObject<Env> {
	// ...
	async deleteBackup(id: string) {
		const backup = await this.ctx.storage.get<DirectoryBackupRecord>(
			`backup:${id}`,
		);
		if (backup) {
			// `delete()` does not need a running container
			await this.backups.delete(backup);
			await this.ctx.storage.delete(`backup:${id}`);
		}
	}
}
An object lifecycle rule that expires objects under 
backups/ also deletes backups. The rule leaves their records, and restoring one of those backups throws 
BACKUP_NOT_FOUND.
A backup that fails does not leave an object. If the Durable Object restarts during a backup, the incomplete multipart upload stays in the bucket until the default lifecycle rule of the bucket aborts it after seven days.
Related resources
DirectoryBackup API: what a backup keeps, one operation at a time per container, cancellation, and every error.
Save and restore a sandbox with snapshots: keep the whole filesystem instead of one directory.
Mount an R2 bucket: read and write files that other systems use.

Work with files in a sandbox
The 
Files class from 
@cloudflare/sandbox moves files between your Worker and a running sandbox, and provides common file system operations. For more information, refer to Move files in and out of a sandbox.
Each sandbox name maps to a Durable Object, which starts a Linux instance when needed. Stopping the instance deletes the files on its disk. For more information, refer to Sandbox lifetime.
Persistence
You can keep files from a sandbox in several ways, from a snapshot of the root filesystem to one directory kept in R2:
Goal
Guide
Trade-off
Continue an agent workspace in a later session
Save and restore a sandbox with snapshots
Saves the root filesystem, but not mounted directories
Keep a workspace without explicit save calls
Save a sandbox automatically
Same as snapshots, plus an alarm in your Durable Object
Keep a project across images, or beyond 30 days
Back up a directory to R2
Saves one directory, and your Durable Object stores each backup record
Share job inputs and outputs with other systems
Mount an R2 bucket
Renames, locks, and permissions do not work as they do on a local disk
Combine approaches
Snapshots do not include mounted directories, so a sandbox can use both. For example, a coding agent can keep its repository and dependencies in a snapshot, and write results to a mounted bucket for other Workers to read. For more information, refer to Sandbox lifetime.
Related resources
Sandbox lifetime
Sandbox security
Files API
DirectoryBackup API
S3Mount API

Move files in and out of a sandbox
import {
PackageManagers,
Render,
Steps,
TypeScriptExample,
WranglerConfig,
} from "~/components";
This guide streams an uploaded file into a sandbox, compresses it with 
gzip, and streams the compressed file back to the caller.
The 
Files class from 
@cloudflare/sandbox reads and writes files in a running Linux instance, and 
exec() runs the command. 
Files does not start the instance, so your Durable Object starts it before each file operation.
Prerequisites
A Worker project from Run a Linux command. This project uses a Durable Object that starts a container with the Durable Object scheduling policy.
Run a command on an uploaded file
Install the package:
To give 
Files its helper binary, create a 
Dockerfile in the project root. If you already have one, add the 
COPY line to it:
FROM node:24-trixie-slim
COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim
RUN mkdir /workspace
CMD ["sleep", "infinity"]
The 
cloudflare/sandbox tag must match the installed package version. A mismatch causes 
SandboxProtocolError. Replace the 
FROM line with the base image your commands need.
To build the image, add the 
nodejs_compat flag to 
wrangler.jsonc and replace the 
containers entry:
{
	"compatibility_flags": ["nodejs_compat"],
	"containers": [
		{
			"class_name": "MyContainer",
			"scheduling_policy": "durable_object",
			"images": {
				"workspace": {
					"dockerfile": "./Dockerfile",
				},
			},
		},
	],
}
The 
workspace key names the image. Your code starts it as 
container.images.workspace.
To start an instance before each file operation, replace 
src/index.ts with a 
MyContainer class that has a 
startSandbox() method:
import { Files } from "@cloudflare/sandbox";
import { DurableObject } from "cloudflare:workers";
const workspace = "/workspace";
const INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000;
export class MyContainer extends DurableObject<Env> {
	private readonly container: Container;
	private readonly files: Files;
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		const container = ctx.container;
		if (!container) {
			throw new Error("No container is configured");
		}
		this.container = container;
		this.files = new Files(container);
		// A restarted Durable Object sets the timeout again.
		if (container.running) {
			void ctx.blockConcurrencyWhile(() =>
				container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS),
			);
		}
	}
	// Files does not start an instance, so start one before each operation.
	private async startSandbox(): Promise<void> {
		if (!this.container.running) {
			this.container.start({
				image: this.container.images.workspace,
				enableInternet: false,
			});
			await this.container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS);
		}
	}
}
The constructor creates one 
Files object for the Durable Object, because 
this.ctx.container stays the same object for as long as the Durable Object runs. 
startSandbox() starts the 
workspace image when no instance is running, and sets the inactivity timeout after 
start(). For more information, refer to Sandbox lifetime.
To write the upload, run the command, and return the output file, add a 
compress() method to 
MyContainer:
export class MyContainer extends DurableObject<Env> {
	// ...
	async compress(upload: ReadableStream<Uint8Array>): Promise<Response> {
		await this.startSandbox();
		const name = crypto.randomUUID();
		await this.files.writeFile(name, upload, { cwd: workspace });
		const process = await this.container.exec(["gzip", "--force", name], {
			cwd: workspace,
		});
		const output = await process.output();
		if (output.exitCode !== 0) {
			throw new Error(new TextDecoder().decode(output.stderr));
		}
		return this.files.readFile(`${name}.gz`, { cwd: workspace });
	}
}
writeFile() streams the upload into the file, and 
readFile() returns a 
Response that streams the output file back. Neither method holds a whole file in the memory of the Durable Object. 
output() holds only what 
gzip prints, and that output counts toward the memory limit.
A Linux failure, such as a full disk, throws 
SandboxFileError. Its 
code holds the Linux error name, such as 
ENOSPC. To handle other errors, refer to Files errors.
To send uploads to 
compress(), add a default export to 
src/index.ts:
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);
		const match = /^\/sandboxes\/([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)\/compress$/.exec(url.pathname);
		if (!match || request.method !== "POST" || !request.body) {
			return new Response("Not found", { status: 404 });
		}
		const sandbox = env.MY_CONTAINER.getByName(match[1]);
		return sandbox.compress(request.body);
	},
} satisfies ExportedHandler<Env>;
:::caution
This route reads the sandbox name from the URL, so any caller can reach any sandbox. In production, derive the name from the authenticated caller. For more information, refer to Sandbox security.
:::
Deploy your Worker:
To test the Worker, upload a file to the sandbox named 
ada and save the response. Replace the hostname with the 
workers.dev URL that Wrangler prints:
printf 'Ada Lovelace\nGrace Hopper\n' | curl \
  https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/sandboxes/ada/compress \
  --data-binary @- \
  --fail-with-body \
  --output names.txt.gz
Decompress the response:
gunzip --stdout names.txt.gz
Ada Lovelace
Grace Hopper
List, rename, and remove files
Files has methods for other file operations. Each method accepts the same 
cwd option as 
writeFile() and 
readFile():
Method
Use it to
readDirectory()
List directory entries
stat()
Read the type, size, owner, and timestamps of a path
mkdir()
Create a directory
rename()
Rename or move a file or directory
remove()
Delete a file, or a directory with 
recursive: true
Compressed files stay in 
/workspace until the instance stops. To delete a file sooner, call 
remove() after the caller has read the response.
For more information, refer to Files API.
Accept paths from callers
Some applications let callers choose paths, such as a file browser. 
Files does not restrict which paths it opens. To keep a request inside one directory, check each path before you pass it to 
Files.
This example adds a 
download() method that accepts only relative paths without 
.., and returns 
404 for a missing file:
import { SandboxFileError } from "@cloudflare/sandbox";
import { DurableObject } from "cloudflare:workers";
const workspace = "/workspace";
// Accept only relative paths that stay inside cwd.
function workspacePath(path: string): string | null {
	if (
		path === "" ||
		path.startsWith("/") ||
		path.includes("\0") ||
		path.split("/").includes("..")
	) {
		return null;
	}
	return path;
}
export class MyContainer extends DurableObject<Env> {
	// ...
	async download(path: string): Promise<Response> {
		const relativePath = workspacePath(path);
		if (!relativePath) {
			return new Response("Invalid path", { status: 400 });
		}
		await this.startSandbox();
		try {
			return await this.files.readFile(relativePath, { cwd: workspace });
		} catch (error) {
			if (SandboxFileError.is(error) && error.code === "ENOENT") {
				return new Response("Not found", { status: 404 });
			}
			throw error;
		}
	}
}
:::caution
The check applies only to the path in the request. It does not isolate files inside the sandbox. Code in the sandbox can still create a symbolic link in 
/workspace that points elsewhere in the sandbox.
The 
user option, such as 
user: "1000:1000", does not narrow access either. It sets the owner of files that 
Files creates. The helper can still open files that the user has no permission for.
For more information, refer to Sandbox security.
:::
Related resources
Files API: every method, including 
readDirectory(), 
rename(), and 
remove().
Save and restore a sandbox with snapshots: keep the files after the instance stops.
Mount an R2 bucket: write files that other systems read.

Mount an R2 bucket
import {
PackageManagers,
Render,
Steps,
TypeScriptExample,
WranglerConfig,
} from "~/components";
The 
S3Mount class from 
@cloudflare/sandbox mounts one prefix of a bucket as a directory with 
s3fs. Your Worker keeps the R2 credentials and signs each storage request. In this example, a command reads an input file from the mount and writes a digest next to it.
Prerequisites
A Worker with a Durable Object that starts a container with the Durable Object scheduling policy. To create one, refer to Run a Linux command.
An R2 bucket, and an R2 API token with the Object Read & Write permission for that bucket only. The examples use a bucket named 
sandbox-artifacts.
Mount a bucket prefix
Install the package:
Create a 
Dockerfile in your project root with FUSE, 
s3fs, and the 
sandbox-shim binary that 
S3Mount uses:
FROM node:24-trixie-slim
RUN apt-get update \
	&& apt-get install -y --no-install-recommends ca-certificates fuse3 s3fs \
	&& rm -rf /var/lib/apt/lists/*
COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim
CMD ["sleep", "infinity"]
Use the 
cloudflare/sandbox tag that matches the 
@cloudflare/sandbox version you installed.
In 
wrangler.jsonc, turn on 
nodejs_compat, add the endpoint and name of the bucket as variables, declare the credentials as secrets, and build the 
Dockerfile as a named image. Replace 
<ACCOUNT_ID> with your Cloudflare account ID:
{
	"compatibility_flags": ["nodejs_compat"],
	"vars": {
		"S3_ENDPOINT": "https://<ACCOUNT_ID>.r2.cloudflarestorage.com",
		"S3_BUCKET": "sandbox-artifacts",
	},
	"secrets": {
		"required": ["S3_ACCESS_KEY_ID", "S3_SECRET_ACCESS_KEY"],
	},
	"containers": [
		{
			"class_name": "MyContainer",
			"scheduling_policy": "durable_object",
			"images": {
				"artifacts": {
					"dockerfile": "./Dockerfile",
				},
			},
		},
	],
}
secrets.required adds the secrets to the generated types and makes 
wrangler deploy fail when they are missing. To mount a bucket from another S3-compatible service, change 
S3_ENDPOINT and 
S3_BUCKET, and use the credentials for that service.
Generate types, then add the Access Key ID and Secret Access Key from the R2 API token as secrets:
Import 
S3Mount, and export 
S3Gateway from the main module of your Worker:
import { S3Mount } from "@cloudflare/sandbox";
// S3Mount sends storage requests from the sandbox to this entrypoint.
export { S3Gateway } from "@cloudflare/sandbox";
s3fs in the sandbox sends each storage request to an address that the container intercepts. The intercept delivers the request to 
S3Gateway in your Worker. 
S3Gateway checks that the request stays within the bucket, prefix, and access mode of the mount. Then it signs the request with your credentials and sends it to R2.
Add a constructor to your Durable Object. It creates one 
S3Mount object, and sets the inactivity timeout again when a restarted Durable Object finds the container running:
const INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000;
export class MyContainer extends DurableObject<Env> {
	private readonly container: Container;
	private readonly mounts: S3Mount;
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		const container = ctx.container;
		if (!container) {
			throw new Error("No container is configured");
		}
		this.container = container;
		this.mounts = new S3Mount(container, ctx.exports.S3Gateway);
		if (container.running) {
			void ctx.blockConcurrencyWhile(() =>
				container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS),
			);
		}
	}
}
this.ctx.container stays the same object for as long as the Durable Object runs, so one 
S3Mount object serves every container that the Durable Object starts.
Then add a method that starts the sandbox and mounts the prefix for the job:
export class MyContainer extends DurableObject<Env> {
	// ...
	private async mountArtifacts(job: string) {
		if (!this.container.running) {
			this.container.start({
				image: this.container.images.artifacts,
				enableInternet: false,
			});
			await this.container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS);
		}
		await this.mounts.mount({
			mountPath: "/mnt/artifacts",
			source: {
				type: "s3",
				endpoint: this.env.S3_ENDPOINT,
				region: "auto",
				bucket: this.env.S3_BUCKET,
				credentials: {
					type: "static",
					accessKeyId: this.env.S3_ACCESS_KEY_ID,
					secretAccessKey: this.env.S3_SECRET_ACCESS_KEY,
				},
			},
			keyPrefix: `jobs/${job}`,
			access: "read-write",
		});
	}
}
Any process in the sandbox can read, change, or delete every object under the prefix. Mount the narrowest prefix the job needs, and use 
access: "read-only" when the job only reads. The sandbox receives placeholder credentials, because 
s3fs requires a key pair. The mount works with 
enableInternet: false. For short-lived credentials, refer to Credentials.
Calling 
mount() again with the same settings reuses the existing mount. Each new mount adds an outbound intercept, and 
unmount() does not remove it. An instance supports a limited number of intercepts. Give each job its own sandbox name instead of mounting a new prefix in the same instance.
Add a method that runs a command in the mounted directory:
export class MyContainer extends DurableObject<Env> {
	// ...
	async digest(job: string) {
		await this.mountArtifacts(job);
		const process = await this.container.exec(
			// The command reads `input.txt` from R2 through the mount
			// and writes `input.sha256` next to it
			["sh", "-c", "sha256sum input.txt > input.sha256"],
			{ cwd: "/mnt/artifacts" },
		);
		const output = await process.output();
		return {
			exitCode: output.exitCode,
			stderr: new TextDecoder().decode(output.stderr),
		};
	}
}
The mount maps files to objects. Renames, locks, and permissions do not work as they do on a local disk. Write results that other systems read to the mount. Keep working files, such as dependencies and build output, on the sandbox disk. For more information, refer to Mounted file behavior.
Add a method that unmounts the prefix and stops the sandbox:
async finish() {
	if (!this.container.running) {
		return;
	}
	await this.mounts.unmount("/mnt/artifacts");
	await this.container.destroy();
}
Call 
finish() only after every job that writes to the mount has ended. 
unmount() denies storage requests before it unmounts, so a process that still writes loses those writes. If a process still uses the directory, 
unmount() throws 
SandboxS3MountError with code 
S3_MOUNT_BUSY and requests stay denied. Stop the process, then call 
unmount() again.
Add routes to your Worker that run a job and finish it:
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);
		const match = /^\/jobs\/([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)(\/digest)?$/.exec(url.pathname);
		if (!match) {
			return new Response("Not found", { status: 404 });
		}
		const [, job, digest] = match;
		const sandbox = env.MY_CONTAINER.getByName(job);
		if (digest && request.method === "POST") {
			return Response.json(await sandbox.digest(job));
		}
		if (!digest && request.method === "DELETE") {
			await sandbox.finish();
			return new Response(null, { status: 204 });
		}
		return new Response("Method not allowed", { status: 405 });
	},
} satisfies ExportedHandler<Env>;
Authenticate callers first, so other people cannot run jobs or read their results. For more information, refer to Sandbox security.
Deploy your Worker:
Upload an input file for the job named 
ada, run the job, and read the result from R2. Replace the example hostname with the 
workers.dev URL that Wrangler prints:
echo "artifact input" > input.txt
npx wrangler r2 object put sandbox-artifacts/jobs/ada/input.txt --file input.txt --remote
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/jobs/ada/digest --request POST
npx wrangler r2 object get sandbox-artifacts/jobs/ada/input.sha256 --remote --pipe
The job responds with 
{"exitCode":0,"stderr":""}, and R2 has the digest:
<SHA256_DIGEST>  input.txt
Unmount the prefix and stop the sandbox:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/jobs/ada --request DELETE
Develop locally
Under 
wrangler dev, the container runs in Docker on your machine, and 
S3Gateway runs in your local Worker. Point the mount at an S3-compatible server on your machine instead of R2. In this example, the server is MinIO. FUSE needs Docker in a virtual machine, such as Docker Desktop, or rootless Linux Docker with 
/dev/fuse. For more information, refer to FUSE support.
Start MinIO and create a bucket:
docker run --detach --name minio --publish 9000:9000 minio/minio server /data
docker exec minio sh -c "mc alias set local http://localhost:9000 minioadmin minioadmin && mc mb local/sandbox-artifacts"
Create a 
.dev.vars file in your project root. Its values override the variables and secrets under 
wrangler dev:
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
Start the development server:
Upload an input file, run the job, and read the result from MinIO:
echo "artifact input" | docker exec --interactive minio mc pipe local/sandbox-artifacts/jobs/ada/input.txt
curl http://localhost:8787/jobs/ada/digest --request POST
docker exec minio mc cat local/sandbox-artifacts/jobs/ada/input.sha256
Related resources
S3Mount API: every option and error.
Artifact workspace example: a deployable Worker that mounts a prefix for each sandbox and processes a file in it.
Save and restore a sandbox with snapshots: keep files on the sandbox disk between instances. Snapshots do not include mounted directories.
S3 API compatibility: the S3 operations that R2 supports.

Save a sandbox automatically
import { PackageManagers, Steps } from "~/components";
An alarm in the Durable Object saves a Container snapshot of an idle sandbox and stops it. While the sandbox is in use, the alarm also saves checkpoints. The next request starts the sandbox from the last snapshot.
:::note[Public beta]
Container snapshots are in public beta. Features and behavior may change.
:::
Prerequisites
A Worker with a Durable Object that starts a container with the Durable Object scheduling policy. To create one, refer to Run a Linux command.
Save a sandbox before it stops
At the top of 
src/index.ts, define how often the Durable Object checks the sandbox, how long a sandbox can go without requests, and how often to save a sandbox that is in use:
const CHECK_INTERVAL_MS = 60 * 1000;
const IDLE_LIMIT_MS = 10 * 60 * 1000;
const CHECKPOINT_INTERVAL_MS = 15 * 60 * 1000;
const INACTIVITY_TIMEOUT_MS = 5 * 60 * 1000;
The inactivity timeout is longer than the check interval, so the instance keeps running between checks. If the checks stop, the timeout still stops the instance, and the sandbox keeps the files from its last save.
In 
MyContainer, add a constructor. It sets the inactivity timeout again when a restarted Durable Object finds the container running, so the instance does not stop before the next check:
constructor(ctx: DurableObjectState, env: Env) {
	super(ctx, env);
	const container = ctx.container;
	if (container?.running) {
		void ctx.blockConcurrencyWhile(() =>
			container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS),
		);
	}
}
Then replace 
exec(). It starts a new instance from the stored snapshot when there is one, schedules the first check, and records activity:
busy = 0;
async exec(argv: string[]) {
	const container = this.ctx.container;
	if (!container) {
		throw new Error("No container is configured");
	}
	if (!container.running) {
		const snapshotId = await this.ctx.storage.get<string>("snapshotId");
		container.start({
			...(snapshotId
				? { containerSnapshot: { id: snapshotId } }
				: { image: "cloudflare/debian-trixie" }),
			entrypoint: ["sleep", "infinity"],
			enableInternet: false,
		});
		await this.ctx.storage.put("savedAt", Date.now());
	}
	await container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS);
	if ((await this.ctx.storage.getAlarm()) === null) {
		await this.ctx.storage.setAlarm(Date.now() + CHECK_INTERVAL_MS);
	}
	this.busy++;
	await this.ctx.storage.put("lastActivity", Date.now());
	try {
		const process = await container.exec(argv);
		const output = await process.output();
		return {
			stdout: new TextDecoder().decode(output.stdout),
			exitCode: output.exitCode,
		};
	} finally {
		this.busy--;
		await this.ctx.storage.put("lastActivity", Date.now());
	}
}
savedAt holds when the files were last saved or restored. 
busy counts the running commands, and the Durable Object does not save or stop a sandbox while a command runs. A request in progress keeps the Durable Object in memory, so 
busy does not need storage. If the stored snapshot cannot be restored, 
start() fails. To handle that failure, refer to Save and restore a sandbox with snapshots.
Add a method that saves a snapshot, and an alarm handler that saves and stops an idle sandbox and saves a checkpoint of a sandbox in use:
async save() {
	const startedAt = Date.now();
	const snapshot = await this.ctx.container!.snapshotContainer({
		name: "auto",
	});
	await this.ctx.storage.put({ snapshotId: snapshot.id, savedAt: startedAt });
}
async alarm() {
	const container = this.ctx.container;
	if (!container?.running) {
		return;
	}
	const lastActivity = (await this.ctx.storage.get<number>("lastActivity")) ?? 0;
	const savedAt = (await this.ctx.storage.get<number>("savedAt")) ?? 0;
	const idle = this.busy === 0 && Date.now() - lastActivity > IDLE_LIMIT_MS;
	const checkpoint =
		this.busy === 0 &&
		lastActivity > savedAt &&
		Date.now() - savedAt > CHECKPOINT_INTERVAL_MS;
	if (idle || checkpoint) {
		try {
			await this.save();
		} catch (error) {
			// Keep the instance and try again at the next check.
			console.error("Saving the sandbox failed", error);
			await container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS);
			await this.ctx.storage.setAlarm(Date.now() + CHECK_INTERVAL_MS);
			return;
		}
	}
	const activeDuringSave =
		this.busy > 0 ||
		(await this.ctx.storage.get<number>("lastActivity")) !== lastActivity;
	if (idle && !activeDuringSave) {
		await container.destroy("idle");
		return;
	}
	await container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS);
	await this.ctx.storage.setAlarm(Date.now() + CHECK_INTERVAL_MS);
}
A save takes a few seconds, and the instance keeps running commands during it. If a request arrives during the save, the alarm does not stop the instance. A later snapshot saves the files written during the save. If a save fails, the handler keeps the instance running and schedules the next check, which tries again. If a deploy interrupts a save, the runtime runs the alarm again.
Checkpoints limit what a sandbox loses when something other than the alarm stops it, such as the inactivity timeout after the checks stop. The sandbox restores the last checkpoint, without the changes made after it.
A Durable Object has one alarm. If your class already has an 
alarm() handler, merge the idle and checkpoint checks into it, and set the alarm to the earliest time that any check needs. For more information, refer to Alarms.
A snapshot saves the writable root filesystem. It does not include mounted directories, memory, or running processes. A background process that writes a file during a save can leave part of that file in the snapshot.
Each save creates a new snapshot. The Durable Object container API has no method to delete a snapshot. A snapshot expires 30 days after it is created or last restored. To save fewer snapshots, increase 
CHECKPOINT_INTERVAL_MS or remove checkpoints.
Add a method that returns the state of the sandbox:
async status() {
	return {
		running: this.ctx.container?.running ?? false,
		snapshotId: (await this.ctx.storage.get<string>("snapshotId")) ?? null,
	};
}
Add routes to your Worker that run a command in a named sandbox and return its state:
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);
		const match = /^\/sandboxes\/([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)$/.exec(url.pathname);
		if (!match) {
			return new Response("Not found", { status: 404 });
		}
		const sandbox = env.MY_CONTAINER.getByName(match[1]);
		if (request.method === "GET") {
			return Response.json(await sandbox.status());
		}
		const { argv } = (await request.json()) as { argv: string[] };
		return Response.json(await sandbox.exec(argv));
	},
};
Snapshots can contain credentials or other sensitive files written in the sandbox. Authenticate callers first, and give each user their own sandbox name. For more information, refer to Sandbox security.
Deploy the Worker:
Write a file in the sandbox named 
ada. Replace the example hostname with the 
workers.dev URL that Wrangler prints:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/sandboxes/ada --json '{"argv":["sh","-c","mkdir -p /workspace && echo hello > /workspace/notes.txt"]}'
Send no requests to 
ada for 11 minutes, then read its state:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/sandboxes/ada
{
	"running": false,
	"snapshotId": "<SNAPSHOT_ID>"
}
The sandbox saved a snapshot and stopped. The next request starts a new instance from the snapshot. Read the file:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/sandboxes/ada --json '{"argv":["cat","/workspace/notes.txt"]}'
{
	"stdout": "hello\n",
	"exitCode": 0
}
Related resources
Save and restore a sandbox with snapshots: save when your application decides, copy a sandbox, and start a sandbox over.
Sandbox lifetime: what a snapshot saves, and what a restored instance starts with.
Run code when a sandbox stops
snapshotContainer()

Save and restore a sandbox with snapshots
import { PackageManagers, Steps, TypeScriptExample } from "~/components";
A Durable Object saves the filesystem of a sandbox as a Container snapshot, stores the snapshot ID, and starts the next instance from the snapshot. In this example, the sandbox keeps a notes file in 
/workspace.
:::note[Public beta]
Container snapshots are in public beta. Features and behavior may change.
:::
Prerequisites
A Worker with a Durable Object that starts a container with the Durable Object scheduling policy. To create one, refer to Run a Linux command.
Save and restore a sandbox
Add an inactivity timeout to your Durable Object. The constructor sets the timeout again when a restarted Durable Object finds the container running:
const INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000;
export class MyContainer extends DurableObject<Env> {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		const container = ctx.container;
		if (container?.running) {
			void ctx.blockConcurrencyWhile(() =>
				container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS),
			);
		}
	}
}
Then start the container from the stored snapshot when there is one:
export class MyContainer extends DurableObject<Env> {
	// ...
	private async startSandbox(): Promise<Container> {
		const container = this.ctx.container;
		if (!container) {
			throw new Error("No container is configured");
		}
		if (!container.running) {
			const snapshotId = await this.ctx.storage.get<string>("snapshotId");
			container.start({
				...(snapshotId
					? { containerSnapshot: { id: snapshotId } }
					: { image: "cloudflare/debian-trixie" }),
				entrypoint: ["sleep", "infinity"],
				enableInternet: false,
			});
			await container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS);
		}
		return container;
	}
}
If the stored snapshot cannot be restored, the request fails with an error such as 
Snapshot "<SNAPSHOT_ID>" was not found. Later requests fail the same way until the stored ID changes. The method does not fall back to the image, because the sandbox would then start with an empty workspace.
Add a method that runs one operation at a time, and a method that saves the filesystem and stops the instance:
export class MyContainer extends DurableObject<Env> {
	// ...
	private queue: Promise<unknown> = Promise.resolve();
	// Runs each operation after the previous one finishes.
	private exclusive<T>(operation: () => Promise<T>): Promise<T> {
		const result = this.queue.then(operation);
		this.queue = result.catch(() => {});
		return result;
	}
	async save() {
		return this.exclusive(async () => {
			const container = await this.startSandbox();
			const snapshot = await container.snapshotContainer({ name: "workspace" });
			await this.ctx.storage.put("snapshotId", snapshot.id);
			await container.destroy();
			return { snapshotId: snapshot.id, size: snapshot.size };
		});
	}
}
A command that writes a file while the snapshot runs can succeed and then disappear when 
destroy() stops the instance. 
exclusive() makes every operation that touches the disk wait for the save, and the save wait for them. Run each such method through it.
A snapshot saves the writable root filesystem. It does not include mounted directories, memory, or running processes. Finish writing files before you save. For more information about what a restored instance starts with, refer to Sandbox lifetime.
Add a method that adds a line to a file and returns the file, so you can check what a restore brings back:
export class MyContainer extends DurableObject<Env> {
	// ...
	async note(line?: string) {
		return this.exclusive(async () => {
			const container = await this.startSandbox();
			const script = line
				? 'mkdir -p /workspace && printf "%s\n" "$1" >> /workspace/notes.txt && cat /workspace/notes.txt'
				: "cat /workspace/notes.txt";
			const process = await container.exec(["sh", "-c", script, "sh", line ?? ""]);
			const output = await process.output();
			return new TextDecoder().decode(output.stdout);
		});
	}
}
Add routes to your Worker that write a note, save the sandbox, and read the notes:
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);
		const match = /^\/sandboxes\/([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)\/(notes|snapshot)$/.exec(
			url.pathname,
		);
		if (!match) {
			return new Response("Not found", { status: 404 });
		}
		const [, name, action] = match;
		const sandbox = env.MY_CONTAINER.getByName(name);
		if (action === "snapshot" && request.method === "POST") {
			return Response.json(await sandbox.save());
		}
		if (action === "notes" && request.method === "POST") {
			return new Response(await sandbox.note(await request.text()));
		}
		if (action === "notes") {
			return new Response(await sandbox.note());
		}
		return new Response("Method not allowed", { status: 405 });
	},
} satisfies ExportedHandler<Env>;
Snapshots can contain credentials or other sensitive files written in the sandbox. Authenticate callers first, so other people cannot read or restore the files of another sandbox. For more information, refer to Sandbox security.
Deploy your Worker:
Write a note in the sandbox named 
ada, save the sandbox, then read the notes. Replace the example hostname with the 
workers.dev URL that Wrangler prints:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/sandboxes/ada/notes --data "Continue from this checkpoint."
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/sandboxes/ada/snapshot --request POST
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/sandboxes/ada/notes
The save responds with the snapshot ID and its size in bytes, such as 
{"snapshotId":"<SNAPSHOT_ID>","size":123456}. The last request starts a new instance from the snapshot, and the note is back:
Continue from this checkpoint.
Copy a sandbox
A snapshot ID restores in any Durable Object of the same class. To copy the files of one sandbox to a new sandbox, store the snapshot ID in the Durable Object of the new sandbox:
Add methods to your Durable Object that return the stored snapshot ID and store another one:
export class MyContainer extends DurableObject<Env> {
	// ...
	async snapshotId() {
		return (await this.ctx.storage.get<string>("snapshotId")) ?? null;
	}
	async useSnapshot(snapshotId: string) {
		return this.exclusive(async () => {
			// Replacing a running instance would discard files it has not saved.
			if (this.ctx.container?.running) {
				return false;
			}
			await this.ctx.storage.put("snapshotId", snapshotId);
			return true;
		});
	}
}
Add a route to your Worker that copies one sandbox to another:
if (action === "copy" && request.method === "POST") {
	const from = url.searchParams.get("from") ?? "";
	const snapshotId = await env.MY_CONTAINER.getByName(from).snapshotId();
	if (!snapshotId || !(await sandbox.useSnapshot(snapshotId))) {
		return new Response("Cannot copy", { status: 409 });
	}
	return new Response(null, { status: 204 });
}
Add 
copy to the actions in the route pattern. A copy receives every file in the snapshot, so copy only between sandboxes that belong to the same user.
Copy 
ada to 
grace, then read the notes from 
grace:
curl "https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/sandboxes/grace/copy?from=ada" --request POST
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/sandboxes/grace/notes
Continue from this checkpoint.
From this point, each sandbox changes its own files.
Start a sandbox over
To discard the files of a sandbox, destroy its instance and delete the stored snapshot ID. The next request starts from the image:
export class MyContainer extends DurableObject<Env> {
	// ...
	async reset() {
		return this.exclusive(async () => {
			if (this.ctx.container?.running) {
				await this.ctx.container.destroy();
			}
			await this.ctx.storage.delete("snapshotId");
		});
	}
}
Deleting the stored ID does not delete the snapshot, so a sandbox that copied it can still restore it until the snapshot expires.
Related resources
Save a sandbox automatically: save before a sandbox stops for inactivity, and save checkpoints while it is in use.
Back up a directory to R2: keep one directory in your own bucket instead of the whole filesystem.
Checkpoint workspace example: a deployable Worker that saves, restores, and copies sandboxes.
Sandbox lifetime
Durable Object container API

Build a coding agent runner
import {
FileTree,
PackageManagers,
Render,
Steps,
TypeScriptExample,
WranglerConfig,
} from "~/components";
In this tutorial, you will build a Worker that runs a coding agent on a GitHub repository in a Linux sandbox. You send a prompt, the agent edits the repository inside the sandbox, and you read its changes as a diff. The runner uses Claude Code. The pages in Coding agents switch it to other agents.
Claude Code calls Anthropic models through AI Gateway. Your Worker adds the gateway token to those requests, so the token never enters the sandbox. The sandbox can reach only your gateway and 
github.com.
When you finish, you can ask the agent to add a file to a repository and read its change:
diff --git a/NOTES.md b/NOTES.md
new file mode 100644
index 0000000..95da11e
--- /dev/null
+++ b/NOTES.md
@@ -0,0 +1 @@
+This repository is a minimal test/example repo containing only a "Hello World!" README file.
You will learn how to:
Keep model credentials in your Worker while an agent runs in a sandbox.
Allow a sandbox to reach only the hostnames a task needs.
Run a task that lasts several minutes in the background and keep the sandbox running until it ends.
Read the outcome and changes of the agent after the task ends.
Prerequisites
You also need:
An authenticated AI Gateway and a gateway token with the Run permission.
Anthropic credentials in AI Gateway, either Unified Billing credits or an Anthropic API key stored as a provider key.
Your Cloudflare account ID.
1. Create the project
Create a Worker project:
<PackageManagers
type="create"
pkg="cloudflare@latest"
args={"sandbox-coding-agent --category=hello-world --type=hello-world --lang=ts --no-deploy --no-git --no-agents"}
/>
Change into the project directory:
cd sandbox-coding-agent
Install the 
@cloudflare/sandbox package and Zod:
Create a 
Dockerfile in your project root:
FROM node:24-trixie-slim
RUN apt-get update \
	&& apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
	&& rm -rf /var/lib/apt/lists/*
# The install script from the Claude Code package puts its native binary in place
RUN npm install --global @anthropic-ai/claude-code@2.1.308
COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim
WORKDIR /workspace
# Keep the container running between requests
CMD ["sleep", "infinity"]
Install everything the agent needs in the image, because the sandbox cannot download packages at run time.
Pin the Claude Code version. Its command-line flags and event format can change between releases. Use the 
cloudflare/sandbox tag that matches the 
@cloudflare/sandbox version you installed.
Replace 
wrangler.jsonc. Replace 
<ACCOUNT_ID> with your account ID, and 
default with your gateway ID if it is different:
{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "sandbox-coding-agent",
	"main": "src/index.ts",
	"compatibility_date": "$today",
	"compatibility_flags": ["nodejs_compat"],
	"observability": {
		"enabled": true,
	},
	"upload_source_maps": true,
	"vars": {
		"AI_GATEWAY_ACCOUNT_ID": "<ACCOUNT_ID>",
		"AI_GATEWAY_ID": "default",
		"MODEL": "claude-sonnet-5",
	},
	"secrets": {
		"required": ["AI_GATEWAY_TOKEN"],
	},
	"containers": [
		{
			"class_name": "AgentSandbox",
			"scheduling_policy": "durable_object",
			"images": {
				"agent": {
					"dockerfile": "./Dockerfile",
				},
			},
		},
	],
	"durable_objects": {
		"bindings": [
			{
				"class_name": "AgentSandbox",
				"name": "SANDBOX",
			},
		],
	},
	"exports": {
		"AgentSandbox": {
			"type": "durable-object",
			"storage": "sqlite",
		},
	},
}
Each sandbox is an 
AgentSandbox Durable Object with its own container. Wrangler builds the 
Dockerfile when you deploy, and the Durable Object starts the built image as 
this.ctx.container.images.agent. 
MODEL is an Anthropic model ID that your gateway can serve. 
secrets.required makes 
wrangler deploy fail if the gateway token is missing.
Generate types for the bindings, variables, and secret:
In the next three sections, you create 
src/outbound.ts and 
src/sandbox.ts and replace 
src/index.ts. The tutorial adds or replaces these files:
Dockerfile
wrangler.jsonc
src
outbound.ts
sandbox.ts
index.ts
2. Allow only the gateway and GitHub
Create 
src/outbound.ts. The sandbox sends every HTTP request on port 
80 and HTTPS request on port 
443 through this entrypoint in your Worker. Without Internet access, the sandbox cannot reach other ports:
import { WorkerEntrypoint } from "cloudflare:workers";
const gatewayHost = "gateway.ai.cloudflare.com";
export class Outbound extends WorkerEntrypoint<Env> {
	async fetch(request: Request): Promise<Response> {
		const url = new URL(request.url);
		const gatewayPath = `/v1/${this.env.AI_GATEWAY_ACCOUNT_ID}/${this.env.AI_GATEWAY_ID}`;
		if (url.protocol !== "https:") {
			return new Response(`${url.hostname} is reachable only over HTTPS\n`, {
				status: 403,
			});
		}
		if (
			url.hostname === gatewayHost &&
			(url.pathname === gatewayPath ||
				url.pathname.startsWith(`${gatewayPath}/`))
		) {
			const headers = new Headers(request.headers);
			headers.delete("x-api-key");
			headers.set(
				"cf-aig-authorization",
				`Bearer ${this.env.AI_GATEWAY_TOKEN}`,
			);
			return fetch(new Request(request, { headers }));
		}
		if (url.hostname === "github.com") {
			return fetch(request);
		}
		return new Response(
			`${url.hostname} is not reachable from this sandbox\n`,
			{ status: 403 },
		);
	}
}
The entrypoint allows two destinations:
Requests to your gateway under your account ID and gateway ID. The Worker removes the placeholder API key that Claude Code sends and adds the gateway token. AI Gateway then calls Anthropic with the credentials it holds. If the placeholder stays, AI Gateway forwards it to Anthropic, and the model request fails.
Requests to 
github.com, so Git can clone public repositories.
The entrypoint allows both destinations over HTTPS only. The Worker fetches with the scheme the container used, so a plain HTTP request to the gateway would send the gateway token unencrypted. Every other request gets a 
403 response, so Claude Code cannot install packages from npm or fetch web pages while it works.
To allow another destination, add it to this entrypoint. Each destination you add is another way for data to leave the sandbox. For more information, refer to Sandbox security.
3. Run Claude Code in the sandbox
Create 
src/sandbox.ts. The 
AgentSandbox Durable Object clones a repository, runs one Claude Code task at a time, and reports the task state and the repository diff:
import { Files, SandboxFileError } from "@cloudflare/sandbox";
import { DurableObject } from "cloudflare:workers";
import { z } from "zod";
const repositoryDirectory = "/workspace/repo";
const taskDirectory = "/workspace/task";
const eventsPath = `${taskDirectory}/stdout.log`;
const stderrPath = `${taskDirectory}/stderr.log`;
const exitCodePath = `${taskDirectory}/exit-code`;
const pidPath = `${taskDirectory}/pid`;
const inactivityTimeout = 30 * 60 * 1000;
const taskCheckInterval = 60 * 1000;
const taskKey = "task";
const caPath = "/etc/cloudflare/certs/cloudflare-containers-ca.crt";
// The CA alone replaces the system trust store. This works because
// Outbound intercepts every HTTPS request from the container.
const trustEnv = {
	NODE_EXTRA_CA_CERTS: caPath,
	GIT_SSL_CAINFO: caPath,
	CURL_CA_BUNDLE: caPath,
	SSL_CERT_FILE: caPath,
};
// Runs the command in its own process group. Records its process ID when
// it starts and its exit code when it ends.
const taskScript = `dir=$1; shift
setsid sh -c 'echo "$$ $(cat /proc/sys/kernel/random/boot_id)" >"$0/pid"; exec "$@"' \\
	"$dir" "$@" >"$dir/stdout.log" 2>"$dir/stderr.log"
echo "$?" >"$dir/exit-code.tmp" && mv "$dir/exit-code.tmp" "$dir/exit-code"`;
// Succeeds while the process in the file runs and started in this instance.
const taskRunningScript = `read -r pid boot <"$1" &&
	[ "$boot" = "$(cat /proc/sys/kernel/random/boot_id)" ] &&
	kill -0 "$pid"`;
const ResultEvent = z.object({
	type: z.literal("result"),
	subtype: z.string(),
	is_error: z.boolean(),
	result: z.string().optional(),
});
export type TaskStatus =
	| { state: "none" }
	| { state: "running" }
	| { state: "lost" }
	| { state: "succeeded"; result: string }
	| { state: "failed"; error: string };
export type CommandResult = {
	exitCode: number;
	stdout: string;
	stderr: string;
};
export class AgentSandbox extends DurableObject<Env> {
	private readonly container: Container;
	private readonly files: Files;
	private setup: Promise<void> | undefined;
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		const container = ctx.container;
		if (!container) {
			throw new Error("No container is configured");
		}
		this.container = container;
		this.files = new Files(container);
		if (container.running) {
			void ctx.blockConcurrencyWhile(() =>
				container.setInactivityTimeout(inactivityTimeout),
			);
		}
	}
	async cloneRepository(
		repository: string,
		ref: string | undefined,
	): Promise<CommandResult> {
		await this.startSandbox();
		const branch = ref === undefined ? [] : ["--branch", ref];
		return this.run(
			[
				"git",
				"clone",
				"--depth",
				"1",
				...branch,
				"--",
				repository,
				repositoryDirectory,
			],
			"/workspace",
			trustEnv,
		);
	}
	startTask(prompt: string): Promise<"started" | "busy"> {
		return this.ctx.blockConcurrencyWhile(async () => {
			await this.startSandbox();
			if ((await this.taskStatus()).state === "running") {
				return "busy";
			}
			await this.files.remove(taskDirectory, { recursive: true, force: true });
			await this.files.mkdir(taskDirectory);
			await this.container.exec(
				[
					"/bin/sh",
					"-c",
					taskScript,
					"agent",
					taskDirectory,
					...this.agentCommand(prompt),
				],
				{
					cwd: repositoryDirectory,
					env: { ...trustEnv, ...this.agentEnv() },
					stdout: "ignore",
					stderr: "ignore",
				},
			);
			this.ctx.storage.kv.put(taskKey, "started");
			await this.ctx.storage.setAlarm(Date.now() + taskCheckInterval);
			return "started";
		});
	}
	async alarm(): Promise<void> {
		if (!this.container.running) {
			return;
		}
		if ((await this.taskStatus()).state === "running") {
			await this.ctx.storage.setAlarm(Date.now() + taskCheckInterval);
			return;
		}
		this.ctx.storage.kv.delete(taskKey);
	}
	async readTask(): Promise<TaskStatus> {
		if (!this.container.running) {
			return this.ctx.storage.kv.get(taskKey) === undefined
				? { state: "none" }
				: { state: "lost" };
		}
		return this.taskStatus();
	}
	async readDiff(): Promise<CommandResult> {
		await this.startSandbox();
		return this.run(
			["/bin/sh", "-c", "git add --intent-to-add . && git diff HEAD"],
			repositoryDirectory,
			{},
		);
	}
	private agentCommand(prompt: string): string[] {
		return [
			"claude",
			"--print",
			"--output-format",
			"stream-json",
			"--verbose",
			"--dangerously-skip-permissions",
			"--no-session-persistence",
			"--model",
			this.env.MODEL,
			"--",
			prompt,
		];
	}
	private agentEnv(): Record<string, string> {
		return {
			ANTHROPIC_BASE_URL: `https://gateway.ai.cloudflare.com/v1/${this.env.AI_GATEWAY_ACCOUNT_ID}/${this.env.AI_GATEWAY_ID}/anthropic`,
			ANTHROPIC_API_KEY: "provided-by-worker",
			CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1",
			IS_SANDBOX: "1",
		};
	}
	private async startSandbox(): Promise<void> {
		// Set up each new container, and a running container
		// after this Durable Object restarts.
		if (this.setup === undefined || !this.container.running) {
			this.setup = this.setUpSandbox().catch((error) => {
				this.setup = undefined;
				throw error;
			});
		}
		await this.setup;
	}
	private async setUpSandbox(): Promise<void> {
		if (!this.container.running) {
			this.ctx.storage.kv.delete(taskKey);
			this.container.start({
				image: this.container.images.agent,
				instance: "standard-1",
				enableInternet: false,
			});
		}
		try {
			await this.container.interceptAllOutboundHttp(this.ctx.exports.Outbound);
			await this.container.interceptOutboundHttps(
				"*",
				this.ctx.exports.Outbound,
			);
			await this.container.setInactivityTimeout(inactivityTimeout);
		} catch (error) {
			// The next request starts a new container.
			await this.container.destroy();
			throw error;
		}
	}
	private async taskStatus(): Promise<TaskStatus> {
		const exitCode = await this.readOptionalText(exitCodePath);
		if (exitCode !== undefined) {
			return this.outcome(Number.parseInt(exitCode, 10));
		}
		const pid = await this.readOptionalText(pidPath);
		if (pid === undefined) {
			// The task writes its process ID right after it starts.
			return this.ctx.storage.kv.get(taskKey) === undefined
				? { state: "none" }
				: { state: "running" };
		}
		const probe = await this.run(
			["/bin/sh", "-c", taskRunningScript, "probe", pidPath],
			"/",
			{},
		);
		if (probe.exitCode === 0) {
			return { state: "running" };
		}
		// The task can finish after the first read, so read the exit code
		// again.
		const lateExitCode = await this.readOptionalText(exitCodePath);
		if (lateExitCode !== undefined) {
			return this.outcome(Number.parseInt(lateExitCode, 10));
		}
		return { state: "lost" };
	}
	private async outcome(exitCode: number): Promise<TaskStatus> {
		let result: z.infer<typeof ResultEvent> | undefined;
		const events = await this.files.readFile(eventsPath);
		for await (const line of readLines(events.body)) {
			const parsed = ResultEvent.safeParse(parseJson(line));
			if (parsed.success) {
				result = parsed.data;
			}
		}
		if (result === undefined) {
			const stderr = (await this.readOptionalText(stderrPath)) ?? "";
			return {
				state: "failed",
				error: `claude exited with ${exitCode}: ${stderr.slice(-2000)}`,
			};
		}
		if (result.is_error) {
			return { state: "failed", error: result.result ?? result.subtype };
		}
		return { state: "succeeded", result: result.result ?? "" };
	}
	private async readOptionalText(path: string): Promise<string | undefined> {
		try {
			return await (await this.files.readFile(path)).text();
		} catch (error) {
			if (SandboxFileError.is(error) && error.code === "ENOENT") {
				return undefined;
			}
			throw error;
		}
	}
	private async run(
		command: string[],
		cwd: string,
		env: Record<string, string>,
	): Promise<CommandResult> {
		const process = await this.container.exec(command, { cwd, env });
		const output = await process.output();
		const decoder = new TextDecoder();
		return {
			exitCode: output.exitCode,
			stdout: decoder.decode(output.stdout),
			stderr: decoder.decode(output.stderr),
		};
	}
}
function parseJson(line: string): unknown {
	try {
		return JSON.parse(line);
	} catch {
		return undefined;
	}
}
async function* readLines(
	body: ReadableStream<Uint8Array> | null,
): AsyncGenerator<string> {
	if (body === null) {
		return;
	}
	const decoder = new TextDecoder();
	let buffered = "";
	for await (const chunk of body) {
		buffered += decoder.decode(chunk, { stream: true });
		const lines = buffered.split("\n");
		buffered = lines.pop() ?? "";
		yield* lines;
	}
	buffered += decoder.decode();
	if (buffered !== "") {
		yield buffered;
	}
}
Only 
ResultEvent, 
agentCommand(), 
agentEnv(), and 
outcome() are specific to Claude Code. The other pages in Coding agents replace those parts to run a different agent in the same Worker.
Start the sandbox
startSandbox() starts the container from the image Wrangler built, with no direct Internet access. In this example, the container uses the 
standard-1 instance type. Choose a size that fits your agent and your repositories.
After each start, 
startSandbox() routes HTTP and HTTPS requests from the container on ports 
80 and 
443 to the 
Outbound entrypoint. The interception ends with the container, so 
startSandbox() registers it on every start. For more information, refer to 
interceptOutboundHttps().
running is 
true as soon as 
start() returns, before the interception is registered. A request that arrives during setup waits for the same 
setUpSandbox() call, so no command runs before the interception is in place. If a setup step fails, 
setUpSandbox() stops the container, and the next request starts a new one.
A deploy restarts the Durable Object and can stop 
setUpSandbox() after 
start(). The restarted Durable Object runs 
setUpSandbox() again for the container that is already running. Registering an interception again replaces the earlier one, so the container gets its interception before the next command.
Containers re-signs HTTPS traffic from the container with a Cloudflare certificate authority, so the 
Outbound entrypoint can read it. The 
trustEnv variables point Git, Node.js, and other tools at that certificate. The Durable Object passes them to every command that makes HTTPS requests. 
SSL_CERT_FILE, 
CURL_CA_BUNDLE, and 
GIT_SSL_CAINFO replace the system trust store with that one certificate, which works only because the 
Outbound entrypoint receives every HTTPS request. If you copy them to a class that intercepts some hostnames only, add the certificate to the system trust store instead. For more information, refer to Trust the CA certificate.
Run Claude Code in the background
A Claude Code task can run for several minutes, longer than a request should wait. 
startTask() starts the task and returns. The client then checks the task state with later requests.
Claude Code runs without its own permission prompts, because the sandbox limits what its commands can reach. The command sets these options:
--print runs Claude Code without an interactive terminal.
--output-format stream-json --verbose writes one JSON event per line, including a final 
result event.
--dangerously-skip-permissions lets Claude Code run commands and edit files without asking. Claude Code requires 
IS_SANDBOX=1 to allow this as 
root.
ANTHROPIC_BASE_URL sends model requests to the Anthropic endpoint of your gateway.
ANTHROPIC_API_KEY is a placeholder. Claude Code does not start without an API key, and the 
Outbound entrypoint removes the key from each request.
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC turns off update checks, telemetry, and error reporting, so Claude Code calls only your gateway.
If the repository has a 
CLAUDE.md file, Claude Code reads it, so the instructions in that file apply to the task.
The process writes its output to files instead of sending it back to the Durable Object. A process with piped output receives 
SIGPIPE after the request that started it ends, which stops Claude Code in the middle of its task.
taskScript is the 
RUN script from Run background processes. 
setsid starts Claude Code in its own process group, and the script records the process ID of Claude Code when it starts. When Claude Code exits, the script writes the exit code to a temporary file and then renames it, so the Durable Object never reads a partial exit code.
The task files live in 
/workspace/task, outside the repository, so they do not appear in the diff.
When two requests start a task at the same time, 
blockConcurrencyWhile() runs them one after the other. The second request sees the running task and returns 
busy.
Keep the sandbox running
A running process does not keep the container running, so 
startTask() schedules an alarm that checks the task every minute until it ends. Each check keeps the container running. For more information, refer to Sandbox lifetime.
Read the outcome
The task has one of these states:
running while the Claude Code process exists.
succeeded with the final reply from Claude Code.
failed with an error message.
lost when the process or its container stopped before Claude Code recorded an exit code.
none when no task has run in this container.
Claude Code exits successfully even when a model request fails. The outcome comes from the 
is_error field of the final 
result event instead of the exit code. The events file comes from the sandbox, so the Durable Object validates each event with Zod before it reads it. When there is no 
result event, the task fails with the end of the standard error output from Claude Code.
While no exit code exists, the Durable Object runs 
kill -0 to check whether the process still exists. The command runs through 
sh, because 
kill is a shell built-in and the slim image has no separate 
kill binary. If the process is gone, the Durable Object reads the exit code again, because the task can finish between the two reads. Only a process that ended without an exit code is 
lost.
The process ID file also records the boot ID, which changes in every instance. If you restore the workspace from a snapshot, the file comes back, and the new instance reuses the same process IDs. The check ignores a process ID from another instance, so a task that was running when the snapshot was taken is 
lost.
readDiff() marks new files with 
git add --intent-to-add so that the diff includes them. 
git diff HEAD compares the files with the checked-out commit, so the diff also includes changes that the agent staged.
4. Route requests
Replace 
src/index.ts with the following Worker. It exports both classes and maps each route to a method on the sandbox named in the URL:
import { z } from "zod";
export { Outbound } from "./outbound";
export { AgentSandbox } from "./sandbox";
const sandboxName = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
// Linux rejects a command argument of 128 KiB or more, including its NUL byte.
const maxPromptBytes = 128 * 1024 - 1;
const RepositoryRequest = z.object({
	url: z.url({ protocol: /^https$/, hostname: /^github\.com$/ }),
	ref: z.string().min(1).optional(),
});
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);
		const match = /^\/sandboxes\/([^/]+)\/(repository|task|diff)$/.exec(
			url.pathname,
		);
		if (!match) {
			return new Response("Not found", { status: 404 });
		}
		const [, name, resource] = match;
		if (!sandboxName.test(name)) {
			return new Response(
				"The sandbox name must be 1-63 lowercase letters, digits, or hyphens, with no hyphen at either end",
				{ status: 400 },
			);
		}
		const sandbox = env.SANDBOX.getByName(name);
		try {
			if (resource === "repository" && request.method === "POST") {
				const body = RepositoryRequest.safeParse(
					await request.json().catch(() => null),
				);
				if (!body.success) {
					return new Response(
						'Send {"url": "https://github.com/OWNER/REPOSITORY"}',
						{ status: 400 },
					);
				}
				const result = await sandbox.cloneRepository(
					body.data.url,
					body.data.ref,
				);
				return Response.json(result, {
					status: result.exitCode === 0 ? 200 : 502,
				});
			}
			if (resource === "task" && request.method === "POST") {
				const prompt = await request.text();
				if (prompt.trim() === "") {
					return new Response("Send a prompt", { status: 400 });
				}
				if (new TextEncoder().encode(prompt).byteLength > maxPromptBytes) {
					return new Response("Send a prompt smaller than 128 KiB", {
						status: 413,
					});
				}
				if ((await sandbox.startTask(prompt)) === "busy") {
					return new Response("A task is already running", { status: 409 });
				}
				return Response.json({ state: "running" }, { status: 202 });
			}
			if (resource === "task" && request.method === "GET") {
				return Response.json(await sandbox.readTask());
			}
			if (resource === "diff" && request.method === "GET") {
				const result = await sandbox.readDiff();
				if (result.exitCode !== 0) {
					return Response.json(result, { status: 502 });
				}
				return new Response(result.stdout, {
					headers: { "content-type": "text/plain" },
				});
			}
			return new Response("Method not allowed", { status: 405 });
		} catch (error) {
			console.error("Sandbox request failed", error);
			return new Response("Sandbox request failed", { status: 500 });
		}
	},
} satisfies ExportedHandler<Env>;
The Worker accepts only 
https://github.com/ repository URLs, because the 
Outbound entrypoint blocks every other Git server. The routes are:
POST /sandboxes/<NAME>/repository clones a repository into the sandbox.
POST /sandboxes/<NAME>/task starts Claude Code with the request body as its prompt. The prompt becomes one argument of the 
claude command, so a prompt of 128 KiB or more gets a 
413 response.
GET /sandboxes/<NAME>/task returns the task state.
GET /sandboxes/<NAME>/diff returns the changes in the repository.
5. Deploy
:::caution
The Worker does not authenticate requests. Anyone with the URL can run Claude Code and spend your AI Gateway credits. Authenticate callers before you share the URL.
For more information, refer to Sandbox security.
:::
Create a file named 
.secrets.json with your gateway token:
{ "AI_GATEWAY_TOKEN": "<AI_GATEWAY_TOKEN>" }
Deploy your Worker with the secret:
Wrangler builds the image with Docker, pushes it to your account, and uploads the Worker with the 
AI_GATEWAY_TOKEN secret.
Delete the secrets file:
rm .secrets.json
Save the 
workers.dev URL that Wrangler prints in a shell variable:
WORKER_URL=https://sandbox-coding-agent.<YOUR_SUBDOMAIN>.workers.dev
6. Run a task
Clone GitHub's 
Hello-World repository into a sandbox named 
agent-1:
curl "$WORKER_URL/sandboxes/agent-1/repository" \
	--json '{"url": "https://github.com/octocat/Hello-World"}'
The first request starts the container, so it can take about a minute. Git writes its progress to standard error:
{
	"exitCode": 0,
	"stdout": "",
	"stderr": "Cloning into '/workspace/repo'...\n"
}
Start a task:
curl "$WORKER_URL/sandboxes/agent-1/task" \
	--data "Add a file NOTES.md with a one-sentence summary of this repository. Do not commit."
The Worker responds with 
202 and the task state:
{ "state": "running" }
Check the task until its state is 
succeeded or 
failed:
curl "$WORKER_URL/sandboxes/agent-1/task"
A finished task includes the final reply from Claude Code:
{
	"state": "succeeded",
	"result": "Created `NOTES.md` with a one-sentence summary. Left uncommitted as requested."
}
The reply differs on each run. This task takes a few seconds, and larger tasks take minutes. The alarm keeps the sandbox running until Claude Code exits, so you do not need to keep checking.
Read the changes:
curl "$WORKER_URL/sandboxes/agent-1/diff"
The response is a 
git diff of the repository. The new file appears because 
readDiff() marks it with 
--intent-to-add:
diff --git a/NOTES.md b/NOTES.md
new file mode 100644
index 0000000..95da11e
--- /dev/null
+++ b/NOTES.md
@@ -0,0 +1 @@
+This repository is a minimal test/example repo containing only a "Hello World!" README file.
If the model request fails, the task state is 
failed and 
error contains the message from AI Gateway:
Failed to authenticate. API Error: 401 Unauthorized means the gateway rejected the token. Check that the token belongs to the account and gateway in 
wrangler.jsonc. Claude Code retries a failing model request 10 times, so this error takes about three minutes to appear.
API Error: 402 Insufficient wholesale credits means the gateway uses Unified Billing and the account has no credits. Add credits, or store an Anthropic API key in the gateway.
Next steps
Run another agent in the same Worker. Refer to Codex, OpenCode, or Pi.
Deploy a finished runner for each agent. Refer to the coding agents example, which deploys one Worker for each agent instead of switching one Worker.
Keep the files of a sandbox after its container stops. Refer to Save and restore a sandbox with snapshots.
Clone private repositories with a token that stays in your Worker. Refer to Clone a private repository.
Decide what one sandbox should hold. Refer to Sandbox security.
Route Claude Code through AI Gateway from other environments. Refer to Claude Code in AI Gateway.

Build an AI code interpreter
import {
PackageManagers,
Render,
Steps,
TypeScriptExample,
WranglerConfig,
} from "~/components";
In this tutorial, you will build a Worker that answers questions by running code. A Workers AI model writes JavaScript, a Dynamic Worker runs it without network access, and the model uses the result in its answer.
When you finish, the Worker answers a question about prime numbers and returns the code the model ran:
{
	"answer": "There are 9,592 prime numbers below 100,000.",
	"runs": [
		{
			"code": "function isPrime(n){if(n<2)return false; if(n%2===0) return n===2; for(let i=3;i*i<=n;i+=2){if(n%i===0) return false;} return true;} let count=0; for(let i=2;i<100000;i++){ if(isPrime(i)) count++; } return count;",
			"output": { "result": 9592, "logs": [] }
		}
	]
}
You will learn how to:
Run model-generated JavaScript in a Dynamic Worker with no network access and a CPU time limit.
Give a model a tool that runs code and returns the result.
Send code errors back to the model so it can fix its code.
Prerequisites
1. Create the project
Create a Worker project:
<PackageManagers
type="create"
pkg="cloudflare@latest"
args={"sandbox-code-interpreter --category=hello-world --type=hello-world --lang=ts --no-deploy --no-git --no-agents"}
/>
Change into the project directory:
cd sandbox-code-interpreter
Install the Agents SDK, the AI SDK, and Zod. The Worker calls Workers AI with 
createAI from 
agents/models/ai-sdk:
Replace 
wrangler.jsonc to add a Workers AI binding and a Worker Loader binding:
{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "sandbox-code-interpreter",
	"main": "src/index.ts",
	"compatibility_date": "$today",
	"observability": {
		"enabled": true,
	},
	"upload_source_maps": true,
	"ai": {
		"binding": "AI",
	},
	"worker_loaders": [
		{
			"binding": "LOADER",
		},
	],
}
AI calls Workers AI models. 
LOADER creates Dynamic Workers at runtime.
Generate types for the bindings:
2. Run code in a sandbox
Create 
src/sandbox.ts. The 
runJavaScript() function loads the code into a new Dynamic Worker and returns its result and logs. It throws if the code does not finish within five seconds:
import type { WorkerEntrypoint } from "cloudflare:workers";
export type Output = {
	result?: unknown;
	logs: string[];
};
type CodeEntrypoint = WorkerEntrypoint & {
	run(): Promise<Output>;
};
const timeoutMs = 5_000;
export async function runJavaScript(env: Env, code: string): Promise<Output> {
	const sandbox = env.LOADER.load({
		compatibilityDate: "$today",
		mainModule: "code.js",
		modules: {
			"code.js": `
				import { WorkerEntrypoint } from "cloudflare:workers";
				function format(value) {
					return typeof value === "string" ? value : JSON.stringify(value);
				}
				export class Code extends WorkerEntrypoint {
					async run() {
						const logs = [];
						const console = {
							log: (...values) => logs.push(values.map(format).join(" ")),
						};
						const result = await (async () => {
							${code}
						})();
						return { result, logs };
					}
				}
			`,
		},
		globalOutbound: null,
		limits: { cpuMs: 50 },
	});
	let timer: number | null = null;
	const timeout = new Promise<never>((_, reject) => {
		timer = setTimeout(() => {
			reject(new Error(`The code did not finish within ${timeoutMs} ms`));
		}, timeoutMs);
	});
	try {
		return await Promise.race([
			sandbox.getEntrypoint<CodeEntrypoint>("Code").run(),
			timeout,
		]);
	} finally {
		clearTimeout(timer);
	}
}
The Dynamic Worker limits what the generated code can do:
globalOutbound: null makes 
fetch() and 
connect() throw, so the code has no network access.
The Dynamic Worker receives no 
env, so the code cannot call Workers AI or any other resource your Worker can reach.
limits: { cpuMs: 50 } stops code that uses more than 50 milliseconds of CPU time. Refer to Custom resource limits.
If the code waits without using CPU, such as in a long 
setTimeout(), the five-second timeout stops your Worker from waiting for it. The timer runs in your Worker, so the generated code cannot change it.
Each call to 
load() creates a new Dynamic Worker, so values from one run are not available in the next.
The generated code becomes the body of an async function, so it can use 
await and must 
return its result. A local 
console object collects 
console.log() output. The code can still change anything inside the Dynamic Worker, including the wrapper around it, but it cannot reach anything the Dynamic Worker does not receive.
3. Let the model run code
Replace 
src/index.ts. The Worker gives the model a 
runJavaScript tool and returns the answer from the model with every piece of code the model ran:
import { generateText, isStepCount, tool } from "ai";
import { createAI } from "agents/models/ai-sdk";
import { z } from "zod";
import { runJavaScript, type Output } from "./sandbox";
const model = "@cf/openai/gpt-oss-120b";
const Question = z.object({ question: z.string().min(1) });
const instructions = `Answer the question.
Always call the runJavaScript tool before you answer. Do not calculate, count, or sort in your head.
Write the body of an async JavaScript function and return the value you need.
If the tool returns an error, fix the code and run it again.
Answer in one or two plain-text sentences.`;
type Run = { code: string } & ({ output: Output } | { error: string });
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		if (request.method !== "POST") {
			return new Response("Send a POST request", { status: 405 });
		}
		const body = Question.safeParse(await request.json().catch(() => null));
		if (!body.success) {
			return Response.json(
				{ error: "Send a JSON body with a question" },
				{ status: 400 },
			);
		}
		const ai = createAI({ binding: env.AI });
		const runs: Run[] = [];
		try {
			const result = await generateText({
				model: ai(model),
				instructions,
				prompt: body.data.question,
				tools: {
					runJavaScript: tool({
						description:
							"Run JavaScript in a sandbox with no network access. The code is the body of an async function. Return a JSON-serializable value. console.log output is captured.",
						inputSchema: z.object({
							code: z.string().describe("Body of an async JavaScript function"),
						}),
						execute: async ({ code }) => {
							try {
								const output = await runJavaScript(env, code);
								runs.push({ code, output });
								return output;
							} catch (error) {
								const message =
									error instanceof Error ? error.message : String(error);
								runs.push({ code, error: message });
								return { error: message };
							}
						},
					}),
				},
				// Stop after five model steps, so a model that keeps failing cannot
				// run code indefinitely
				stopWhen: isStepCount(5),
			});
			return Response.json({ answer: result.text, runs });
		} catch (error) {
			console.error("Model request failed", error);
			return Response.json(
				{ error: "The model request failed. Try again later.", runs },
				{ status: 502 },
			);
		}
	},
} satisfies ExportedHandler<Env>;
generateText() sends the question to the model. When the model calls 
runJavaScript, the AI SDK runs 
execute() and sends the return value back to the model. The model can then run more code or answer.
If the code throws, exceeds the CPU time limit or the timeout, or calls 
fetch(), 
execute() returns the error message instead of failing the request. The model reads the error and can fix its code.
The Worker validates the request body with Zod before it calls the model. If a Workers AI request fails, for example because of a rate limit, the Worker logs the error and responds with 
502 and the code that already ran. 
observability in 
wrangler.jsonc keeps those logs in Workers Logs.
4. Test locally
Start a local development server:
During 
wrangler dev, the Dynamic Worker runs locally. Workers AI requests always run on Cloudflare and count toward your Workers AI usage.
POST a question to the URL Wrangler prints. The default is 
http://localhost:8787:
curl http://localhost:8787 --json '{"question":"How many prime numbers are there below 100,000?"}'
The response includes the answer and the code the model ran:
{
	"answer": "There are 9,592 prime numbers below 100,000.",
	"runs": [
		{
			"code": "function isPrime(n){if(n<2)return false; if(n%2===0) return n===2; for(let i=3;i*i<=n;i+=2){if(n%i===0) return false;} return true;} let count=0; for(let i=2;i<100000;i++){ if(isPrime(i)) count++; } return count;",
			"output": { "result": 9592, "logs": [] }
		}
	]
}
The model writes different code and wording each time. 
result is 
9592.
Ask a question that needs sorting:
curl http://localhost:8787 --json '{"question":"Sort these words by length, then alphabetically: pear, fig, banana, kiwi, apple, date."}'
The answer lists 
fig, date, kiwi, pear, apple, banana.
5. Deploy
:::caution
The Worker does not authenticate requests. Anyone with the URL can send questions and use your Workers AI allowance. Authenticate callers before you share the URL.
For more information, refer to Sandbox security.
:::
Deploy your Worker:
POST a question to the 
workers.dev URL Wrangler prints:
curl https://sandbox-code-interpreter.<YOUR_SUBDOMAIN>.workers.dev --json '{"question":"How many prime numbers are there below 100,000?"}'
The response has the same shape as the local response.
Next steps
Let generated code call methods that your Worker provides. Refer to Bindings.
Let a model call typed tools from generated code. Refer to Code Mode.
Run shell commands or other Linux tools. Refer to Run a Linux command.
Choose a different model. Refer to Workers AI models.

Run JavaScript
import {
PackageManagers,
Render,
Steps,
TypeScriptExample,
WranglerConfig,
} from "~/components";
You will POST JavaScript to a Worker and read 
{"result":["Ada"]}.
Prerequisites
Run JavaScript
Create a Worker project:
<PackageManagers
type="create"
pkg="cloudflare@latest"
args={"sandbox-dynamic-worker --category=hello-world --type=hello-world --lang=ts --no-deploy"}
/>
Change into the project directory:
cd sandbox-dynamic-worker
Replace 
wrangler.jsonc to add a Worker Loader binding:
{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "sandbox-dynamic-worker",
	"main": "src/index.ts",
	"compatibility_date": "$today",
	"observability": {
		"enabled": true,
	},
	"upload_source_maps": true,
	"worker_loaders": [
		{
			"binding": "LOADER",
		},
	],
}
Generate types for the binding:
Replace 
src/index.ts. Your Worker reads 
code from the JSON body and runs it in the sandbox:
import type { WorkerEntrypoint } from "cloudflare:workers";
type CodeEntrypoint = WorkerEntrypoint & {
	evaluate(): Promise<unknown>;
};
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const { code } = (await request.json()) as { code: string };
		const sandbox = env.LOADER.load({
			compatibilityDate: "$today",
			mainModule: "code.js",
			modules: {
				"code.js": `
					import { WorkerEntrypoint } from "cloudflare:workers";
					export class Code extends WorkerEntrypoint {
						evaluate() {
							${code}
						}
					}
				`,
			},
			// Block `fetch()` and `connect()`
			globalOutbound: null,
			// Stop code that uses more than 50 milliseconds of CPU time
			limits: { cpuMs: 50 },
		});
		const result = await sandbox
			.getEntrypoint<CodeEntrypoint>("Code")
			.evaluate();
		return Response.json({ result });
	},
};
code is the body of 
evaluate(), so it needs a 
return statement. Code that waits without using CPU can still hold the request open, so add a timeout before you run code from other people. For an example, refer to Build an AI code interpreter.
Run 
wrangler dev:
POST JavaScript to the URL Wrangler prints. The default is 
http://localhost:8787:
curl http://localhost:8787 --request POST --json '{
  "code": "const users = [{ name: \"Ada\", role: \"admin\" }, { name: \"Grace\", role: \"user\" }]; return users.filter((u) => u.role === \"admin\").map((u) => u.name);"
}'
The response body is 
{"result":["Ada"]}. The Worker ran the JavaScript you sent.
Next steps
Let the code call methods that your Worker provides. Refer to Bindings.
Run a Linux command. Refer to Run a Linux command.
Use the Loader API for 
load() and 
get().

Run a Linux command
import {
PackageManagers,
Render,
Steps,
TypeScriptExample,
WranglerConfig,
} from "~/components";
You will POST 
uname -a to a Worker and read stdout that contains 
Linux.
Prerequisites
Run a command in Linux
Create a Worker project:
<PackageManagers
type="create"
pkg="cloudflare@latest"
args={"sandbox-linux --category=hello-world --type=hello-world --lang=ts --no-deploy --no-git --no-agents"}
/>
Change into the project directory:
cd sandbox-linux
Replace 
wrangler.jsonc so a Durable Object can start a container:
{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "sandbox-linux",
	"main": "src/index.ts",
	"compatibility_date": "$today",
	"observability": {
		"enabled": true,
	},
	"upload_source_maps": true,
	"containers": [
		{
			"class_name": "MyContainer",
			"scheduling_policy": "durable_object",
		},
	],
	"durable_objects": {
		"bindings": [
			{
				"class_name": "MyContainer",
				"name": "MY_CONTAINER",
			},
		],
	},
	"exports": {
		"MyContainer": {
			"type": "durable-object",
			"storage": "sqlite",
		},
	},
}
Replace 
src/index.ts. The Worker reads 
argv from the JSON body and runs it in Linux:
import { DurableObject } from "cloudflare:workers";
export class MyContainer extends DurableObject<Env> {
	async exec(argv: string[]) {
		const container = this.ctx.container;
		if (!container) {
			throw new Error("No container is configured");
		}
		if (!container.running) {
			container.start({
				// Debian Trixie with Node.js 24
				image: "cloudflare/debian-trixie",
				// Keep the instance running so it can accept commands
				entrypoint: ["sleep", "infinity"],
				// Block commands in the sandbox from reaching the Internet
				enableInternet: false,
			});
		}
		const process = await container.exec(argv);
		const output = await process.output();
		return {
			stdout: new TextDecoder().decode(output.stdout),
			exitCode: output.exitCode,
		};
	}
}
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const { argv } = (await request.json()) as { argv: string[] };
		const sandbox = env.MY_CONTAINER.getByName("sandbox");
		return Response.json(await sandbox.exec(argv));
	},
};
Generate types for the binding. Wrangler reads the 
MyContainer class from 
src/index.ts to type 
env.MY_CONTAINER:
Run 
wrangler dev:
wrangler dev runs the instance in Docker on your machine, so Docker must be running. Running 
cloudflare/debian-trixie locally needs Wrangler 4.141.0 or later.
POST a command to the URL Wrangler prints. The default is 
http://localhost:8787:
curl http://localhost:8787 --request POST --json '{"argv":["uname","-a"]}'
The JSON body includes 
"exitCode":0. 
stdout contains 
Linux. The Worker started a Linux container and ran the command you sent. When you deploy, each instance runs in its own virtual machine instead of in Docker.
Next steps
Run another process in the instance. Refer to 
exec().
Deploy your Worker. Refer to Deploy Containers. A deploy does not replace a running instance. Refer to Sandbox lifetime.
Run JavaScript. Refer to Run JavaScript.
Use the Durable Object container API for 
start() and 
exec().
Start a project from the minimal sandbox template. It adds a 
Dockerfile, a sandbox for each name in the URL, and file reads and writes with 
@cloudflare/sandbox.

Manage sandboxes
import { DirectoryListing } from "~/components";
Your Worker reaches each sandbox by name. The runtime does not record which names belong to which user, and it does not wake a Durable Object when its container stops. To list a user's sandboxes or act when a sandbox stops, your Worker keeps its own records.

List a user's sandboxes
import { PackageManagers, Steps, WranglerConfig } from "~/components";
Each user gets a registry, a Durable Object that records the sandboxes of that user. In this example, the Worker adds a sandbox to the registry when the sandbox first runs a command. To report which sandboxes are running, the Worker asks the Durable Object of each sandbox whether its container is running.
Prerequisites
A Worker with a Durable Object that starts a container with the Durable Object scheduling policy. To create one, refer to Run a Linux command.
List the sandboxes
In 
wrangler.jsonc, add a binding for the registry class, and declare the class in 
exports:
{
	"durable_objects": {
		"bindings": [
			{
				"class_name": "MyContainer",
				"name": "MY_CONTAINER",
			},
			{
				"class_name": "SandboxDirectory",
				"name": "SANDBOX_DIRECTORY",
			},
		],
	},
	"exports": {
		"MyContainer": {
			"type": "durable-object",
			"storage": "sqlite",
		},
		"SandboxDirectory": {
			"type": "durable-object",
			"storage": "sqlite",
		},
	},
}
If your Worker declares its classes with a 
migrations array instead, add a migration with a new 
tag and 
"new_sqlite_classes": ["SandboxDirectory"]. For more information, refer to Durable Object class migrations (legacy).
Add the registry class to your Worker. Each user gets one 
SandboxDirectory, which stores the user's sandbox sessions in SQLite:
export class SandboxDirectory extends DurableObject<Env> {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		ctx.storage.sql.exec(
			"CREATE TABLE IF NOT EXISTS sandboxes (session TEXT PRIMARY KEY, created_at INTEGER NOT NULL)",
		);
	}
	add(session: string) {
		// Keep the time of the first command when the same session runs again
		this.ctx.storage.sql.exec(
			"INSERT OR IGNORE INTO sandboxes (session, created_at) VALUES (?, ?)",
			session,
			Date.now(),
		);
	}
	remove(session: string) {
		this.ctx.storage.sql.exec("DELETE FROM sandboxes WHERE session = ?", session);
	}
	list() {
		return this.ctx.storage.sql
			.exec<{ session: string }>("SELECT session FROM sandboxes ORDER BY created_at")
			.toArray()
			.map((row) => row.session);
	}
}
In 
MyContainer, set an inactivity timeout, and add methods that report and stop the container. Define the timeout at the top of the file, and add a constructor that sets it when a restarted Durable Object finds the container running:
const INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000;
export class MyContainer extends DurableObject<Env> {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		const container = ctx.container;
		if (container?.running) {
			void ctx.blockConcurrencyWhile(() =>
				container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS),
			);
		}
	}
}
In 
exec(), set the timeout after 
start(), inside the 
if (!container.running) block:
await container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS);
Then add the two methods to 
MyContainer:
export class MyContainer extends DurableObject<Env> {
	// ...
	isRunning() {
		// Reading `running` does not start the container
		return this.ctx.container?.running ?? false;
	}
	async destroy() {
		await this.ctx.container?.destroy();
	}
}
A listing request can wake a restarted Durable Object, which starts without the timeout that 
exec() set. The constructor sets the timeout again, so the sandbox does not stop shortly after the listing request ends. For more information, refer to Sandbox lifetime.
Add routes to your Worker that name each sandbox 
<OWNER>/<SESSION>, record the session before running a command, list the sessions with their state, and remove a session after stopping its container:
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);
		const [, users, owner, sandboxes, session] = url.pathname.split("/");
		if (users !== "users" || !owner || sandboxes !== "sandboxes") {
			return new Response("Not found", { status: 404 });
		}
		const directory = env.SANDBOX_DIRECTORY.getByName(owner);
		if (request.method === "GET" && !session) {
			const sessions = await directory.list();
			// Call the Durable Object of every session in parallel
			const list = await Promise.all(
				sessions.map(async (name) => ({
					session: name,
					running: await env.MY_CONTAINER.getByName(`${owner}/${name}`).isRunning(),
				})),
			);
			return Response.json(list);
		}
		if (!session) {
			return new Response("Not found", { status: 404 });
		}
		const sandbox = env.MY_CONTAINER.getByName(`${owner}/${session}`);
		if (request.method === "POST") {
			const { argv } = (await request.json()) as { argv: string[] };
			await directory.add(session);
			return Response.json(await sandbox.exec(argv));
		}
		if (request.method === "DELETE") {
			await sandbox.destroy();
			await directory.remove(session);
			return new Response(null, { status: 204 });
		}
		return new Response("Not found", { status: 404 });
	},
};
A sandbox whose container stopped stays in the list with 
running: false until the Worker removes its session.
Authenticate callers first, and derive the owner from their identity rather than from the URL. Otherwise anyone can list, use, or stop another user's sandboxes. For more information, refer to Sandbox security.
Deploy your Worker:
Start two sandboxes for the user 
ada, on the 
workers.dev URL that Wrangler prints:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/users/ada/sandboxes/notes --request POST --json '{"argv":["uname","-s"]}'
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/users/ada/sandboxes/tests --request POST --json '{"argv":["uname","-s"]}'
List them:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/users/ada/sandboxes
[
	{ "session": "notes", "running": true },
	{ "session": "tests", "running": true }
]
Stop one of them, and list again:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/users/ada/sandboxes/tests --request DELETE
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/users/ada/sandboxes
[{ "session": "notes", "running": true }]
List sandboxes across the account
The registry lists only the sandboxes that your Worker recorded. The Containers API lists every sandbox that a Container application started, including sandboxes that failed or that the registry missed. For each sandbox, the list of instances returns the name passed to 
getByName() and the state:
curl "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/containers/applications/<APPLICATION_ID>/instances?name_prefix=ada/" \
	--header "Authorization: Bearer <API_TOKEN>"
The application ID appears in 
wrangler containers list. The application is named after the Worker and the Durable Object class, such as 
sandbox-linux-mycontainer.
The API token needs the Containers Read permission, which covers every Container application in the account. Use it for administration and cleanup, not in routes that users call.
name_prefix filters by the start of the name, and 
state=active returns only sandboxes that are starting, running, or stopping. Stopped sandboxes stay in the list.
A new sandbox can take a few seconds to appear, and sandboxes that run under 
wrangler dev do not appear.
Related resources
Sandbox lifetime: what keeps a sandbox running, and what stops it.
Run code when a sandbox stops: record when and why each sandbox stops.
destroy()
SQLite storage API

Run code when a sandbox stops
import { PackageManagers, Steps } from "~/components";
The runtime does not wake a Durable Object when its container stops. Your Durable Object watches the container while the Durable Object is in memory, and checks for a missed stop on every command and alarm. In this example, the Durable Object also stops idle sandboxes itself, so the record shows why each one stopped.
Prerequisites
A Worker with a Durable Object that starts a container with the Durable Object scheduling policy. To create one, refer to Run a Linux command.
Record each stop
At the top of 
src/index.ts, define the check interval, the idle limit, the inactivity timeout, and the record your Durable Object keeps:
const CHECK_INTERVAL_MS = 60 * 1000;
// Stop a sandbox after this long without requests
const IDLE_LIMIT_MS = 10 * 60 * 1000;
const INACTIVITY_TIMEOUT_MS = 5 * 60 * 1000;
interface SandboxRecord {
	state: "running" | "stopped";
	lastActivity: number;
	reason?: string;
	exitCode?: number | null;
	stoppedAt?: number;
}
Keep the inactivity timeout longer than the check interval, so the container keeps running between alarms. While 
monitor() waits, the inactivity timeout does not start, so the alarm enforces the idle limit. If the alarms stop, the timeout still stops the container after the Durable Object leaves memory. For more information, refer to Sandbox lifetime.
In 
MyContainer, add a constructor, a method that watches the container, and a method that records the stop:
export class MyContainer extends DurableObject<Env> {
	// ...
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		const container = ctx.container;
		// A restarted Durable Object loses the earlier `monitor()` call and the
		// inactivity timeout
		if (container?.running) {
			void ctx.blockConcurrencyWhile(() =>
				container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS),
			);
			this.watch();
		}
	}
	watch() {
		this.ctx.container?.monitor().then(
			() => this.onStop("exited", 0),
			(error: unknown) => {
				const exitCode = (error as { exitCode?: number }).exitCode;
				if (exitCode === undefined) {
					return this.onStop(String(error), null);
				}
				return this.onStop("exited", exitCode);
			},
		);
	}
	async onStop(reason: string, exitCode: number | null) {
		const record = await this.ctx.storage.get<SandboxRecord>("sandbox");
		// Record each stop once, even when two checks report it
		if (record?.state !== "running") {
			return;
		}
		await this.ctx.storage.put<SandboxRecord>("sandbox", {
			...record,
			state: "stopped",
			reason,
			exitCode,
			stoppedAt: Date.now(),
		});
		await this.ctx.storage.deleteAlarm();
		console.log(JSON.stringify({ event: "sandbox.stopped", reason, exitCode }));
	}
}
When the main process fails, 
monitor() rejects with an error that has an 
exitCode. When your code calls 
destroy() with a reason, 
monitor() rejects with that reason. Put your own code after the record is saved.
Add a method that records a stop that 
monitor() missed:
export class MyContainer extends DurableObject<Env> {
	// ...
	async reconcile() {
		const record = await this.ctx.storage.get<SandboxRecord>("sandbox");
		if (record?.state === "running" && !this.ctx.container?.running) {
			// A stop that happened while the Durable Object was not in memory has
			// no exit code
			await this.onStop("unknown", null);
		}
	}
}
Replace 
exec(). It checks for a missed stop, watches a container it starts, schedules the next check, and records activity when the command finishes:
export class MyContainer extends DurableObject<Env> {
	// ...
	// Count the commands that are running. A request in progress keeps the
	// Durable Object in memory, so the count does not need storage
	busy = 0;
	async exec(argv: string[]) {
		const container = this.ctx.container;
		if (!container) {
			throw new Error("No container is configured");
		}
		await this.reconcile();
		if (!container.running) {
			container.start({
				image: "cloudflare/debian-trixie",
				entrypoint: ["sleep", "infinity"],
				enableInternet: false,
			});
			await container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS);
			this.watch();
		}
		await this.ctx.storage.put<SandboxRecord>("sandbox", {
			state: "running",
			lastActivity: Date.now(),
		});
		await this.ctx.storage.setAlarm(Date.now() + CHECK_INTERVAL_MS);
		this.busy++;
		try {
			const process = await container.exec(argv);
			const output = await process.output();
			return {
				stdout: new TextDecoder().decode(output.stdout),
				exitCode: output.exitCode,
			};
		} finally {
			this.busy--;
			const record = await this.ctx.storage.get<SandboxRecord>("sandbox");
			if (record?.state === "running") {
				await this.ctx.storage.put<SandboxRecord>("sandbox", {
					...record,
					lastActivity: Date.now(),
				});
			}
		}
	}
}
The alarm does not stop the sandbox while a command is running, even when the command runs longer than the idle limit.
Add an alarm handler that checks the sandbox and stops it after 
IDLE_LIMIT_MS without requests. Then add methods that return the record and stop the sandbox:
export class MyContainer extends DurableObject<Env> {
	// ...
	async alarm() {
		await this.reconcile();
		const record = await this.ctx.storage.get<SandboxRecord>("sandbox");
		if (record?.state !== "running") {
			return;
		}
		if (this.busy === 0 && Date.now() - record.lastActivity > IDLE_LIMIT_MS) {
			await this.ctx.container?.destroy("idle");
			return;
		}
		await this.ctx.storage.setAlarm(Date.now() + CHECK_INTERVAL_MS);
	}
	async status() {
		return (await this.ctx.storage.get<SandboxRecord>("sandbox")) ?? null;
	}
	async stop() {
		await this.ctx.container?.destroy("stopped");
	}
}
The reason passed to 
destroy() reaches 
monitor(), so an idle stop records 
idle and a stop through 
stop() records 
stopped.
A Durable Object has one alarm. If your class already has an 
alarm() handler, merge the stop and idle checks into it, and set the alarm to the earliest time that any check needs. For more information, refer to Alarms.
Add routes to your Worker. 
GET returns the record, 
DELETE stops the sandbox, and 
POST runs a command:
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const sandbox = env.MY_CONTAINER.getByName("sandbox");
		if (request.method === "GET") {
			return Response.json(await sandbox.status());
		}
		if (request.method === "DELETE") {
			await sandbox.stop();
			return new Response(null, { status: 204 });
		}
		const { argv } = (await request.json()) as { argv: string[] };
		return Response.json(await sandbox.exec(argv));
	},
};
Authenticate callers first, so other people cannot use or stop the sandbox. For more information, refer to Sandbox security.
Deploy your Worker:
Run a command, stop the sandbox, and read the record, on the 
workers.dev URL that Wrangler prints:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev --request POST --json '{"argv":["uname","-s"]}'
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev --request DELETE
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev
{
	"state": "stopped",
	"lastActivity": 1790270030663,
	"reason": "stopped",
	"exitCode": null,
	"stoppedAt": 1790270031496
}
Run another command and send no requests for 10 minutes. The next alarm stops the sandbox, and the record shows 
"reason": "idle". A deploy while the sandbox runs does not record a stop.
Reasons in the record
The 
reason field shows how the sandbox stopped:
Reason
Meaning
exited
The main process exited. 
exitCode holds its exit code.
idle or 
stopped
Your Durable Object called 
destroy() with this reason.
unknown
The container stopped while the Durable Object was not in memory, and a later command or alarm found it stopped. The exit code is not available.
Any other text
The error from 
monitor() when the container failed.
Related resources
Sandbox lifetime: what keeps a sandbox running, and what stops it.
Save a sandbox automatically: save a snapshot before an idle stop.
List a user's sandboxes
monitor() and 
destroy()
Durable Object alarms

Call an authenticated API from a sandbox
import {
PackageManagers,
Steps,
TypeScriptExample,
WranglerConfig,
} from "~/components";
Let code in a sandbox call an API that needs a token, while the token stays in your Worker. Requests from the sandbox reach an entrypoint in your Worker, which allows only the requests you choose and adds the token. In this example, the code reads your profile from the GitHub API.
Prerequisites
A Worker with a Durable Object that starts a container with the Durable Object scheduling policy, or a Worker that loads Dynamic Workers with a Worker Loader binding named 
LOADER. To create one, refer to Run a Linux command or Run JavaScript.
A GitHub access token that can read your profile.
Store the token
In 
wrangler.jsonc, declare the token as a secret, then generate types:
{
	"secrets": {
		"required": ["GITHUB_TOKEN"],
	},
}
Store the token when Wrangler prompts for it:
Call the API from a Container
The container sends its request to 
api.github.com as usual. The Durable Object intercepts HTTPS requests to that hostname and delivers them to an entrypoint in your Worker, which adds the token.
Add an entrypoint to your Worker that accepts one GitHub API request and adds the token:
import { WorkerEntrypoint } from "cloudflare:workers";
export class GitHubGateway extends WorkerEntrypoint<Env> {
	async fetch(request: Request): Promise<Response> {
		const url = new URL(request.url);
		if (
			request.method !== "GET" ||
			url.hostname !== "api.github.com" ||
			url.pathname !== "/user" ||
			url.search !== ""
		) {
			return new Response("Forbidden", { status: 403 });
		}
		return fetch("https://api.github.com/user", {
			headers: {
				Accept: "application/vnd.github+json",
				Authorization: `Bearer ${this.env.GITHUB_TOKEN}`,
				"User-Agent": "cloudflare-sandbox",
				"X-GitHub-Api-Version": "2022-11-28",
			},
		});
	}
}
The entrypoint allows only 
GET /user, so code in the sandbox cannot use the token for anything else. Allow each request your code needs, and nothing more.
Add a method to your Durable Object that intercepts 
api.github.com and runs code that calls it:
export class MyContainer extends DurableObject<Env> {
	// ...
	async getUsername(): Promise<string> {
		const container = this.ctx.container;
		if (!container) {
			throw new Error("No container is configured");
		}
		await container.interceptOutboundHttps(
			"api.github.com",
			this.ctx.exports.GitHubGateway,
		);
		if (!container.running) {
			container.start({
				image: "cloudflare/debian-trixie",
				entrypoint: ["sleep", "infinity"],
				// The container can reach only the hostnames you intercept
				enableInternet: false,
			});
		}
		const process = await container.exec(
			[
				"node",
				"--input-type=module",
				"--eval",
				`const response = await fetch("https://api.github.com/user");
if (!response.ok) throw new Error("GitHub request failed");
console.log((await response.json()).login);`,
			],
			{
				env: {
					// The intercept terminates TLS with a certificate that the container
					// CA certificate signs. Node.js reads the CA certificate from this path
					NODE_EXTRA_CA_CERTS: "/etc/cloudflare/certs/cloudflare-containers-ca.crt",
				},
			},
		);
		const output = await process.output();
		if (output.exitCode !== 0) {
			throw new Error(new TextDecoder().decode(output.stderr));
		}
		return new TextDecoder().decode(output.stdout).trim();
	}
}
Add a route to your Worker that returns the username:
if (url.pathname === "/username") {
	const sandbox = env.MY_CONTAINER.getByName("github");
	return Response.json({ username: await sandbox.getUsername() });
}
The route uses a sandbox name of its own. An instance that is already running keeps the Internet access it started with, so 
enableInternet: false applies only to an instance that this method starts.
Deploy your Worker, then send a request to 
/username on the 
workers.dev URL that Wrangler prints:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/username
{ "username": "octocat" }
Call the API from a Dynamic Worker
A Dynamic Worker gets a method that calls one fixed GitHub endpoint, instead of the token.
Add an entrypoint to your Worker with a method that calls GitHub with the token:
import { WorkerEntrypoint } from "cloudflare:workers";
export class GitHub extends WorkerEntrypoint<Env> {
	async getUsername(): Promise<string> {
		const response = await fetch("https://api.github.com/user", {
			headers: {
				Accept: "application/vnd.github+json",
				Authorization: `Bearer ${this.env.GITHUB_TOKEN}`,
				"User-Agent": "cloudflare-sandbox",
				"X-GitHub-Api-Version": "2022-11-28",
			},
		});
		if (!response.ok) {
			throw new Error(`GitHub returned ${response.status}`);
		}
		const user = await response.json<{ login: string }>();
		return user.login;
	}
}
In the 
fetch() handler of your Worker, pass the entrypoint to the Dynamic Worker as a binding. The handler needs its 
ctx argument for 
ctx.exports:
const sandbox = env.LOADER.load({
	compatibilityDate: "2026-10-01",
	mainModule: "code.js",
	modules: {
		"code.js": `
			import { WorkerEntrypoint } from "cloudflare:workers";
			export class Code extends WorkerEntrypoint {
				async run() {
					return this.env.GITHUB.getUsername();
				}
			}
		`,
	},
	env: {
		// Create a stub that the Dynamic Worker can receive
		GITHUB: ctx.exports.GitHub({ props: {} }),
	},
	// Block every other `fetch()` and `connect()` call from the Dynamic Worker
	globalOutbound: null,
});
const username = await sandbox
	.getEntrypoint<WorkerEntrypoint & { run(): Promise<string> }>("Code")
	.run();
return Response.json({ username });
The code calls 
this.env.GITHUB.getUsername(), and the method reads the token in your Worker.
Deploy your Worker, then send a request to the 
workers.dev URL that Wrangler prints:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev
{ "username": "octocat" }
Authenticate callers to your Worker first, so other people cannot use the quota of your token. For more information, refer to Sandbox security.
Related resources
Clone a private repository: the same pattern for Git.
interceptOutboundHttps: intercept other Container destinations.
Bindings: pass other methods to a Dynamic Worker.
Egress control: restrict or audit requests from a Dynamic Worker.
Secrets: rotate or manage the token.

Clone a private repository
import {
PackageManagers,
Render,
Steps,
TypeScriptExample,
WranglerConfig,
} from "~/components";
Clone a private repository into a sandbox while the access token stays in your Worker. If the clone URL contains the token, every command in the sandbox can read it. Instead, the Durable Object intercepts HTTPS requests from Git to 
github.com. An entrypoint in your Worker receives each request, checks it, and adds the token.
Prerequisites
A Worker with a Durable Object that starts a container with the Durable Object scheduling policy. To create one, refer to Run a Linux command.
A GitHub access token with read access to the contents of the repository.
Clone the repository
Create a 
Dockerfile in your project root that installs Git:
FROM node:24-trixie-slim
RUN apt-get update \
	&& apt-get install --yes --no-install-recommends ca-certificates git \
	&& rm -rf /var/lib/apt/lists/*
CMD ["sleep", "infinity"]
In 
wrangler.jsonc, name the repository, declare the token as a secret, and build the 
Dockerfile as a named image. Replace 
<OWNER>/<REPOSITORY> with your repository:
{
	"vars": {
		"REPOSITORY": "<OWNER>/<REPOSITORY>",
	},
	"secrets": {
		"required": ["GITHUB_TOKEN"],
	},
	"containers": [
		{
			"class_name": "MyContainer",
			"scheduling_policy": "durable_object",
			"images": {
				"git": {
					"dockerfile": "./Dockerfile",
				},
			},
		},
	],
}
Store the token when Wrangler prompts for it:
Add an entrypoint to your Worker that accepts only the requests that fetch the repository, and adds the token:
import { WorkerEntrypoint } from "cloudflare:workers";
export class GitGateway extends WorkerEntrypoint<Env> {
	async fetch(request: Request): Promise<Response> {
		const url = new URL(request.url);
		const repository = `/${this.env.REPOSITORY}.git`;
		const fetchesRepository =
			(request.method === "GET" &&
				url.pathname === `${repository}/info/refs` &&
				url.search === "?service=git-upload-pack") ||
			(request.method === "POST" &&
				url.pathname === `${repository}/git-upload-pack`);
		if (url.hostname !== "github.com" || !fetchesRepository) {
			return new Response("Forbidden", { status: 403 });
		}
		const headers = new Headers(request.headers);
		const credentials = btoa(`x-access-token:${this.env.GITHUB_TOKEN}`);
		headers.set("Authorization", `Basic ${credentials}`);
		return fetch(new Request(request, { headers }));
	}
}
git-upload-pack serves clones and fetches. The entrypoint allows it for one repository and rejects every other request. Code in the sandbox cannot push through 
git-receive-pack or read other repositories, even when the token allows it.
Add a method to your Durable Object that intercepts 
github.com and clones the repository:
export class MyContainer extends DurableObject<Env> {
	// ...
	async clone(): Promise<{ exitCode: number; stderr: string }> {
		const container = this.ctx.container;
		if (!container) {
			throw new Error("No container is configured");
		}
		await container.interceptOutboundHttps(
			"github.com",
			this.ctx.exports.GitGateway,
		);
		if (!container.running) {
			container.start({
				image: container.images.git,
				// The container can reach only the hostnames you intercept
				enableInternet: false,
			});
			// Keep the clone for later requests
			await container.setInactivityTimeout(10 * 60 * 1000);
		}
		const process = await container.exec(
			[
				"git",
				"clone",
				"--depth=1",
				`https://github.com/${this.env.REPOSITORY}.git`,
				"/workspace",
			],
			{
				env: {
					// The intercept terminates TLS with a certificate that the container
					// CA certificate signs. Git reads the CA certificate from this path
					GIT_SSL_CAINFO: "/etc/cloudflare/certs/cloudflare-containers-ca.crt",
				},
			},
		);
		const output = await process.output();
		return {
			exitCode: output.exitCode,
			// Git prints its progress to standard error
			stderr: new TextDecoder().decode(output.stderr),
		};
	}
}
Add a route to your Worker that clones the repository:
if (url.pathname === "/clone" && request.method === "POST") {
	const sandbox = env.MY_CONTAINER.getByName("repo");
	const { exitCode, stderr } = await sandbox.clone();
	return new Response(stderr, { status: exitCode === 0 ? 200 : 500 });
}
The route uses a sandbox name of its own. An instance that is already running keeps the image and Internet access it started with, so it would have no Git.
When Git fails, the route responds with 
500 and the error from Git. While the sandbox keeps running, a second request fails this way, because 
/workspace already holds the clone.
Authenticate callers first, so other people cannot read the repository through the sandbox. For more information, refer to Sandbox security.
Deploy your Worker:
Send a 
POST request to 
/clone on the 
workers.dev URL that Wrangler prints:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/clone --request POST
Cloning into '/workspace'...
The repository is in 
/workspace, and 
git remote get-url origin prints the URL without a token. A 
git push from the sandbox fails with 
403. The clone lasts until the instance stops. For more information, refer to Sandbox lifetime.
Related resources
Run tests from a Git repository: install and test a cloned repository.
Call an authenticated API from a sandbox: the same pattern for an API.
interceptOutboundHttps

Credentials and network access
import { DirectoryListing } from "~/components";
Any process in a sandbox can read a token that the sandbox holds. Keep the token in your Worker instead, and give the sandbox only the access it needs. A Container sends requests to a hostname that you choose, and your Worker intercepts each request and adds the token. A Dynamic Worker calls a method that your Worker passes it, and the method adds the token.
A Container that starts with 
enableInternet: false reaches only the hostnames you intercept. A Dynamic Worker loaded with 
globalOutbound: null cannot make its own requests, and reaches your application only through the methods you pass.
For every outbound option in each environment, refer to Handle outbound traffic for Containers and Egress control for Dynamic Workers.

Preview a web application
import { PackageManagers, Steps, TypeScriptExample } from "~/components";
Use a browser to open a web server that runs in a sandbox. The server has no public port, so your Worker forwards requests to it. In this example, the Worker forwards each request under 
/previews/<NAME>/ to the sandbox named 
<NAME>.
Prerequisites
A Worker with a Durable Object that starts a container with the Durable Object scheduling policy. To create one, refer to Run a Linux command.
Forward requests to the server
Choose the command that starts your server. In this example, the command runs a small Node.js server that returns the request path and the server uptime. Replace it with your own command, such as 
npm run dev:
const port = 8080;
const server = `
const { createServer } = require("node:http");
process.on("SIGTERM", () => process.exit(0));
createServer((request, response) => {
	response.setHeader("Content-Type", "application/json");
	response.end(
		JSON.stringify({ path: request.url, uptime: Math.round(process.uptime()) }),
	);
}).listen(8080, "0.0.0.0");
`;
The server must listen on 
0.0.0.0, because 
getTcpPort() cannot reach a server that listens only on 
127.0.0.1. Many development servers listen on 
localhost by default and provide an option to change the address. The server runs as the main process. When it exits, for example after a crash, the instance stops, and its files end with it. If commands in the sandbox change files that you need, start the server as described in Run a server in the background instead.
After you deploy, servers built on the Python 
http.server module, such as 
python3 -m http.server, exit on startup, because they look up the container hostname. For a Python command that serves files, refer to Differences after you deploy.
Add an inactivity timeout to your Durable Object. The constructor sets the timeout again when a restarted Durable Object finds the container running:
const INACTIVITY_TIMEOUT_MS = 5 * 60 * 1000;
export class MyContainer extends DurableObject<Env> {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		const container = ctx.container;
		if (container?.running) {
			void ctx.blockConcurrencyWhile(() =>
				container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS),
			);
		}
	}
}
The five-minute inactivity timeout keeps the server running between visits. For more information, refer to Sandbox lifetime.
Then start the server and wait until it responds:
export class MyContainer extends DurableObject<Env> {
	// ...
	// Skip the check after the first response
	private ready = false;
	private async startServer(): Promise<Container> {
		const container = this.ctx.container;
		if (!container) {
			throw new Error("No container is configured");
		}
		if (!container.running) {
			container.start({
				image: "cloudflare/debian-trixie",
				entrypoint: ["node", "--eval", server],
				enableInternet: false,
			});
			await container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS);
			this.ready = false;
		}
		// `start()` returns before the server listens. Send `GET /` until any
		// HTTP response arrives, for up to 30 seconds
		const deadline = Date.now() + 30_000;
		while (!this.ready && Date.now() < deadline) {
			try {
				const response = await container
					.getTcpPort(port)
					.fetch("http://container/", { signal: AbortSignal.timeout(1_000) });
				await response.body?.cancel();
				this.ready = true;
			} catch {
				await scheduler.wait(500);
			}
		}
		return container;
	}
}
Forward requests from the 
fetch() handler of your Durable Object:
export class MyContainer extends DurableObject<Env> {
	// ...
	async fetch(request: Request): Promise<Response> {
		const container = await this.startServer();
		if (!this.ready) {
			return new Response("The preview did not start", { status: 503 });
		}
		// Forward each request once, because a retry could send a `POST` twice
		try {
			return await container.getTcpPort(port).fetch(request);
		} catch {
			// Check the server again on the next request
			this.ready = false;
			return new Response("The preview is not responding", { status: 502 });
		}
	}
}
Route preview paths from your Worker to your Durable Object:
function forward(
	sandbox: DurableObjectStub<MyContainer>,
	request: Request,
	path: string | undefined,
): Promise<Response> | Response {
	const url = new URL(request.url);
	if (!path) {
		url.pathname += "/";
		return Response.redirect(url.toString(), 308);
	}
	// Prefix the host, so that a path such as //example.com/ stays a path.
	const target = new URL(`http://container${path}${url.search}`);
	return sandbox.fetch(new Request(target, request));
}
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);
		const preview = /^\/previews\/([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)(\/.*)?$/.exec(url.pathname);
		if (!preview) {
			return new Response("Not found", { status: 404 });
		}
		const sandbox = env.MY_CONTAINER.getByName(preview[1]);
		return forward(sandbox, request, preview[2]);
	},
} satisfies ExportedHandler<Env>;
The server receives each path without the 
/previews/<NAME> prefix. Links that start with 
/ leave the preview, so use relative links or serve each preview on its own hostname.
In this example, the route reads the sandbox name from the URL. The pattern accepts only names that are valid DNS labels: 1 to 63 lowercase letters, digits, and hyphens, with no hyphen at either end. A name that this route accepts can also be a preview hostname. An encoded 
/ does not match, so this route cannot reach a sandbox that another route names with a 
/, such as 
<OWNER>/<SESSION>.
Authenticate callers before they reach a preview. Serve previews from a hostname that does not host your application. For more information, refer to Sandbox security.
Deploy your Worker:
Request a page from the preview named 
ada. Replace the example hostname with the 
workers.dev URL that Wrangler prints:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/previews/ada/hello
{ "path": "/hello", "uptime": 0 }
Wait a few seconds and send the same request again. The uptime increases, because the same server handles both requests:
{ "path": "/hello", "uptime": 5 }
Keep WebSocket connections open
The 
fetch() handler in the previous section passes WebSocket upgrade requests to the server, so WebSocket connections work. A connection that only passes through the Durable Object does not keep the sandbox running. When the inactivity timeout ends, Cloudflare stops the instance and the connection closes.
To keep the sandbox running while a page has a connection open, accept both ends of the connection in the Durable Object:
Add a function that relays messages between the visitor and the server:
function bridge(response: Response): Response {
	const upstream = response.webSocket!;
	const [client, server] = Object.values(new WebSocketPair());
	// Receive binary messages as `ArrayBuffer` instead of `Blob`
	upstream.binaryType = "arraybuffer";
	server.binaryType = "arraybuffer";
	upstream.accept();
	server.accept();
	// A listener that throws drops the connection, so these never throw.
	const relay = (from: WebSocket, to: WebSocket) => {
		from.addEventListener("message", (event) => {
			try {
				to.send(event.data);
			} catch {
				from.close(1011, "The other side closed");
			}
		});
		from.addEventListener("close", (event) => {
			// 1005 and 1006 report a missing or abnormal close and cannot be sent.
			const code =
				event.code === 1005 || event.code === 1006 ? 1000 : event.code;
			try {
				to.close(code, event.reason);
			} catch {}
		});
	};
	relay(server, upstream);
	relay(upstream, server);
	// Pass on the subprotocol that the server chose. A browser closes a
	// connection that requested one and receives none.
	const headers = new Headers();
	const protocol = response.headers.get("Sec-WebSocket-Protocol");
	if (protocol) {
		headers.set("Sec-WebSocket-Protocol", protocol);
	}
	return new Response(null, { status: 101, webSocket: client, headers });
}
In the 
fetch() handler of your Durable Object, bridge responses that open a WebSocket:
try {
	const response = await container.getTcpPort(port).fetch(request);
	return response.webSocket ? bridge(response) : response;
} catch {
With the bridge, the sandbox keeps running while any page has a connection open, even when no messages arrive. After the last connection closes, the inactivity timeout applies again.
Use hot reloading with a development server
Development servers such as Vite reload the page over a WebSocket. With the bridge from the previous section, the reload connection reaches the server. Two server settings decide whether hot reloading works:
The server checks the 
Host header of each request. Vite rejects hostnames that it does not know, so add the preview hostname to 
server.allowedHosts. Under 
/previews/<NAME>/, requests arrive with the 
Host header 
container.
The server builds absolute URLs for its assets and for the reload connection from its base path. Under 
/previews/<NAME>/, those URLs leave the preview. Serve each preview on its own hostname, where paths reach the server unchanged.
The following Vite configuration accepts requests for previews on their own hostnames under 
example-previews.com:
import { defineConfig } from "vite";
export default defineConfig({
	server: {
		host: "0.0.0.0",
		port: 8080,
		allowedHosts: [".example-previews.com"],
	},
});
Share a preview with a link
Give someone access to one preview for a limited time. In this example, the Durable Object stores random tokens with an expiry time. The Worker forwards requests under 
/shared/<NAME>/<TOKEN>/ only while the token is valid.
Add methods that create and check tokens to your Durable Object:
export class MyContainer extends DurableObject<Env> {
	// ...
	async share(ttl: number): Promise<string> {
		const token = crypto.randomUUID();
		await this.ctx.storage.put(`share:${token}`, Date.now() + ttl);
		return token;
	}
	async isShared(token: string): Promise<boolean> {
		const key = `share:${token}`;
		const expires = await this.ctx.storage.get<number>(key);
		if (expires !== undefined && expires <= Date.now()) {
			await this.ctx.storage.delete(key);
			return false;
		}
		return expires !== undefined;
	}
}
In the 
fetch() handler of your Worker, add routes that create a link and serve shared previews, before the 
404 response:
const share = /^\/shares\/([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)$/.exec(url.pathname);
if (share && request.method === "POST") {
	const sandbox = env.MY_CONTAINER.getByName(share[1]);
	const token = await sandbox.share(60 * 60 * 1000);
	return Response.json({ url: `${url.origin}/shared/${share[1]}/${token}/` });
}
const shared = /^\/shared\/([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)\/([^/]+)(\/.*)?$/.exec(url.pathname);
if (shared) {
	const sandbox = env.MY_CONTAINER.getByName(shared[1]);
	if (!(await sandbox.isShared(shared[2]))) {
		return new Response("Not found", { status: 404 });
	}
	return forward(sandbox, request, shared[3]);
}
Authenticate the 
POST request, so that only the owner of a preview can create links to it. Code in a preview runs on this hostname and can send requests to this route with the visitor's cookies. To prevent that, serve the route from another hostname, or authenticate it with a credential that pages in the browser cannot send, such as a secret that your application backend adds.
The shared route needs no authentication, because the token is the permission.
Deploy your Worker, then create a link to the preview named 
ada:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/shares/ada --request POST
{
	"url": "https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/shared/ada/<TOKEN>/"
}
Open the URL in a browser. The preview loads for one hour. After that, and for any other token or preview name, the Worker responds with 
404.
Anyone with the link can open the preview until it expires. Each token belongs to one preview name. To revoke a link early, delete its key from Durable Object storage.
Stop a preview
Stop the server when the preview is no longer needed, instead of waiting for the inactivity timeout:
Add a method that stops the container to your Durable Object:
export class MyContainer extends DurableObject<Env> {
	// ...
	async stop(): Promise<void> {
		if (this.ctx.container?.running) {
			await this.ctx.container.destroy();
		}
		this.ready = false;
	}
}
In your Worker, call it for 
DELETE /previews/<NAME>, before forwarding:
if (!preview[2] && request.method === "DELETE") {
	await sandbox.stop();
	return new Response(null, { status: 204 });
}
Deploy your Worker, and stop the preview named 
ada:
curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/previews/ada --request DELETE
The Worker responds with 
204. The next request to the preview starts a new server, with an uptime of 
0.
Related resources
Serve previews on their own hostnames
Sandbox lifetime
Sandbox security
getTcpPort()

Serve previews on their own hostnames
import {
PackageManagers,
Steps,
TypeScriptExample,
WranglerConfig,
} from "
/components";
import { PreviewHostname } from "/components/react/sandbox/PreviewHostname";
Serve each sandbox preview from its own hostname, such as 
ada.example-previews.com. Code in a preview runs in the visitor's browser, and each preview hostname is a separate origin. Code in one preview cannot read your application pages or the storage of another preview. Paths reach the server unchanged, so applications do not need a base path.
In 
https://ada.example-previews.com/app/, a wildcard DNS record and the route 
*.example-previews.com/* send the request to your Worker. Your Worker reads the sandbox name 
ada and calls 
getByName("ada"). A name that is not a valid DNS label gets a 
404. The path 
/app/ reaches the web server in the container unchanged, with the preview hostname in the 
Host header.
Prerequisites
A Durable Object whose 
fetch() handler forwards requests to a web server in its container. To build one, refer to Preview a web application.
A domain for previews on Cloudflare, such as 
example-previews.com, with Cloudflare managing its DNS. Use a domain that your application does not use.
Route preview hostnames to your Worker
In the DNS settings of the preview domain, add a proxied wildcard record. For example, add an 
AAAA record with the name 
* and the content 
100::, with the proxy status Proxied.
The record lets Cloudflare receive requests for every preview hostname. The Worker route handles those requests, so Cloudflare never contacts the address in the record.
In 
wrangler.jsonc, add the preview domain as a variable and route its subdomains to your Worker. Replace 
example-previews.com with your preview domain:
{
	"vars": {
		"PREVIEW_DOMAIN": "example-previews.com",
	},
	"routes": [
		{
			"pattern": "*.example-previews.com/*",
			"zone_name": "example-previews.com",
		},
	],
	"workers_dev": true,
}
Wrangler turns off the 
workers.dev URL when 
routes is set. 
workers_dev: true keeps it for requests that manage previews.
Generate types for the new variable:
In the 
fetch() handler of your Worker, send each preview hostname to the Durable Object with the same name:
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);
		const suffix = `.${env.PREVIEW_DOMAIN}`;
		// A preview hostname reaches only the sandbox with the same name.
		if (url.hostname.endsWith(suffix)) {
			const name = url.hostname.slice(0, -suffix.length);
			// Accept only sandbox names that are valid DNS labels
			if (!/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(name)) {
				return new Response("Not found", { status: 404 });
			}
			// Forward with the `http:` scheme, because `getTcpPort().fetch()`
			// does not accept `https:` URLs
			url.protocol = "http:";
			return env.MY_CONTAINER.getByName(name).fetch(new Request(url, request));
		}
		// Other hostnames manage previews.
		return new Response("Not found", { status: 404 });
	},
} satisfies ExportedHandler<Env>;
The server receives the full path and the preview hostname in the 
Host header.
Every request to a preview hostname goes to the preview. Keep routes that manage previews, such as stopping one, on other hostnames, so code in a preview cannot call them from its own origin. Authenticate preview visitors on the preview hostname, and do not send your application session cookie there.
Deploy your Worker:
Open the preview named 
ada in your browser, and store a value in its browser console. Replace 
example-previews.com with your preview domain:
https://ada.example-previews.com/
localStorage.setItem("name", "ada");
Open the preview named 
grace, and read the value in its browser console:
https://grace.example-previews.com/
localStorage.getItem("name");
The console prints 
null. Each preview hostname is a separate origin, so 
grace cannot read the storage of 
ada.
Serve previews under a subdomain
To serve previews under a subdomain of a domain you already use, such as 
previews.example.com, name the wildcard record and the route after that subdomain:
In the DNS settings of 
example.com, add a proxied 
AAAA record with the name 
*.previews and the content 
100::. A wildcard record named 
* does not apply below 
previews.example.com if that hostname has its own record, and it also matches every other unused subdomain of 
example.com. A record named 
*.previews matches only preview hostnames.
In 
wrangler.jsonc, set 
PREVIEW_DOMAIN to the subdomain and route its subdomains to your Worker:
{
	"vars": {
		"PREVIEW_DOMAIN": "previews.example.com",
	},
	"routes": [
		{
			"pattern": "*.previews.example.com/*",
			"zone_name": "example.com",
		},
	],
	"workers_dev": true,
}
:::caution[Certificates for deeper hostnames]
Universal SSL covers a domain and its first-level subdomains, such as 
ada.example-previews.com. It does not cover deeper hostnames such as 
ada.previews.example.com. To serve previews under a subdomain, add Total TLS or an advanced certificate for it. Without one, browsers show a certificate error on preview hostnames.
:::
Previews under a domain that your application also uses share cookies with your application. Browsers send a cookie set with 
Domain=example.com to every subdomain, including every preview under 
previews.example.com.
Set cookies on preview hostnames
Code in one preview can set a cookie with 
Domain=example-previews.com, and every other preview then receives that cookie. Set cookies on preview hostnames without a 
Domain attribute, and do not trust a cookie because it arrived on a preview hostname.
Troubleshooting
The server in the container uses HTTPS: Serve plain HTTP from the container. Cloudflare handles TLS for the preview hostname, and your Worker forwards each request to the container over HTTP. A server that only accepts HTTPS, such as one started with 
https.createServer() in Node.js or with a framework's HTTPS flag, cannot handle these requests. Start the server with HTTP instead.
Related resources
Preview a web application
Preview workspace example: a deployable Worker that runs a Vite development server on a separate hostname for each sandbox.
Sandbox security
Routes

DirectoryBackup API
import { MetaInfo, Type, TypeScriptExample } from "~/components";
DirectoryBackup saves a directory from a running container to an R2 bucket and restores it later into a container, including a container that runs a newer image. The container sends the backup through 
DirectoryBackupGateway in your Worker, so the container needs no Internet access and no R2 credentials. The gateway lets the container reach only the object that the operation needs. 
DirectoryBackup does not start or stop the container.
import {
	DirectoryBackup,
	type DirectoryBackupRecord,
} from "@cloudflare/sandbox";
import { DurableObject } from "cloudflare:workers";
export { DirectoryBackupGateway } from "@cloudflare/sandbox";
export class MyContainer extends DurableObject<Env> {
	readonly #backups: DirectoryBackup;
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		if (!ctx.container) {
			throw new Error("No container is configured");
		}
		// ctx.container stays the same object while the Durable Object runs.
		this.#backups = new DirectoryBackup(
			ctx.container,
			ctx.exports.DirectoryBackupGateway,
			{ binding: "BACKUPS", prefix: "workspaces/" },
		);
	}
	// The container must already be running.
	async saveWorkspace() {
		const backup = await this.#backups.backup({
			dir: "/workspace/app",
			exclude: ["node_modules/"],
		});
		// Keep the record. The package does not list backups.
		await this.ctx.storage.put("workspace", backup);
	}
	async restoreWorkspace() {
		const backup =
			await this.ctx.storage.get<DirectoryBackupRecord>("workspace");
		if (backup) {
			await this.#backups.restore(backup);
		}
	}
}
For a complete Worker, refer to Back up a directory to R2.
Requirements
In addition to the package requirements, 
DirectoryBackup has these requirements:
The Worker has an R2 bucket binding.
The main module of the Worker re-exports 
DirectoryBackupGateway from 
@cloudflare/sandbox:
export { DirectoryBackupGateway } from "@cloudflare/sandbox";
Do not route HTTP requests to 
DirectoryBackupGateway.
DirectoryBackup
new DirectoryBackup(
	container: Pick<Container, "exec" | "interceptOutboundHttp">,
	gateway: DirectoryBackupGatewayBinding,
	storage: DirectoryBackupStorage,
)
container — the container from 
this.ctx.container.
gateway — 
this.ctx.exports.DirectoryBackupGateway.
storage — where backups are stored. Refer to 
DirectoryBackupStorage.
An invalid 
storage throws 
TypeError.
Methods
backup
backup(options: DirectoryBackupOptions): Promise<DirectoryBackupRecord>
Saves 
options.dir as one object in the bucket and returns a 
DirectoryBackupRecord. For the options, refer to 
DirectoryBackupOptions. What a backup contains lists what the object keeps.
backup() reads the directory while processes can still change it, and it does not detect changes. A file that changes during the backup can be saved partly old and partly new. A backup is consistent only when no process writes to 
dir while it runs.
A backup that fails or is canceled returns no record, and 
backup() aborts its multipart upload. If the Durable Object restarts during a backup, the upload stays in the bucket until an R2 lifecycle rule aborts it.
restore
restore(backup: DirectoryBackupRecord, options?: DirectoryRestoreOptions): Promise<void>
Replaces the target directory with the contents of the backup. The target is 
dir from the record, unless you pass another absolute path in 
options.dir.
The parent directory of the target must exist. The target does not need to exist.
The target must not be a mount point or contain one, such as an 
S3Mount mount. Otherwise 
restore() fails with 
EBUSY, including when a mount appears during the restore. Unmount first, for example with 
S3Mount.unmount(), and mount again after the restore.
restore() extracts the backup into a new directory beside the target and checks the size and SHA-256 of the object against the record. It then replaces the target with the new directory in one atomic rename. When 
restore() throws 
SandboxFileError or 
SandboxBackupError, or is canceled before it verifies the download, it leaves the target as it was and removes the new directory.
A process that has its working directory inside the target, or has a file in the target open, keeps using the old directory or file. Restart such processes after 
restore(), or have them reopen files by absolute path.
The filesystem needs free space for the old and the restored directory at the same time. 
restore() stops with 
ENOSPC before free space falls below 5% of the filesystem or 256 MiB, whichever is smaller.
The root filesystem of a deployed container compresses files. 
restore() writes files without compression. The restored files take more disk space until a process rewrites them.
delete
delete(backup: DirectoryBackupRecord, options?: DirectoryBackupDeleteOptions): Promise<void>
Deletes the backup object. The container does not need to be running. Deleting an object that does not exist succeeds. A 
restore() that reads the object at the same time fails with 
BACKUP_NOT_FOUND or 
BACKUP_INTEGRITY.
intercept
intercept(): Promise<void>
Routes backup traffic from the container to 
DirectoryBackupGateway, which refuses every request until a backup or restore starts. 
intercept() does not start the container.
{/* Remove the second sentence and the last list item when a hostname intercept registered after interceptAllOutboundHttp() receives its requests. */}
backup() and 
restore() add this route themselves. If the Durable Object also calls 
interceptAllOutboundHttp(), call 
intercept() before it. Otherwise the catch-all receives the backup traffic from the container, and 
backup() and 
restore() fail with 
BACKUP_TRANSFER.
Call 
intercept() in the setup that runs after you start the container, and again when a restarted Durable Object finds the container running. Backups and restores in that container then keep their route.
Do not call 
intercept() while a backup or restore can be running. It replaces the access of the running operation, and the operation fails.
A container that registered the catch-all first keeps sending backup traffic to it. Restart the container to use 
intercept().
#setup: Promise<void> | null = null;
// Call before each use of the container.
#ensureRunning(container: Container): Promise<void> {
	// Set up each new container, and a running container
	// after this Durable Object restarts.
	if (this.#setup === null || !container.running) {
		this.#setup = this.#setUp(container).catch((error) => {
			this.#setup = null;
			throw error;
		});
	}
	return this.#setup;
}
async #setUp(container: Container): Promise<void> {
	if (!container.running) {
		container.start({
			image: container.images.sandbox,
			enableInternet: false,
		});
	}
	await this.#backups.intercept();
	await container.interceptAllOutboundHttp(
		this.ctx.exports.Outbound({ props: {} }),
	);
}
Types
DirectoryBackupRecord
The record that 
backup() returns. It is a plain object that you can store in Durable Object storage, a database, or JSON. The package keeps no list of backups.
id  — UUID of the backup. The object key is 
<prefix><id>.tar.zst.
dir  — absolute path of the directory that was backed up, and the default restore target.
size  — size of the stored object in bytes.
name   — the 
name passed to 
backup().
sha256  — SHA-256 of the stored object, as 64 lowercase hexadecimal characters. Every 
restore() checks it.
format  — archive format of the object.
restore() and 
delete() use the object at 
<prefix><id>.tar.zst in the bucket and prefix that the 
DirectoryBackup instance was created with, so pass a record to an instance whose storage holds that object. 
restore() checks the size and SHA-256 of the object against the record. A record that does not match this shape throws 
TypeError.
DirectoryBackupStorage
binding  — name of the R2 bucket binding in the Worker 
env, such as 
"BACKUPS".
prefix   — key prefix for the objects. A prefix that is not empty must end in 
/. The default is no prefix.
DirectoryBackupOptions
dir  — absolute path of the directory to back up.
name   — label stored in the record and in the custom metadata of the object as 
name.
exclude   — patterns in 
.gitignore syntax, relative to 
dir. 
"node_modules/" excludes every directory named 
node_modules. 
"/build" excludes only 
build at the top of 
dir.
gitignore   — also apply the 
.gitignore files inside 
dir and 
.git/info/exclude. Global Git excludes do not apply. The image does not need 
git. The default is 
false.
signal   — cancels the operation. Refer to Cancellation.
DirectoryRestoreOptions
dir   — absolute path of the directory to replace. The default is 
dir from the record.
signal   — cancels the operation. Refer to Cancellation.
DirectoryBackupDeleteOptions
signal   — an aborted signal rejects the call before the object is deleted.
An option that a method does not accept, or an option of the wrong type, throws 
TypeError.
What a backup contains
backup() walks 
dir without following symbolic links and does not enter other filesystems. A mount point inside 
dir becomes an empty directory in the backup. 
restore() works the other way: it refuses a target that contains a mount point. For more information, refer to 
restore. 
backup() includes every other path, including 
.git, unless 
exclude or 
gitignore leaves it out.
A backup keeps:
File contents
Directories, including empty ones
Symbolic links, as links
Hard links between files inside 
dir
Permission bits, and numeric user and group IDs
Modification times, to the nanosecond
A backup does not keep:
Sockets, devices, and FIFOs
The setuid and setgid bits
Extended attributes, ACLs, and file capabilities
Holes in sparse files, which restore as zeros
Access times
When the image user is root, 
restore() sets the saved user and group IDs as numbers, even when the image has no user with that ID. Otherwise, the restored files belong to the image user.
Operations in one container
One 
backup() or 
restore() runs at a time in a container. Other calls wait for it to finish, including calls from other 
DirectoryBackup instances and from a Durable Object that restarted. 
Promise.all() over several directories runs them one after another. 
delete() does not wait.
Cancellation
DirectoryBackup sets no timeouts and does not retry. Aborting 
signal rejects the call with the abort reason without waiting for the helper process, including a call that is still waiting for another operation. The helper process in the container then removes what the operation created and exits.
After 
restore() verifies the download, it finishes replacing the target even if 
signal aborts. The call then resolves when the target is replaced, or rejects with the error from replacing it.
When the Durable Object restarts during an operation, the result of the call is lost, and the helper process exits. A backup is not recorded. A restore has either replaced the whole target or left it as it was. Restoring the same backup again gives the same result either way.
DirectoryBackupGateway
DirectoryBackupGateway is a 
WorkerEntrypoint that moves backups between the container and the R2 bucket.
The container can reach only the object of the operation in progress. During a backup, it uploads parts of that object. During a restore, it reads byte ranges of it. It cannot list or delete objects or reach another key.
The SHA-256 check detects an object that changed after the backup.
The container sends HTTP requests to the gateway at 
backups.sandbox.internal, which 
DirectoryBackup routes with 
interceptOutboundHttp(). The Durable Object creates, completes, and aborts uploads, and deletes objects, through RPC calls to the gateway. The first operation in a container, or 
intercept(), adds the intercept target. Each later operation replaces the handler on that target and does not add a target.
Limits
The container uploads the compressed backup in parts of 16 MiB. An R2 multipart upload holds up to 10,000 parts, so a compressed backup can be at most 160,000 MiB, about 156 GiB. A larger backup fails with 
BACKUP_TRANSFER.
Local development
Under 
wrangler dev, the container runs in Docker, and 
restore() cannot replace a directory that is part of the image. The restore fails with 
SandboxFileError code 
EXDEV and leaves the directory as it was. 
restore() can replace a directory that was created after the container started, a directory in a volume, or a target that does not exist yet.
Errors
SandboxBackupError
The backup object is missing, changed, or could not be transferred.
Field
Type
Description
name
"SandboxBackupError"
Error name
code
SandboxBackupErrorCode
Error code
operation
DirectoryBackupOperation
Method that failed: 
backup or 
restore
path
string
Directory being backed up or restored
detail
string
Error description
code is one of the following values:
Code
Meaning
BACKUP_NOT_FOUND
The object does not exist
BACKUP_INTEGRITY
The object does not match the record, or it is not a valid archive. The target was not changed. 
backup() also throws it when R2 stored a different size than the container uploaded, and deletes the object
BACKUP_TRANSFER
An upload or download between the container and 
DirectoryBackupGateway failed, including when 
storage.binding does not name an R2 bucket binding. 
detail contains the HTTP status. No record was returned, and no directory was changed
The package exports the 
SandboxBackupErrorCode and 
DirectoryBackupOperation types, which list these codes and methods.
SandboxBackupError is not a class. Use 
SandboxBackupError.is(error) instead of 
instanceof. It recognizes errors thrown in the same Worker and errors returned through Durable Object RPC.
SandboxFileError
Linux rejected the operation in the container. 
operation is 
backup or 
restore. Refer to 
SandboxFileError.
Code
Condition
EBUSY
The restore target is a mount point or has one inside it
EINVAL
An 
exclude pattern is invalid
ENOENT
dir from the backup or the parent of the restore target does not exist
ENOSPC
The restore would fill the filesystem
ENOTDIR
dir from the backup or the restore target is a symbolic link or is not a directory
EXDEV
Linux could not swap the restored directory into place, as for a directory from the image under 
wrangler dev
Other codes, such as 
EACCES, come from reading a file during a backup.
SandboxProtocolError
DirectoryBackup could not complete its exchange with the helper binary. Refer to 
SandboxProtocolError.
Other errors
DirectoryBackup does not wrap errors from the runtime, from R2, or from its inputs.
Condition
Error
Invalid options, record, or 
storage
TypeError
storage.binding does not name an R2 bucket binding in 
backup() or 
delete()
TypeError from 
DirectoryBackupGateway
The container is not running
Error from 
exec()
signal is aborted
The abort reason
R2 rejects creating, completing, or aborting an upload, or deleting an object
The error from the R2 binding
An intercept cannot be added
Error from 
interceptOutboundHttp()
Related resources
Back up a directory to R2
Save and restore a workspace
Durable Object Container
R2 Workers API

Files API
import { TypeScriptExample } from "~/components";
Files reads and changes files and directories in a running container. It does not start or stop the container.
Each method runs the 
sandbox-shim helper binary in the container through 
exec(). Every method except 
readFile() waits for the helper to finish; 
readFile() returns once the file is open and streams its contents. Paths follow Linux rules, and 
Files does not restrict which paths a caller can open.
import { Files } from "@cloudflare/sandbox";
import { DurableObject } from "cloudflare:workers";
export class MyContainer extends DurableObject<Env> {
	private readonly files: Files;
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		if (!ctx.container) {
			throw new Error("No container is configured");
		}
		// ctx.container stays the same object while the Durable Object runs.
		this.files = new Files(ctx.container);
	}
	// The container must already be running.
	async readInput(): Promise<Response> {
		await this.files.mkdir("/workspace", { recursive: true });
		await this.files.writeFile("/workspace/input.txt", "hello\n");
		return this.files.readFile("/workspace/input.txt");
	}
}
For a complete Worker, refer to Move files in and out of a sandbox.
Requirements
Before you use 
Files, meet the package requirements: the helper binary in the image, the 
nodejs_compat flag, and a running container. 
Files has no other requirements.
Files
new Files(container: Pick<Container, "exec">)
container — the container from 
this.ctx.container, or any object with a compatible 
exec() method.
Paths
A path is absolute, or relative to the 
cwd option.
A relative path requires 
cwd. 
cwd must be absolute.
A path cannot be empty or contain a null character.
An invalid path or 
cwd throws 
TypeError before the helper process starts.
A relative path is joined onto 
cwd, and Linux resolves the joined path. An absolute path ignores 
cwd. A 
cwd that does not exist rejects with 
SandboxFileError 
ENOENT. So does a missing directory anywhere in a path.
Paths resolve through symbolic links as they do in Linux, except where a method states otherwise.
Options
Every method accepts 
FileOperationOptions:
interface FileOperationOptions {
	cwd?: string;
	user?: string;
	signal?: AbortSignal;
}
Option
Type
Description
cwd
string
Absolute directory that resolves a relative path. For 
rename(), it resolves both paths.
user
string
Numeric Linux user and group IDs as 
uid:gid, such as 
"1000:1000". Passed to 
exec(). When omitted, the helper runs as the image user. A user ID alone, or a user or group name, throws 
TypeError.
signal
AbortSignal
Cancels the operation and kills its helper process. A signal that fires after the operation finishes has no effect, including an 
AbortSignal.timeout() that outlives the call. The call rejects with the abort reason: 
AbortError from 
abort() without a reason, or 
TimeoutError from 
AbortSignal.timeout(). Cancellation can leave the partial effects that each method lists.
mkdir() also accepts 
recursive. 
remove() also accepts 
recursive and 
force. An option a method does not accept, or an option of the wrong type, throws 
TypeError before the helper process starts. Of these options, only 
user and 
signal reach 
exec().
Methods
readFile
readFile(path: string, options?: FileOperationOptions): Promise<Response>
Reads the contents of a file as bytes.
Returns a 
Response with status 
200 and no 
Content-Type header. The body applies backpressure to the helper process.
Rejects with 
SandboxFileError when the file cannot be opened, such as 
ENOENT for a missing file or 
EISDIR for a directory.
An error after the file opens errors the response body instead of rejecting the call.
Read the 
Response like any HTTP response. 
text(), 
json(), 
arrayBuffer(), and 
blob() load the whole file into memory. For a large file or a file of unknown size, stream 
body instead.
writeFile
writeFile(
	path: string,
	content:
		| string
		| ArrayBuffer
		| ArrayBufferView
		| Blob
		| ReadableStream<Uint8Array>,
	options?: FileOperationOptions,
): Promise<void>
Creates a file, or truncates an existing file, then streams 
content into it.
content is a 
FileContent value, such as a 
string, a 
Uint8Array, or a 
ReadableStream<Uint8Array>.
The parent directory must exist. A missing parent rejects with 
ENOENT. A directory at 
path rejects with 
EISDIR.
The file opens before a 
ReadableStream is consumed. A later failure can leave the file created, truncated, or partially written.
If the 
content stream errors, the call rejects with the error from the stream instead of a 
SandboxFileError.
rename() replaces an existing destination in one step. To keep other processes from reading a partially written file, write the file to a temporary path and then rename it:
await files.writeFile(`${path}.partial`, content, { cwd });
await files.rename(`${path}.partial`, path, { cwd });
stat
stat(path: string, options?: FileOperationOptions): Promise<SandboxFileStat>
Returns 
SandboxFileStat metadata for a path. Follows a symbolic link at the end of the path.
lstat
lstat(path: string, options?: FileOperationOptions): Promise<SandboxFileStat>
Returns 
SandboxFileStat metadata for a path without following a symbolic link at the end of the path. For a symbolic link, 
type is 
"symlink" and 
size is the length of the link target.
readDirectory
readDirectory(
	path: string,
	options?: FileOperationOptions,
): Promise<SandboxDirectoryEntry[]>
Returns the immediate entries of a directory as 
SandboxDirectoryEntry values.
The list is not sorted. The filesystem decides the order. The list does not include 
. or 
...
path can be a symbolic link to a directory. The method follows no other symbolic link.
The method does not recurse or return metadata for each entry.
A file at 
path rejects with 
ENOTDIR.
An entry name that is not valid UTF-8 rejects the whole call with 
EILSEQ.
To list a directory tree, walk it with 
readDirectory(). This walk does not follow symbolic links to directories:
import type { Files } from "@cloudflare/sandbox";
async function* walk(files: Files, directory: string): AsyncGenerator<string> {
	for (const entry of await files.readDirectory(directory)) {
		const path = `${directory}/${entry.name}`;
		yield path;
		if (entry.type === "directory") {
			yield* walk(files, path);
		}
	}
}
Each call to 
readDirectory() starts one process in the container. For a large tree, one 
container.exec(["find", directory]) call is faster. To cancel it, pass 
signal to 
exec().
mkdir
mkdir(path: string, options?: MkdirOptions): Promise<void>
type MkdirOptions = FileOperationOptions & {
	recursive?: boolean;
};
Creates a directory.
With 
recursive: true, the method creates missing parent directories. Without it, a missing parent rejects with 
ENOENT. 
recursive defaults to 
false.
An existing file at 
path rejects with 
EEXIST. An existing directory at 
path also rejects with 
EEXIST, unless 
recursive is 
true.
A file in place of a parent directory rejects with 
ENOTDIR.
A failed recursive call can leave the parents it created.
rename
rename(
	source: string,
	destination: string,
	options?: FileOperationOptions,
): Promise<void>
Renames a file, directory, or symbolic link with Linux 
rename rules.
An existing file at 
destination is replaced.
Renaming a directory onto a non-empty directory rejects with 
ENOTEMPTY.
Renaming across filesystems rejects with 
EXDEV.
The method does not fall back to copying and deleting.
SandboxFileError from this method sets both 
path and 
destination.
remove
remove(path: string, options?: RemoveOptions): Promise<void>
type RemoveOptions = FileOperationOptions & {
	recursive?: boolean;
	force?: boolean;
};
Removes a file or symbolic link. A symbolic link is removed, not its target.
A directory requires 
recursive: true. Without it, a directory rejects with 
EISDIR, even when 
force is 
true.
With 
recursive: true, the method removes the directory tree without following symbolic links inside it.
With 
force: true, a missing target resolves instead of rejecting with 
ENOENT.
A failed recursive call can leave part of the tree.
Types
FileContent
type FileContent =
	string | ArrayBuffer | ArrayBufferView | Blob | ReadableStream<Uint8Array>;
A string is written as UTF-8.
SandboxFileStat
Field
Type
Description
type
SandboxFileType
File type
size
bigint
Size in bytes
mode
number
Linux mode, including the file type bits. A regular file with permissions 
644 has mode 
0o100644.
uid
number
Owner user ID
gid
number
Owner group ID
accessedAt
Date
Last access time
modifiedAt
Date
Last content modification time
changedAt
Date
Last metadata change time
JSON.stringify() and 
Response.json() throw 
TypeError for a 
bigint. Convert 
size with 
Number() or 
String() before serializing a 
SandboxFileStat. 
bigint and 
Date values pass through Durable Object RPC unchanged.
SandboxDirectoryEntry
Field
Type
Description
name
string
Entry name
type
SandboxFileType
Entry type. A symbolic link has type 
"symlink".
SandboxFileType
type SandboxFileType =
	| "file"
	| "directory"
	| "symlink"
	| "blockDevice"
	| "characterDevice"
	| "fifo"
	| "socket";
Errors
SandboxFileError
Linux rejected a file operation.
Field
Type
Description
name
"SandboxFileError"
Error name
code
string
Linux error name, such as 
ENOENT. 
UNKNOWN when the runtime has no name for the error.
operation
string
Method that failed: 
readFile, 
writeFile, 
stat, 
lstat, 
readDirectory, 
mkdir, 
rename, or 
remove
path
string
Path passed to the method. For 
rename(), the source path.
destination
string
Destination path. Set only by 
rename(). 
undefined for every other method.
detail
string
Error description from the helper
The 
message has the form 
<operation> '<path>': <detail>, for example 
readFile 'notes.txt': No such file or directory (os error 2).
SandboxFileError is not a class. Use 
SandboxFileError.is(error) instead of 
instanceof. It recognizes errors thrown in the same Worker and errors returned through Durable Object RPC.
SandboxProtocolError
Files could not complete its exchange with the helper binary. A 
cloudflare/sandbox image tag that does not match the installed package version can cause this error.
Field
Type
Description
name
"SandboxProtocolError"
Error name
code
"SANDBOX_PROTOCOL_ERROR"
Error code
detail
string
Error description
Use 
SandboxProtocolError.is(error) to recognize the error.
Other errors
Files does not wrap errors from the runtime or from its inputs.
Condition
Error
Invalid path, 
cwd, or other option
TypeError
The container is not running
Error from 
exec()
The image does not contain the helper binary
Error from 
exec() that names 
/usr/local/bin/sandbox-shim
signal is aborted
The abort reason
The 
content stream of 
writeFile() errors
The error from the stream
Related resources
Move files in and out of a sandbox
Durable Object Container
Sandbox lifetime

@cloudflare/sandbox
import {
DirectoryListing,
PackageManagers,
TypeScriptExample,
WranglerConfig,
} from "~/components";
@cloudflare/sandbox works with a container you start from a Durable Object. Its classes run helper processes in the running container through 
exec(). The package does not start, stop, or monitor the container.
For 
start(), 
exec(), snapshots, and the other methods of the container itself, refer to the Durable Object container API.
Install
Requirements
Every class in the package has these requirements. A class page lists any others.
The container image contains the helper binary at 
/usr/local/bin/sandbox-shim. Copy it from the 
cloudflare/sandbox image whose tag matches the installed 
@cloudflare/sandbox version:
COPY --from=docker.io/cloudflare/sandbox:<VERSION> /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim
The helper is a statically linked 
linux/amd64 binary. It runs in any 
linux/amd64 image.
The Worker has the 
nodejs_compat compatibility flag. The package reads Linux error names through 
node:os.
The container is running when a method runs the helper. A class page lists the methods that do not need it, such as 
DirectoryBackup.delete().
Example configuration
This configuration meets every requirement. The 
Dockerfile copies the helper into a Debian Trixie image with Node.js 24, and 
sleep infinity keeps the container running:
FROM node:24-trixie-slim
COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim
RUN mkdir /workspace
CMD ["sleep", "infinity"]
The Wrangler configuration sets 
nodejs_compat, builds the 
Dockerfile as the image named 
workspace, and declares 
MyContainer as a Durable Object class:
{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "sandbox-files",
	"main": "src/index.ts",
	"upload_source_maps": true,
	"compatibility_date": "$today",
	"compatibility_flags": ["nodejs_compat"],
	"containers": [
		{
			"class_name": "MyContainer",
			"scheduling_policy": "durable_object",
			"images": {
				"workspace": {
					"dockerfile": "./Dockerfile",
				},
			},
		},
	],
	"durable_objects": {
		"bindings": [
			{
				"class_name": "MyContainer",
				"name": "MY_CONTAINER",
			},
		],
	},
	"exports": {
		"MyContainer": {
			"type": "durable-object",
			"storage": "sqlite",
		},
	},
}
The Durable Object starts the 
workspace image and passes the container to a class from the package:
import { Files } from "@cloudflare/sandbox";
import { DurableObject } from "cloudflare:workers";
const INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000;
export class MyContainer extends DurableObject<Env> {
	private readonly container: Container;
	private readonly files: Files;
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		const container = ctx.container;
		if (!container) {
			throw new Error("No container is configured");
		}
		this.container = container;
		// ctx.container stays the same object while the Durable Object runs.
		this.files = new Files(container);
		// A restarted Durable Object sets the timeout again.
		if (container.running) {
			void ctx.blockConcurrencyWhile(() =>
				container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS),
			);
		}
	}
	async listWorkspace() {
		// Files does not start the container.
		if (!this.container.running) {
			this.container.start({
				image: this.container.images.workspace,
				enableInternet: false,
			});
			await this.container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS);
		}
		return this.files.readDirectory("/workspace");
	}
}
For more information about building images, refer to 
images.
Classes

S3Mount API
import { MetaInfo, Type, TypeScriptExample } from "~/components";
S3Mount mounts an S3-compatible bucket, or a prefix in one, at a path in a running container. The container runs 
s3fs, which sends storage requests to 
S3Gateway in your Worker. 
S3Gateway checks each request and signs it with credentials that the container never receives. 
S3Mount does not start or stop the container.
import { S3Mount } from "@cloudflare/sandbox";
import { DurableObject } from "cloudflare:workers";
export { S3Gateway } from "@cloudflare/sandbox";
export class MyContainer extends DurableObject<Env> {
	private readonly mounts: S3Mount;
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		if (!ctx.container) {
			throw new Error("No container is configured");
		}
		// ctx.container stays the same object while the Durable Object runs.
		this.mounts = new S3Mount(ctx.container, ctx.exports.S3Gateway);
	}
	// The container must already be running.
	async mountModels() {
		await this.mounts.mount({
			mountPath: "/mnt/models",
			source: {
				type: "s3",
				endpoint: `https://${this.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
				region: "auto",
				bucket: "models",
				credentials: {
					type: "static",
					accessKeyId: this.env.R2_ACCESS_KEY_ID,
					secretAccessKey: this.env.R2_SECRET_ACCESS_KEY,
				},
			},
			keyPrefix: "production",
			access: "read-only",
		});
	}
}
For a complete Worker, refer to Mount an R2 bucket.
Requirements
In addition to the package requirements, 
S3Mount has these requirements:
The container image contains FUSE 3 and 
s3fs. In Debian and Ubuntu images, install the 
fuse3 and 
s3fs packages.
The main module of the Worker re-exports 
S3Gateway, so that 
this.ctx.exports.S3Gateway exists:
export { S3Gateway } from "@cloudflare/sandbox";
Do not route HTTP requests to 
S3Gateway.
S3Mount
new S3Mount(container: Pick<Container, "exec" | "interceptOutboundHttp">, gateway: S3GatewayBinding)
container — the container from 
this.ctx.container.
gateway — 
this.ctx.exports.S3Gateway.
Methods
mount
mount(request: S3MountRequest, options?: S3MountOperationOptions): Promise<void>
Mounts the source at 
request.mountPath. The result depends on what the path holds:
Nothing: 
mount() creates the directory and mounts the source.
A mount with the same settings: 
mount() reuses it.
Leftover state from a failed or canceled 
mount() with the same settings: 
mount() repairs it.
Another filesystem, or a mount with different settings: 
mount() throws 
SandboxS3MountError with code 
S3_MOUNT_CONFLICT. To change the settings, call 
unmount() first.
Each new mount adds one outbound intercept target to the container. Reusing a mount does not add one. 
unmount() does not remove one. Mounts share the container intercept limit with the intercepts your own code registers. Once the container reaches the limit, a mount with new settings fails.
{/* Remove this paragraph when a hostname intercept registered after interceptAllOutboundHttp() receives its requests. */}
If the Durable Object also calls 
interceptAllOutboundHttp(), call 
mount() before it, right after you start the container. Otherwise the catch-all receives the storage requests from the container, and 
mount() fails with 
cannot verify the new FUSE connection. A container that registered the catch-all first keeps sending storage requests to it. Restart the container to mount.
S3Mount does not retry a failed operation. Call 
inspect() before you retry.
inspect
inspect(mountPath: string, options?: S3MountOperationOptions): Promise<S3MountInspection>
Reports the state of a path without changing it. 
inspect() waits for a 
mount() or 
unmount() in progress on the same path. It then reads the mount state in the container and sends one list request for the prefix through 
S3Gateway.
Reading the mount state can block while the filesystem does not respond. 
inspect() has no timeout. Pass 
signal to set one.
Credentials that can read objects but cannot list the prefix produce a 
rejected upstream status.
unmount
unmount(mountPath: string, options?: S3MountOperationOptions): Promise<void>
Denies further storage requests for the mount, then unmounts the path. On a path with no mount, 
unmount() succeeds without changes. 
unmount() never forces an unmount.
When a process is using the path, 
unmount() throws 
S3_MOUNT_BUSY. Requests stay denied. Stop the process and call 
unmount() again, or call 
mount() with the same request to restore access.
After denial, new storage requests for the mount receive HTTP 
403. A request already in progress can complete.
After denial, a process that still uses the path can read empty files and lose writes without an error. Listing a directory fails.
A file that a process opened and read before the denial can stay readable through that open file.
Canceling 
unmount() or 
mount() can leave the filesystem mounted with requests denied. Call 
mount() with the same request, or call 
unmount() again.
Types
S3MountRequest
mountPath  — absolute, normalized path to mount at. Cannot be 
/, and cannot overlap 
/proc/self/mountinfo, 
/run/sandbox/s3-mounts, or 
/usr/local/bin/sandbox-shim.
source :
type  — source kind.
endpoint  — HTTP or HTTPS origin of the S3 API, with no credentials, path, query, or fragment. For R2, use 
https://<ACCOUNT_ID>.r2.cloudflarestorage.com.
region  — region used to sign requests. For R2, use 
auto.
bucket  — bucket name. Cannot start with 
- or contain 
/ or 
:.
credentials  — static credentials or a credential provider. Refer to Credentials.
keyPrefix   — object key prefix to mount. The mount shows only keys under the prefix. The prefix cannot start with 
/. 
S3Mount adds a trailing 
/. Omit it to mount the whole bucket.
access  — whether processes in the container can create, change, and delete objects.
s3fsOptions   — extra 
s3fs options. For the options, refer to the 
s3fs manual.
A 
true value adds the option as a flag, 
false omits it, and a string or number adds 
name=value.
Options that set the endpoint, credentials, access mode, proxy, or filesystem identity throw 
TypeError.
S3Mount always sets 
nomixupload. Passing 
nomixupload throws 
TypeError.
With 
nomixupload, a command that changes part of a large file uploads the whole file in parts of one size, as R2 requires.
S3Mount sets no cache, retry, or timeout options. The defaults of the 
s3fs version in your image apply.
S3Mount does not accept an R2 binding. Use the R2 S3 API endpoint with R2 API credentials.
Credentials
Static credentials:
type 
accessKeyId 
secretAccessKey 
sessionToken  
Provider credentials:
type 
fetcher  — called for each storage request that 
S3Gateway allows.
S3Gateway sends the provider 
GET https://credentials.sandbox.internal/ with 
Accept: application/json. The response must be JSON of at most 16 KiB:
{
	"accessKeyId": "<ACCESS_KEY_ID>",
	"secretAccessKey": "<SECRET_ACCESS_KEY>",
	"sessionToken": "<SESSION_TOKEN>",
	"expiresAt": 1790000000000
}
sessionToken is optional. 
expiresAt is a Unix time in milliseconds and must be in the future. 
S3Gateway does not cache credentials and does not retry a failed provider request.
S3MountOperationOptions
signal   — cancels the operation. The operation throws the abort reason.
S3MountInspection
Every inspection has 
mountPath and 
attachment.status:
attachment.status
Other fields
Meaning
absent
None
No mount at the path
unmanaged
attachment.filesystemType
Another filesystem is mounted at the path
incompatible
None
The path has state from an unsupported version
stale
attachment.configuration, 
gateway
Mount settings remain, but the filesystem is gone
managed
attachment.configuration, 
fuse, 
gateway
The mount is active
configuration — the endpoint, region, bucket, key prefix, access mode, and 
s3fs options of the mount.
fuse.status 
gateway.status 
gateway.upstream.status  — present when 
gateway.status is 
reachable.
S3Gateway
S3Gateway is a 
WorkerEntrypoint that handles storage requests from the container. 
S3Mount connects a separate 
S3Gateway to each mount.
The container receives placeholder credentials, because 
s3fs requires a key pair.
S3Gateway does not forward the 
Authorization header from the container. It signs each allowed request with the credentials of the mount.
S3Gateway allows only the object and list operations that 
s3fs uses, within the bucket and prefix of the mount. Other requests are rejected.
A read-only mount allows no writes.
Any process in the container that can reach the mount path can perform every allowed operation on the prefix. Limit the credentials to the bucket and prefix as well.
Mounted file behavior
A mounted directory maps files to objects in the bucket. It does not behave like a local disk:
Renaming a file copies the object and deletes the original.
File locks, hard links, ownership, permissions, and atomic replacement do not work as they do on a local filesystem.
Directories come from object key prefixes.
s3fs caches file metadata, including the fact that a file does not exist, for 900 seconds by default.
Until the cache expires, a file that another client adds to the bucket can stay missing in the container.
Until the cache expires, a file that another client changes can keep its old size, and a read can return the new content cut to that size.
To shorten the wait, set a lower 
stat_cache_expire in 
s3fsOptions. To stop caching missing files, set 
disable_noobj_cache: true.
An interrupted write can leave an incomplete upload in the bucket.
A snapshot does not include mounted directories.
Errors
SandboxS3MountError
A mount operation failed.
Field
Type
Description
name
"SandboxS3MountError"
Error name
code
SandboxS3MountErrorCode
Error code
operation
S3MountOperation
Method that failed: 
mount, 
inspect, or 
unmount
path
string
Path passed to the method
detail
string
Error description from the helper
code is one of the following values:
Code
Meaning
S3_MOUNT_CONFLICT
Another filesystem, or a mount with different settings, owns the path
S3_MOUNT_BUSY
A process is using the path
S3_MOUNT_FAILED
s3fs, FUSE, or another step of the operation failed
S3_MOUNT_INCOMPATIBLE
The path has state from an unsupported version
The package exports the 
SandboxS3MountErrorCode and 
S3MountOperation types, which list these codes and methods.
SandboxS3MountError is not a class. Use 
SandboxS3MountError.is(error) instead of 
instanceof. It recognizes errors thrown in the same Worker and errors returned through Durable Object RPC.
SandboxProtocolError
S3Mount could not complete its exchange with the helper binary. Refer to 
SandboxProtocolError.
Other errors
S3Mount does not wrap errors from the runtime or from its inputs.
Condition
Error
Invalid request or path
TypeError
The container is not running
Error from 
exec()
signal is aborted
The abort reason
An intercept cannot be added
Error from 
interceptOutboundHttp()
Related resources
Mount an R2 bucket
Durable Object Container
Sandbox security

Getting started
import { Render, PackageManagers, Steps, WranglerConfig } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/get-started/", title: "Get started" }} />
Build your first application with Sandbox SDK - a secure code execution environment. In this guide, you'll create a Worker that can execute Python code and work with files in isolated containers.
:::note[What you're building]
A simple API that can safely execute Python code and perform file operations in isolated sandbox environments.
:::
Prerequisites
Ensure Docker is running locally
Sandbox SDK uses Docker to build container images alongside your Worker.
1. Create a new project
Create a new Sandbox SDK project:
<PackageManagers
type="create"
pkg="cloudflare@latest"
args={"my-sandbox --template=cloudflare/sandbox-sdk/examples/minimal#v0"}
/>
This creates a 
my-sandbox directory with everything you need:
src/index.ts - Worker with sandbox integration
wrangler.jsonc - Configuration for Workers and Containers
Dockerfile - Container environment definition
cd my-sandbox
2. Explore the template
The template provides a minimal Worker that demonstrates core sandbox capabilities:
import { getSandbox, proxyToSandbox, type Sandbox } from "@cloudflare/sandbox";
export { Sandbox } from "@cloudflare/sandbox";
type Env = {
	Sandbox: DurableObjectNamespace<Sandbox>;
};
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);
		// Get or create a sandbox instance. For user-facing apps,
		// derive this ID from the authenticated user.
		const sandbox = getSandbox(env.Sandbox, "my-sandbox");
		// Execute Python code
		if (url.pathname === "/run") {
			const result = await sandbox.exec('python3 -c "print(2 + 2)"');
			return Response.json({
				output: result.stdout,
				error: result.stderr,
				exitCode: result.exitCode,
				success: result.success,
			});
		}
		// Work with files
		if (url.pathname === "/file") {
			await sandbox.writeFile("/workspace/hello.txt", "Hello, Sandbox!");
			const file = await sandbox.readFile("/workspace/hello.txt");
			return Response.json({
				content: file.content,
			});
		}
		return new Response("Try /run or /file");
	},
};
Key concepts:
getSandbox() - Gets or creates a sandbox instance by ID. Use a stable ID to reconnect to the same sandbox. In user-facing apps, scope IDs to a single user.
sandbox.exec() - Execute shell commands in the sandbox and capture stdout, stderr, and exit codes.
sandbox.writeFile() / 
readFile() - Write and read files in the sandbox filesystem.
3. Test locally
Start the development server:
npm run dev
# If you expect to have multiple sandbox instances, you can increase `max_instances`.
:::note
First run builds the Docker container (2-3 minutes). Subsequent runs are much faster due to caching.
:::
Test the endpoints:
# Execute Python code
curl http://localhost:8787/run
# File operations
curl http://localhost:8787/file
You should see JSON responses with the command output and file contents.
4. Deploy to production
Deploy your Worker and container:
npx wrangler deploy
This will:
Build your container image using Docker
Push it to Cloudflare's Container Registry
Deploy your Worker globally
:::caution[Wait for provisioning]
After the first deployment, wait several minutes before you expect sandbox requests to succeed. The Worker deploys immediately, but the container image still has to provision.
:::
Check deployment status:
npx wrangler containers list
5. Test your deployment
Visit your Worker URL (shown in deploy output):
# Replace with your actual URL
curl https://my-sandbox.YOUR_SUBDOMAIN.workers.dev/run
Your sandbox is now deployed and can execute code in isolated containers.
Understanding the configuration
Your 
wrangler.jsonc connects three pieces together:
{
	"containers": [
		{
			"class_name": "Sandbox",
			"image": "./Dockerfile",
			"instance_type": "lite",
			"max_instances": 1,
		},
	],
	"durable_objects": {
		"bindings": [
			{
				"class_name": "Sandbox",
				"name": "Sandbox",
			},
		],
	},
	"migrations": [
		{
			"new_sqlite_classes": ["Sandbox"],
			"tag": "v1",
		},
	],
}
containers - Defines the container image, instance type, and resource limits for your sandbox environment. If you expect to have multiple sandbox instances, you can increase 
max_instances.
durable_objects - You need not be familiar with Durable Objects to use Sandbox SDK, but if you'd like, you can learn more about Cloudflare Containers and Durable Objects. This configuration creates a binding that makes the 
Sandbox Durable Object accessible in your Worker code.
migrations - Registers the 
Sandbox class, implemented by the Sandbox SDK, with SQLite storage backend (required once)
For detailed configuration options including environment variables, secrets, and custom images, see the Wrangler configuration reference.
Next steps
Now that you have a working sandbox, explore more capabilities:
Code interpreter with Workers AI - Build an AI-powered code execution system
Execute commands - Run shell commands and stream output
Manage files - Work with files and directories
Deploy a Sandbox application - Deploy and keep package and image aligned
Expose services - Get public URLs for services running in your sandbox
Quick tunnels - Zero-config 
*.trycloudflare.com URLs for development and 
.workers.dev deployments
Configure preview URLs on a custom domain - Wildcard DNS and TLS for 
exposePort()
API reference - Complete API documentation

Sandbox SDK 0.x
import { CardGrid, LinkTitleCard, Plan } from "~/components";
:::note
These pages document 
@cloudflare/sandbox 0.x for existing applications. Version 1.0 is a different library that works with a container you start from a Durable Object. To move an existing application to 1.0, refer to Migrate from Sandbox SDK 0.x. To start new work, refer to Sandboxes.
:::
Sandbox SDK 0.x gives your Worker a 
Sandbox class built on Containers. A sandbox starts its container on first use, and its methods run commands, manage files, run background processes, and expose services in that container.
Move to 1.0
<LinkTitleCard
title="Migrate from Sandbox SDK 0.x"
href="/sandbox/sdk/migrate/"
icon="ph:arrow-circle-up"
Move a 0.12 application to a Durable Object that starts its own container.
<LinkTitleCard
title="API map"
href="/sandbox/sdk/migrate/api-map/"
icon="list-format"
Find what replaces each 0.12 API in 1.0.
Maintain a 0.x application
<LinkTitleCard
title="Getting started"
href="/sandbox/sdk/get-started/"
icon="rocket"
Create a Worker that runs Python code in a 0.x sandbox.
<LinkTitleCard
title="How-to guides"
href="/sandbox/sdk/guides/"
icon="seti:notebook"
Run commands, manage files, expose services, and deploy with Sandbox SDK 0.x.
	Look up the methods of the 0.x `Sandbox` class.
<LinkTitleCard
title="Tutorials"
href="/sandbox/sdk/tutorials/"
icon="open-book"
Build complete applications with Sandbox SDK 0.x.
Coding agents
Install Cloudflare Skills for your agent (Agent setup). Use 
sandbox-stable with these Sandbox SDK docs.

Backups
import { TypeScriptExample, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/files/save-and-restore-a-workspace/", title: "Save and restore a sandbox with snapshots" }} />
Create point-in-time snapshots of sandbox directories and restore them from R2.
For setup, restore workflows, and generated-cache exclusions, refer to Backup and restore. For overlay semantics, refer to Directory backups.
Methods
createBackup()
Create a snapshot of a directory and upload it to R2.
await sandbox.createBackup(options: BackupOptions): Promise<DirectoryBackup>
Parameters:
options - Backup configuration (see 
BackupOptions):
dir (required) - Absolute path to back up. Must be under 
/workspace, 
/home, 
/tmp, 
/var/tmp, or 
/app.
name (optional) - Human-readable name. Maximum 256 characters. Control characters are rejected.
ttl (optional) - Time-to-live in seconds. Default: 
259200 (3 days). Must be a positive number.
gitignore (optional) - When 
true, exclude paths matching 
.gitignore rules if 
dir is inside a git repository. Default: 
false. If the directory is not in a git repository, no git exclusions apply. If 
git is not installed, the SDK logs a warning and continues without git-based exclusions.
excludes (optional) - Glob patterns to omit from the archive. Passed to 
mksquashfs as wildcard excludes. 
** globstars are normalized automatically. Default: 
[].
localBucket (optional) - When 
true, use the 
BACKUP_BUCKET R2 binding instead of presigned URLs. Intended for 
wrangler dev. Default: 
false.
compression (optional) - Archive compression. Default format: 
lz4. Default threads: 
8. Format must be 
gzip, 
lz4, or 
zstd. 
threads must be a positive integer.
multipart (optional) - Use parallel multipart upload for large archives. Default: 
true.
Returns: 
Promise<DirectoryBackup> containing:
id - Unique backup identifier (UUID)
dir - Directory that was backed up
localBucket (optional) - Whether the backup used local R2 binding mode
import { getSandbox } from "@cloudflare/sandbox";
const sandbox = getSandbox(env.Sandbox, "my-sandbox");
const backup = await sandbox.createBackup({ dir: "/workspace" });
await sandbox.restoreBackup(backup);
How it works:
In production:
The container creates a compressed squashfs archive.
The container uploads the archive to R2 with a presigned URL.
Metadata is stored alongside the archive in R2.
The local archive is deleted.
With 
localBucket: true:
The container creates a compressed squashfs archive.
The archive is uploaded through the 
BACKUP_BUCKET R2 binding.
Metadata is stored alongside the archive in R2.
The local archive is deleted.
Throws:
InvalidBackupConfigError - If 
dir is not an allowed absolute path, the 
BACKUP_BUCKET binding is missing, or (in production) R2 presigned URL credentials are not configured
BackupCreateError - If archive creation or the upload to R2 fails
:::note[R2 binding required]
Configure a 
BACKUP_BUCKET R2 binding in 
wrangler.jsonc before using backup methods. Production also requires 
R2_ACCESS_KEY_ID, 
R2_SECRET_ACCESS_KEY, 
CLOUDFLARE_ACCOUNT_ID, and 
BACKUP_BUCKET_NAME. Refer to Backup and restore.
:::
:::caution[Path permissions]
mksquashfs must read every file and subdirectory in 
dir. Restrictive permissions fail with 
BackupCreateError. Refer to Fix path permissions.
:::
:::caution[Partial writes]
Partially written files may not be captured consistently. Completed writes are included.
:::
restoreBackup()
Restore a previously created backup.
await sandbox.restoreBackup(backup: DirectoryBackup): Promise<RestoreBackupResult>
Parameters:
backup - Handle returned by 
createBackup(). Contains 
id and 
dir. Restore writes into 
backup.dir, which may differ from the original backup path. (see 
DirectoryBackup)
Returns: 
Promise<RestoreBackupResult> containing:
success - Whether the restore succeeded
dir - Directory that was restored
id - Backup ID that was restored
await sandbox.restoreBackup(backup);
How it works:
In production:
Metadata is downloaded from R2 and the TTL is checked, with a 60-second buffer. An expired backup throws.
The container downloads the archive from R2 with a presigned URL.
The container mounts the archive with FUSE overlayfs.
With 
localBucket: true:
Metadata is downloaded from the 
BACKUP_BUCKET binding and the TTL is checked.
The archive is downloaded from the R2 binding.
The archive is extracted with 
unsquashfs.
Throws:
InvalidBackupConfigError - If 
backup.id is missing or not a UUID, or 
backup.dir is invalid
BackupNotFoundError - If the metadata or archive is not in R2
BackupExpiredError - If the TTL has elapsed
BackupRestoreError - If the container fails to restore
:::note[Copy-on-write]
In production, the backup is a read-only lower layer and new writes go to a writable upper layer. In local development, the directory is replaced. For overlay constraints, refer to Directory backups.
:::
:::caution[Ephemeral mount]
In production, the FUSE mount is lost when the sandbox sleeps or restarts. Restore again from the handle. Stop processes that write to the target directory before restoring.
:::
Behavior
Concurrent backup and restore operations on the same sandbox are serialized.
DirectoryBackup is serializable. Store it in KV, D1, or Durable Object storage.
Overlapping backups are independent. Restoring a parent directory overwrites subdirectory mounts. Restore the parent first when restoring both.
ttl is enforced at restore time only. Expired objects remain in R2 until you delete them or an R2 lifecycle rule removes them.
Backup objects use 
backups/{id}/data.sqsh and 
backups/{id}/meta.json.
Types
BackupOptions
interface BackupCompressionOptions {
	format?: "gzip" | "lz4" | "zstd";
	threads?: number;
}
interface BackupOptions {
	dir: string;
	name?: string;
	ttl?: number;
	gitignore?: boolean;
	excludes?: string[];
	localBucket?: boolean;
	compression?: BackupCompressionOptions;
	multipart?: boolean;
}
Fields:
dir (required) - Absolute path under 
/workspace, 
/home, 
/tmp, 
/var/tmp, or 
/app
name (optional) - Human-readable name. Maximum 256 characters. No control characters.
ttl (optional) - Time-to-live in seconds. Default: 
259200 (3 days). Must be a positive number.
gitignore (optional) - When 
true, exclude 
.gitignore matches if 
dir is inside a git repository. Default: 
false.
excludes (optional) - Glob patterns to omit. Example: 
['node_modules/.cache', '*.log']. Refer to Exclude generated caches.
localBucket (optional) - Use the 
BACKUP_BUCKET binding instead of presigned URLs. Default: 
false.
compression (optional) - 
format defaults to 
lz4. 
threads defaults to 
8.
multipart (optional) - Parallel multipart upload. Default: 
true.
DirectoryBackup
interface DirectoryBackup {
	readonly id: string;
	readonly dir: string;
	readonly localBucket?: boolean;
}
Fields:
id - Unique backup identifier (UUID)
dir - Directory to restore into
localBucket (optional) - Whether the backup used local R2 binding mode
RestoreBackupResult
interface RestoreBackupResult {
	success: boolean;
	dir: string;
	id: string;
}
Fields:
success - Whether the restore succeeded
dir - Directory that was restored
id - Backup ID that was restored
Related resources
Backup and restore - Setup and restore workflows
Directory backups - Overlay restore and 
EXDEV
Storage API - Mount S3-compatible buckets
Files API - Read and write files
Wrangler configuration - Configure bindings

Commands
import { Details, TypeScriptExample, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/containers/api/durable-object-container/#exec", title: "Container API" }} />
Execute commands and manage background processes in the sandbox's isolated container environment.
Methods
exec()
Execute a command and return the complete result.
const result = await sandbox.exec(command: string, options?: ExecOptions): Promise<ExecuteResponse>
Parameters:
command - The command to execute (can include arguments)
options (optional):
stream - Enable streaming callbacks (default: 
false)
onOutput - Callback for real-time output: 
(stream: 'stdout' | 'stderr', data: string) => void
timeout - Maximum execution time in milliseconds
env - Environment variables for this command: 
Record<string, string | undefined>
cwd - Working directory for this command
stdin - Data to pass to the command's standard input (enables arbitrary input without shell injection risks)
Returns: 
Promise<ExecuteResponse> with 
success, 
stdout, 
stderr, 
exitCode
```
const result = await sandbox.exec('npm run build');
if (result.success) {
console.log('Build output:', result.stdout);
} else {
console.error('Build failed:', result.stderr);
}
// With streaming
await sandbox.exec('npm install', {
stream: true,
onOutput: (stream, data) => console.log(
[${stream}] ${data})
});
// With environment variables (undefined values are skipped)
await sandbox.exec('node app.js', {
env: {
NODE_ENV: 'production',
PORT: '3000',
DEBUG_MODE: undefined // Skipped, uses container default or unset
}
});
// Pass input via stdin (no shell injection risks)
const result = await sandbox.exec('cat', {
stdin: 'Hello, world!'
});
console.log(result.stdout); // "Hello, world!"
// Process user input safely
const userInput = 'user@example.com\nsecret123';
await sandbox.exec('python process_login.py', {
stdin: userInput
});
</TypeScriptExample>
:::note[Timeout behavior]
When a command times out, the SDK raises an error on the caller side and closes the connection. The underlying process **continues running** inside the container. To stop a timed-out process, delete the session with [`deleteSession()`](/sandbox/sdk/api/sessions/#deletesession) or destroy the sandbox with [`destroy()`](/sandbox/sdk/api/lifecycle/#destroy).
Timeout precedence: per-command `timeout` on `exec()` > session-level `commandTimeoutMs` on [`createSession()`](/sandbox/sdk/api/sessions/#createsession) > global [`COMMAND_TIMEOUT_MS`](/sandbox/sdk/configuration/environment-variables/#command_timeout_ms) environment variable. If none are set, commands run without a timeout.
:::
### `execStream()`
Execute a command and return a Server-Sent Events stream for real-time processing.
```ts
const stream = await sandbox.execStream(command: string, options?: ExecOptions): Promise<ReadableStream>
Parameters:
command - The command to execute
options - Same as 
exec() (including 
stdin support)
Returns: 
Promise<ReadableStream> emitting 
ExecEvent objects (
start, 
stdout, 
stderr, 
complete, 
error)
```
import { parseSSEStream, type ExecEvent } from '@cloudflare/sandbox';
const stream = await sandbox.execStream('npm run build');
for await (const event of parseSSEStream(stream)) {
switch (event.type) {
case 'stdout':
console.log('Output:', event.data);
break;
case 'complete':
console.log('Exit code:', event.exitCode);
break;
case 'error':
console.error('Failed:', event.error);
break;
}
}
// Stream with stdin input
const inputStream = await sandbox.execStream('python -c "import sys; print(sys.stdin.read())"', {
stdin: 'Data from Workers!'
});
for await (const event of parseSSEStream(inputStream)) {
if (event.type === 'stdout') {
console.log('Python received:', event.data);
}
}
</TypeScriptExample>
### `startProcess()`
Start a long-running background process.
```ts
const process = await sandbox.startProcess(command: string, options?: ProcessOptions): Promise<Process>
Parameters:
command - The command to start as a background process
options (optional):
cwd - Working directory
env - Environment variables: 
Record<string, string | undefined>
stdin - Data to pass to the command's standard input
timeout - Maximum execution time in milliseconds
processId - Custom process ID
encoding - Output encoding (default: 
'utf8')
autoCleanup - Whether to clean up process on sandbox sleep
Returns: 
Promise<Process> object with:
id - Unique process identifier
pid - System process ID
command - The command being executed
status - Current status (
'running', 
'exited', etc.)
kill() - Stop the process
getStatus() - Get current status
getLogs() - Get accumulated logs
waitForPort() - Wait for process to listen on a port
waitForLog() - Wait for pattern in process output
waitForExit() - Wait for process to terminate and return exit code
```
const server = await sandbox.startProcess('python -m http.server 8000');
console.log('Started with PID:', server.pid);
// With custom environment
const app = await sandbox.startProcess('node app.js', {
cwd: '/workspace/my-app',
env: { NODE_ENV: 'production', PORT: '3000' }
});
// Start process with stdin input (useful for interactive applications)
const interactive = await sandbox.startProcess('python interactive_app.py', {
stdin: 'initial_config\nstart_mode\n'
});
</TypeScriptExample>
### `listProcesses()`
List all running processes.
```ts
const processes = await sandbox.listProcesses(): Promise<ProcessInfo[]>
```
const processes = await sandbox.listProcesses();
for (const proc of processes) {
console.log(
${proc.id}: ${proc.command} (PID ${proc.pid}));
}
</TypeScriptExample>
### `killProcess()`
Terminate a specific process and all of its child processes.
```ts
await sandbox.killProcess(processId: string, signal?: string): Promise<void>
Parameters:
processId - The process ID (from 
startProcess() or 
listProcesses())
signal - Signal to send (default: 
"SIGTERM")
Sends the signal to the entire process group, ensuring that both the main process and any child processes it spawned are terminated. This prevents orphaned processes from continuing to run after the parent is killed.
```
const server = await sandbox.startProcess('python -m http.server 8000');
await sandbox.killProcess(server.id);
// Example with a process that spawns children
const script = await sandbox.startProcess('bash -c "sleep 10 & sleep 10 & wait"');
// killProcess terminates both sleep commands and the bash process
await sandbox.killProcess(script.id);
</TypeScriptExample>
### `killAllProcesses()`
Terminate all running processes.
```ts
await sandbox.killAllProcesses(): Promise<void>
```
await sandbox.killAllProcesses();
```
streamProcessLogs()
Stream logs from a running process in real-time.
const stream = await sandbox.streamProcessLogs(processId: string): Promise<ReadableStream>
Parameters:
processId - The process ID
Returns: 
Promise<ReadableStream> emitting 
LogEvent objects
```
import { parseSSEStream, type LogEvent } from '@cloudflare/sandbox';
const server = await sandbox.startProcess('node server.js');
const logStream = await sandbox.streamProcessLogs(server.id);
for await (const log of parseSSEStream(logStream)) {
console.log(
[${log.timestamp}] ${log.data});
if (log.data.includes('Server started')) break;
}
</TypeScriptExample>
### `getProcessLogs()`
Get accumulated logs from a process.
```ts
const logs = await sandbox.getProcessLogs(processId: string): Promise<string>
Parameters:
processId - The process ID
Returns: 
Promise<string> with all accumulated output
```
const server = await sandbox.startProcess('node server.js');
await new Promise(resolve => setTimeout(resolve, 5000));
const logs = await sandbox.getProcessLogs(server.id);
console.log('Server logs:', logs);
</TypeScriptExample>
## Standard input (stdin)
All command execution methods support passing data to a command's standard input via the `stdin` option. This enables secure processing of user input without shell injection risks.
### How stdin works
When you provide the `stdin` option:
1. The input data is written to a temporary file inside the container
2. The command receives this data through its standard input stream
3. The temporary file is automatically cleaned up after execution
This approach prevents shell injection attacks that could occur when embedding user data directly in commands.
<TypeScriptExample>
// Safe: User input goes through stdin, not shell parsing
const userInput = 'user@domain.com; rm -rf /';
const result = await sandbox.exec('python validate_email.py', {
stdin: userInput
});
// Instead of unsafe: 
python validate_email.py "${userInput}"
// which could execute the embedded 
rm -rf / command
</TypeScriptExample>
### Common patterns
**Processing form data:**
<TypeScriptExample>
const formData = JSON.stringify({
username: 'john_doe',
email: 'john@example.com'
});
const result = await sandbox.exec('python process_form.py', {
stdin: formData
});
</TypeScriptExample>
**Interactive command-line tools:**
<TypeScriptExample>
// Simulate user responses to prompts
const responses = 'yes\nmy-app\n1.0.0\n';
const result = await sandbox.exec('npm init', {
stdin: responses
});
</TypeScriptExample>
**Data transformation:**
<TypeScriptExample>
const csvData = 'name,age,city\nJohn,30,NYC\nJane,25,LA';
const result = await sandbox.exec('python csv_processor.py', {
stdin: csvData
});
console.log('Processed data:', result.stdout);
</TypeScriptExample>
## Process readiness methods
The `Process` object returned by `startProcess()` includes methods to wait for the process to be ready before proceeding.
### `process.waitForPort()`
Wait for a process to listen on a port.
```ts
await process.waitForPort(port: number, options?: WaitForPortOptions): Promise<void>
Parameters:
port - The port number to check
options (optional):
mode - Check mode: 
'http' (default) or 
'tcp'
timeout - Maximum wait time in milliseconds
interval - Check interval in milliseconds (default: 
100)
path - HTTP path to check (default: 
'/', HTTP mode only)
status - Expected HTTP status range (default: 
{ min: 200, max: 399 }, HTTP mode only)
HTTP mode (default) makes an HTTP GET request and checks the response status:
```
const server = await sandbox.startProcess('node server.js');
// Wait for server to be ready (HTTP mode)
await server.waitForPort(3000);
// Check specific endpoint and status
await server.waitForPort(8080, {
path: '/health',
status: { min: 200, max: 299 },
timeout: 30000
});
</TypeScriptExample>
**TCP mode** checks if the port accepts connections:
<TypeScriptExample>
const db = await sandbox.startProcess('redis-server');
// Wait for database to accept connections
await db.waitForPort(6379, {
mode: 'tcp',
timeout: 10000
});
</TypeScriptExample>
**Throws**:
- `ProcessReadyTimeoutError` - If port does not become ready within timeout
- `ProcessExitedBeforeReadyError` - If process exits before becoming ready
### `process.waitForLog()`
Wait for a pattern to appear in process output.
```ts
const result = await process.waitForLog(pattern: string | RegExp, timeout?: number): Promise<WaitForLogResult>
Parameters:
pattern - String or RegExp to match in stdout/stderr
timeout - Maximum wait time in milliseconds (optional)
Returns: 
Promise<WaitForLogResult> with:
line - The matching line of output
matches - Array of capture groups (for RegExp patterns)
```
const server = await sandbox.startProcess('node server.js');
// Wait for string pattern
const result = await server.waitForLog('Server listening');
console.log('Ready:', result.line);
// Wait for RegExp with capture groups
const result = await server.waitForLog(/Server listening on port (\d+)/);
console.log('Port:', result.matches[1]); // Extracted port number
// With timeout
await server.waitForLog('Ready', 30000);
</TypeScriptExample>
**Throws**:
- `ProcessReadyTimeoutError` - If pattern is not found within timeout
- `ProcessExitedBeforeReadyError` - If process exits before pattern appears
### `process.waitForExit()`
Wait for a process to terminate and return the exit code.
```ts
const result = await process.waitForExit(timeout?: number): Promise<WaitForExitResult>
Parameters:
timeout - Maximum wait time in milliseconds (optional)
Returns: 
Promise<WaitForExitResult> with:
exitCode - The process exit code
```
const build = await sandbox.startProcess('npm run build');
// Wait for build to complete
const result = await build.waitForExit();
console.log('Build finished with exit code:', result.exitCode);
// With timeout
const result = await build.waitForExit(60000); // 60 second timeout
</TypeScriptExample>
**Throws**:
- `ProcessReadyTimeoutError` - If process does not exit within timeout
## Related resources
- [Background processes guide](/sandbox/sdk/guides/background-processes/) - Managing long-running processes
- [Files API](/sandbox/sdk/api/files/) - File operations

File watching
import { TypeScriptExample, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
Monitor filesystem changes in real-time using Linux's native inotify system. The 
watch() method returns a Server-Sent Events (SSE) stream of file change events that you consume with 
parseSSEStream().
Methods
watch()
Watch a directory for filesystem changes. Returns an SSE stream of events.
const stream = await sandbox.watch(path: string, options?: WatchOptions): Promise<ReadableStream<Uint8Array>>
Parameters:
path - Absolute path or relative to 
/workspace (for example, 
/app/src or 
src)
options (optional):
recursive - Watch subdirectories recursively (default: 
true)
include - Glob patterns to include (for example, 
['*.ts', '*.js']). Cannot be used together with 
exclude.
exclude - Glob patterns to exclude (default: 
['.git', 'node_modules', '.DS_Store']). Cannot be used together with 
include.
sessionId - Session to run the watch in (if omittied, will use the default session unless 
enableDefaultSession is set to false)
Returns: 
Promise<ReadableStream<Uint8Array>> — an SSE stream of 
FileWatchSSEEvent objects
import { parseSSEStream } from "@cloudflare/sandbox";
import type { FileWatchSSEEvent } from "@cloudflare/sandbox";
const stream = await sandbox.watch("/workspace/src", {
	recursive: true,
	include: ["*.ts", "*.js"],
});
const controller = new AbortController();
for await (const event of parseSSEStream<FileWatchSSEEvent>(
	stream,
	controller.signal,
)) {
	switch (event.type) {
		case "watching":
			console.log(`Watch established on ${event.path} (id: ${event.watchId})`);
			break;
		case "event":
			console.log(`${event.eventType}: ${event.path}`);
			break;
		case "error":
			console.error(`Watch error: ${event.error}`);
			break;
		case "stopped":
			console.log(`Watch stopped: ${event.reason}`);
			break;
	}
}
// Cancel the watch by aborting — cleans up the watcher server-side
controller.abort();
:::note
The 
watch() method is also available on sessions. When called on a session, the 
sessionId is set automatically:
const session = await sandbox.createSession();
const stream = await session.watch("/workspace/src", {
	include: ["*.ts"],
});
:::
Types
FileWatchSSEEvent
Union type of all SSE events emitted by the watch stream.
type FileWatchSSEEvent =
	| { type: "watching"; path: string; watchId: string }
	| {
			type: "event";
			eventType: FileWatchEventType;
			path: string;
			isDirectory: boolean;
			timestamp: string;
	  }
	| { type: "error"; error: string }
	| { type: "stopped"; reason: string };
watching — Emitted once when the watch is established. Contains the 
watchId and the 
path being watched.
event — Emitted for each filesystem change. Contains the 
eventType, the 
path that changed, and whether it 
isDirectory.
error — Emitted when the watch encounters an error.
stopped — Emitted when the watch is stopped, with a 
reason.
FileWatchEventType
Types of filesystem changes that can be detected.
type FileWatchEventType =
	| "create"
	| "modify"
	| "delete"
	| "move_from"
	| "move_to"
	| "attrib";
create — File or directory was created
modify — File content changed
delete — File or directory was deleted
move_from — File or directory was moved away (source of a rename/move)
move_to — File or directory was moved here (destination of a rename/move)
attrib — File or directory attributes changed (permissions, timestamps)
WatchOptions
Configuration options for watching directories.
interface WatchOptions {
	/** Watch subdirectories recursively (default: true) */
	recursive?: boolean;
	/** Glob patterns to include. Cannot be used together with `exclude`. */
	include?: string[];
	/** Glob patterns to exclude. Cannot be used together with `include`. Default: ['.git', 'node_modules', '.DS_Store'] */
	exclude?: string[];
	/** Session to run the watch in. If omitted, the sandbox's implicit execution mode is used. */
	sessionId?: string;
}
:::caution[Mutual exclusivity]
include and 
exclude cannot be used together. Use 
include to allowlist patterns, or 
exclude to blocklist patterns. Requests that specify both are rejected with a validation error.
:::
parseSSEStream()
Converts a 
ReadableStream<Uint8Array> into a typed 
AsyncGenerator of events. Accepts an optional 
AbortSignal to cancel the stream.
function parseSSEStream<T>(
	stream: ReadableStream<Uint8Array>,
	signal?: AbortSignal,
): AsyncGenerator<T>;
Parameters:
stream — The SSE stream returned by 
watch()
signal (optional) — An 
AbortSignal to cancel the stream. When aborted, the reader is cancelled which propagates cleanup to the server.
Aborting the signal is the recommended way to stop a watch from outside the consuming loop:
const controller = new AbortController();
// Cancel after 60 seconds
setTimeout(() => controller.abort(), 60_000);
for await (const event of parseSSEStream<FileWatchSSEEvent>(
	stream,
	controller.signal,
)) {
	// process events
}
Glob pattern support
The 
include and 
exclude options accept a limited set of glob tokens for predictable matching:
Token
Meaning
Example
*
Match any characters within a path segment
*.ts matches 
index.ts
**
Match across directory boundaries
**/*.test.ts
?
Match a single character
?.js matches 
a.js
Character classes (
[abc]), brace expansion (
{a,b}), and backslash escapes are not supported. Patterns containing these tokens are rejected with a validation error.
Notes
:::note[Deterministic readiness]
watch() blocks until the filesystem watcher is established on the server. When the promise resolves, the watcher is active and you can immediately perform filesystem actions that depend on the watch being in place.
:::
:::note[Container lifecycle]
File watchers are automatically stopped when the sandbox container sleeps or is destroyed. You do not need to manually cancel the stream on container shutdown.
:::
:::caution[Path requirements]
All paths must exist when starting a watch. Watching non-existent paths returns an error. Create directories before watching them. All paths must resolve to within 
/workspace.
:::
Related resources
Watch filesystem changes guide — Patterns, best practices, and real-world examples
Manage files guide — File operations

Files
import { TypeScriptExample, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/reference/files/", title: "Files API" }} />
Read, write, and manage files in the sandbox filesystem. All paths are absolute (e.g., 
/workspace/app.js).
Methods
writeFile()
Write content to a file.
await sandbox.writeFile(path: string, content: string, options?: WriteFileOptions): Promise<void>
Parameters:
path - Absolute path to the file
content - Content to write
options (optional):
encoding - File encoding (
"utf-8" or 
"base64", default: 
"utf-8")
```
await sandbox.writeFile('/workspace/app.js', `console.log('Hello!');`);
// Binary data
await sandbox.writeFile('/tmp/image.png', base64Data, { encoding: 'base64' });
</TypeScriptExample>
:::note[Base64 validation]
When using `encoding: 'base64'`, content must contain only valid base64 characters (A-Z, a-z, 0-9, +, /, =). Invalid base64 content returns a validation error.
:::
#### Large files and binary data
When using the [`rpc` transport](/sandbox/sdk/configuration/transport/) the `writeFile()` method supports passing a `ReadableStream` as the `content` parameter. This allows binary data and files greater than [32 MiB](/workers/runtime-apis/rpc/#limitations) to be written to the sandbox. It replaces the `"base64"` encoding option.
```js
// Requires SANDBOX_TRANSPORT to be "rpc" in wrangler.jsonc
const req = await fetch("https://example.com/archive.tar.gz");
await sandbox.writeFile('/workspace/archive.tar.gz', req.body);
readFile()
Read a file from the sandbox. By default returns the content as a string. This is useful for small text files. For larger files and binary data use 
encoding: "none" to get back a 
ReadableStream with the file data.
const file = await sandbox.readFile(path: string, options?: ReadFileOptions): Promise<ReadFileResult | ReadFileStreamResult>
Parameters:
path - Absolute path to the file
options (optional):
encoding - File encoding (
"utf-8", 
"base64" or 
"none", default: auto-detected from MIME type)
Returns: 
Promise<ReadFileResult | ReadFileStreamResult>.
:::note[Encoding]
The 
"none" encoding property was added in 0.10.1 and aims to improve support for streaming binary data. When 
encoding: "none" is provided the 
content field will be a 
ReadableStream<Uint8Array>. It is only supported with the RPC transport.
:::
```
const file = await sandbox.readFile('/workspace/package.json');
const pkg = JSON.parse(file.content);
// Binary data (since 0.10.1 using 
rpc transport)
const { content, size, mimeType } = await sandbox.readFile("/workspace/archive.tar.gz", {
encoding: "none"
});
// Example 1: Store on R2:
const stream = request.body.pipeThrough(new FixedLengthStream(size));
await env.MY_BUCKET.put('/bucket/archive.tar.gz', stream, {
httpMetadata: { contentType: mimeType }
});
// Example 2: Stream an HTTP response:
return new Response(content, { headers: { "Content-Type": mimeType } });
// Older versions/transports used the base64 encoding for binary data:
const archive = await sandbox.readFile("/workspace/archive.tar.gz", {
encoding: "base64"
});
console.log(archive.content); // => "";
</TypeScriptExample>
:::note[Encoding behavior]
When `encoding` is specified, it overrides MIME-based auto-detection. Without `encoding`, the SDK detects the appropriate encoding from the file's MIME type.
:::
### `exists()`
Check if a file or directory exists.
```ts
const result = await sandbox.exists(path: string): Promise<FileExistsResult>
Parameters:
path - Absolute path to check
Returns: 
Promise<FileExistsResult> with 
exists boolean
```
const result = await sandbox.exists('/workspace/package.json');
if (result.exists) {
  const file = await sandbox.readFile('/workspace/package.json');
  // process file
}
// Check directory
const dirResult = await sandbox.exists('/workspace/src');
if (!dirResult.exists) {
await sandbox.mkdir('/workspace/src');
}
</TypeScriptExample>
:::note[Available on sessions]
Both `sandbox.exists()` and `session.exists()` are supported.
:::
### `mkdir()`
Create a directory.
```ts
await sandbox.mkdir(path: string, options?: MkdirOptions): Promise<void>
Parameters:
path - Absolute path to the directory
options (optional):
recursive - Create parent directories if needed (default: 
false)
```
await sandbox.mkdir('/workspace/src');
// Nested directories
await sandbox.mkdir('/workspace/src/components/ui', { recursive: true });
</TypeScriptExample>
### `deleteFile()`
Delete a file.
```ts
await sandbox.deleteFile(path: string): Promise<void>
Parameters:
path - Absolute path to the file
```
await sandbox.deleteFile('/workspace/temp.txt');
```
renameFile()
Rename a file.
await sandbox.renameFile(oldPath: string, newPath: string): Promise<void>
Parameters:
oldPath - Current file path
newPath - New file path
```
await sandbox.renameFile('/workspace/draft.txt', '/workspace/final.txt');
```
moveFile()
Move a file to a different directory.
await sandbox.moveFile(sourcePath: string, destinationPath: string): Promise<void>
Parameters:
sourcePath - Current file path
destinationPath - Destination path
```
await sandbox.moveFile('/tmp/download.txt', '/workspace/data.txt');
```
gitCheckout()
Clone a git repository.
await sandbox.gitCheckout(repoUrl: string, options?: GitCheckoutOptions): Promise<void>
Parameters:
repoUrl - Git repository URL
options (optional):
branch - Branch to checkout (default: repository default branch)
targetDir - Directory to clone into (default: 
/workspace/{repoName})
depth - Clone depth for shallow clones (e.g., 
1 for latest commit only)
```
await sandbox.gitCheckout('https://github.com/user/repo');
// Specific branch
await sandbox.gitCheckout('https://github.com/user/repo', {
branch: 'develop',
targetDir: '/workspace/my-project'
});
// Shallow clone (faster for large repositories)
await sandbox.gitCheckout('https://github.com/facebook/react', {
depth: 1
});
</TypeScriptExample>
## Related resources
- [Manage files guide](/sandbox/sdk/guides/manage-files/) - Detailed guide with best practices
- [Commands API](/sandbox/sdk/api/commands/) - Execute commands

API reference
import { LinkTitleCard, CardGrid, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
The Sandbox SDK provides a comprehensive API for executing code, managing files, running processes, and exposing services in isolated sandboxes.
	Create and manage sandbox containers. Get sandbox instances, configure
	options, and clean up resources.
	Execute commands and stream output. Run scripts, manage background processes,
	and capture execution results.
	Read, write, and manage files in the sandbox filesystem. Includes directory
	operations and file metadata.
<LinkTitleCard
title="File watching"
href="/sandbox/sdk/api/file-watching/"
icon="seti:eye"
Monitor real-time filesystem changes using native inotify. Build development
tools, hot-reload systems, and responsive file processing.
<LinkTitleCard
title="Code interpreter"
href="/sandbox/sdk/api/interpreter/"
icon="laptop"
Execute Python and JavaScript code with rich outputs including charts, tables,
and formatted data.
	Expose services running in the sandbox via preview URLs. Access web servers
	and APIs from the internet.
	Expose services on zero-config `*.trycloudflare.com` URLs via
	`sandbox.tunnels.get(port)`. Best for quick development and `.workers.dev`
	deployments.
	Mount S3-compatible buckets (R2, S3, GCS) as local filesystems for persistent
	data storage across sandbox lifecycles.
	Create point-in-time snapshots of directories and restore them from R2.
	Create isolated execution contexts within a sandbox. Each session maintains
	its own shell state, environment variables, and working directory.
	Connect browser-based terminal UIs to sandbox shells via WebSocket, with the
	xterm.js SandboxAddon for automatic reconnection and resize handling.

Code interpreter
import { TypeScriptExample, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
Execute Python, JavaScript, and TypeScript code with support for data visualizations, tables, and rich output formats. Contexts maintain state (variables, imports, functions) across executions.
Methods
createCodeContext()
Create a persistent execution context for running code.
const context = await sandbox.createCodeContext(options?: CreateContextOptions): Promise<CodeContext>
Parameters:
options (optional):
language - 
"python" | "javascript" | "typescript" (default: 
"python")
cwd - Working directory (default: 
"/workspace")
envVars - Environment variables
timeout - Request timeout in milliseconds (default: 30000)
Returns: 
Promise<CodeContext> with 
id, 
language, 
cwd, 
createdAt, 
lastUsed
```
const ctx = await sandbox.createCodeContext({
  language: 'python',
  envVars: { API_KEY: env.API_KEY }
});
```
runCode()
Execute code in a context and return the complete result.
const result = await sandbox.runCode(code: string, options?: RunCodeOptions): Promise<ExecutionResult>
Parameters:
code - The code to execute (required)
options (optional):
context - Context to run in (recommended - see below)
language - 
"python" | "javascript" | "typescript" (default: 
"python")
timeout - Execution timeout in milliseconds (default: 60000)
onStdout, 
onStderr, 
onResult, 
onError - Streaming callbacks
Returns: 
Promise<ExecutionResult> with:
code - The executed code
logs - 
stdout and 
stderr arrays
results - Array of rich outputs (see Rich Output Formats)
error - Execution error if any
executionCount - Execution counter
Recommended usage - create explicit context:
```
const ctx = await sandbox.createCodeContext({ language: 'python' });
await sandbox.runCode('import math; radius = 5', { context: ctx });
const result = await sandbox.runCode('math.pi * radius ** 2', { context: ctx });
console.log(result.results[0].text); // "78.53981633974483"
</TypeScriptExample>
:::note[Default context behavior]
If no `context` is provided, a default context is automatically created/reused for the specified `language`. While convenient for quick tests, **explicitly creating contexts is recommended** for production use to maintain predictable state.
<TypeScriptExample>
const result = await sandbox.runCode(
data = [1, 2, 3, 4, 5] print(f"Sum: {sum(data)}") sum(data), { language: 'python' });
console.log(result.logs.stdout); // ["Sum: 15"]
console.log(result.results[0].text); // "15"
</TypeScriptExample>
:::
**Error handling**:
<TypeScriptExample>
const result = await sandbox.runCode('x = 1 / 0', { language: 'python' });
if (result.error) {
console.error(result.error.name);      // "ZeroDivisionError"
console.error(result.error.value);     // "division by zero"
console.error(result.error.traceback); // Stack trace array
}
</TypeScriptExample>
**JavaScript and TypeScript features**:
JavaScript and TypeScript code execution supports top-level `await` and persistent variables across executions within the same context.
<TypeScriptExample>
const ctx = await sandbox.createCodeContext({ language: 'javascript' });
// Execution 1: Fetch data with top-level await
await sandbox.runCode(
const response = await fetch('https://api.example.com/data'); const data = await response.json();, { context: ctx });
// Execution 2: Use the data from previous execution
const result = await sandbox.runCode('console.log(data)', { context: ctx });
console.log(result.logs.stdout); // Data persists across executions
</TypeScriptExample>
Variables declared with `const`, `let`, or `var` persist across executions, enabling multi-step workflows:
<TypeScriptExample>
const ctx = await sandbox.createCodeContext({ language: 'javascript' });
await sandbox.runCode('const x = 10', { context: ctx });
await sandbox.runCode('let y = 20', { context: ctx });
const result = await sandbox.runCode('x + y', { context: ctx });
console.log(result.results[0].text); // "30"
</TypeScriptExample>
### `listCodeContexts()`
List all active code execution contexts.
```ts
const contexts = await sandbox.listCodeContexts(): Promise<CodeContext[]>
```
const contexts = await sandbox.listCodeContexts();
console.log(`Found ${contexts.length} contexts`);
```
deleteCodeContext()
Delete a code execution context and free its resources.
await sandbox.deleteCodeContext(contextId: string): Promise<void>
```
const ctx = await sandbox.createCodeContext({ language: 'python' });
await sandbox.runCode('print("Hello")', { context: ctx });
await sandbox.deleteCodeContext(ctx.id);
```
Rich Output Formats
Results include: 
text, 
html, 
png, 
jpeg, 
svg, 
latex, 
markdown, 
json, 
chart, 
data
Charts (matplotlib):
```
const result = await sandbox.runCode(`
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 10, 100)
plt.plot(x, np.sin(x))
plt.show()
`, { language: 'python' });
if (result.results[0]?.png) {
const imageBuffer = Buffer.from(result.results[0].png, 'base64');
return new Response(imageBuffer, {
headers: { 'Content-Type': 'image/png' }
});
}
</TypeScriptExample>
**Tables (pandas)**:
<TypeScriptExample>
const result = await sandbox.runCode(
import pandas as pd df = pd.DataFrame({'Name': ['Alice', 'Bob'], 'Age': [25, 30]}) df, { language: 'python' });
if (result.results[0]?.html) {
return new Response(result.results[0].html, {
headers: { 'Content-Type': 'text/html' }
});
}
</TypeScriptExample>
## Related resources
- [Build an AI Code Executor](/sandbox/sdk/tutorials/ai-code-executor/) - Complete tutorial
- [Commands API](/sandbox/sdk/api/commands/) - Lower-level command execution
- [Files API](/sandbox/sdk/api/files/) - File operations

Lifecycle
import { TypeScriptExample, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
Create and manage sandbox containers. Get sandbox instances, configure options, and clean up resources.
Methods
getSandbox()
Get or create a sandbox instance by ID.
const sandbox = getSandbox(
  binding: DurableObjectNamespace<Sandbox>,
  sandboxId: string,
  options?: SandboxOptions
): Sandbox
Parameters:
binding - The Durable Object namespace binding from your Worker environment
sandboxId - Unique identifier for this sandbox. The same ID always returns the same sandbox instance. In user-facing apps, scope IDs to a single user.
options (optional) - See SandboxOptions for all available options:
enableDefaultSession - Use the default session for operations without an explicit 
sessionId. Set to 
false to evaluate each call in isolation (default: 
true)
sleepAfter - Duration of inactivity before automatic sleep (default: 
"10m")
keepAlive - Prevent automatic sleep entirely. Persists across hibernation (default: 
false)
containerTimeouts - Configure container startup timeouts
normalizeId - Lowercase sandbox IDs for preview URL compatibility (default: 
false)
Returns: 
Sandbox instance
:::note
The container starts lazily on first operation. Calling 
getSandbox() returns immediately—the container only spins up when you execute a command, write a file, or perform other operations. See Sandbox lifecycle for details.
:::
:::note[Implicit execution mode]
By default, sandbox methods that do not specify a 
sessionId run in the sandbox's default session and preserve shell state between calls. It is recommended to set 
enableDefaultSession to 
false to ensure operations run in isolation. The 
createSession() API exists when sessions are required. Default sessions will be removed in a future version of the Sandbox SDK.
:::
```
import { getSandbox } from '@cloudflare/sandbox';
export default {
async fetch(request: Request, env: Env): Promise {
const sandbox = getSandbox(env.Sandbox, 'user-123');
const result = await sandbox.exec('python script.py');
return Response.json(result);
}
};
</TypeScriptExample>
:::caution
When using `keepAlive: true`, you **must** call `destroy()` when finished to prevent containers running indefinitely.
:::
---
### `setKeepAlive()`
Enable or disable keepAlive mode dynamically after sandbox creation.
```ts
await sandbox.setKeepAlive(keepAlive: boolean): Promise<void>
Parameters:
keepAlive - 
true to prevent automatic sleep, 
false to allow normal sleep behavior
When enabled, the sandbox automatically sends heartbeat pings every 30 seconds to prevent container eviction. When disabled, the sandbox returns to normal sleep behavior based on the 
sleepAfter configuration.
```
const sandbox = getSandbox(env.Sandbox, 'user-123');
// Enable keepAlive for a long-running process
await sandbox.setKeepAlive(true);
await sandbox.startProcess('python long_running_analysis.py');
// Later, disable keepAlive when done
await sandbox.setKeepAlive(false);
</TypeScriptExample>
:::note[Heartbeat mechanism]
When keepAlive is enabled, the sandbox automatically sends lightweight ping requests to the container every 30 seconds to prevent eviction. This happens transparently without affecting your application code.
:::
:::caution[Resource management]
Containers with `keepAlive: true` will not automatically timeout. Always disable keepAlive or call `destroy()` when done to prevent containers running indefinitely.
:::
---
### `destroy()`
Destroy the sandbox container and free up resources.
```ts
await sandbox.destroy(): Promise<void>
Immediately terminates the container and permanently deletes all state:
All files in 
/workspace, 
/tmp, and 
/home
All running processes
All sessions (including the default session)
Network connections and exposed ports
```
async function executeCode(code: string): Promise {
  const sandbox = getSandbox(env.Sandbox, `temp-${Date.now()}`);
try {
await sandbox.writeFile('/tmp/code.py', code);
const result = await sandbox.exec('python /tmp/code.py');
return result.stdout;
} finally {
await sandbox.destroy();
}
}
</TypeScriptExample>
:::note
Containers automatically sleep after 10 minutes of inactivity but still count toward account limits. Use `destroy()` to immediately free up resources.
:::
---
## Related resources
- [Sandbox lifecycle concept](/sandbox/sdk/concepts/sandboxes/) - Understanding container lifecycle and state
- [Sandbox options configuration](/sandbox/sdk/configuration/sandbox-options/) - Configure `keepAlive` and other options
- [Sessions API](/sandbox/sdk/api/sessions/) - Create execution contexts within a sandbox

Ports
import { TypeScriptExample, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/previews/", title: "Preview a web application" }} />
:::note[Production requires custom domain]
Preview URLs require a custom domain with wildcard DNS routing in production. See Configure preview URLs on a custom domain.
:::
:::note[Prefer 
sandbox.tunnels for public URLs]
For most public-URL use cases — development, 
.workers.dev deployments, and production traffic — 
sandbox.tunnels is the recommended option. Use named tunnels for stable hostnames on a zone you control, or quick tunnels for zero-config 
*.trycloudflare.com URLs. 
exposePort() is appropriate when you want the Worker itself to front the request (for example, to inject authentication, rewrite responses, or call sandbox-only RPC methods on the same hostname).
:::
Expose services running in your sandbox via public preview URLs. See Preview URLs concept for details.
Module functions
proxyToSandbox()
Route incoming HTTP and WebSocket requests to the correct sandbox container. Call this at the top of your Worker's 
fetch handler, before any application logic, so that it intercepts and forwards preview URL requests automatically.
proxyToSandbox(request: Request, env: Env): Promise<Response | null>
Parameters:
request - The incoming 
Request object from the 
fetch handler.
env - The 
Env object containing your Sandbox binding.
Returns: 
Promise<Response | null> — a 
Response if the request matched a preview URL and was routed to the sandbox, or 
null if the request did not match and should be handled by your application logic.
The function inspects the request hostname to determine whether it matches the subdomain pattern of an exposed port (for example, 
8080-sandbox-id-token.yourdomain.com). If it matches, 
proxyToSandbox() proxies the request to the correct Durable Object, and the sandbox service handles it. Both HTTP and WebSocket upgrade requests are supported.
```ts
import { proxyToSandbox, getSandbox } from "@cloudflare/sandbox";
export { Sandbox } from "@cloudflare/sandbox";
export default {
async fetch(request: Request, env: Env): Promise {
// Always call proxyToSandbox first to handle preview URL requests
const proxyResponse = await proxyToSandbox(request, env);
if (proxyResponse) return proxyResponse;
// Your application routes
const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
// ...
return new Response('Not found', { status: 404 });
}
};
</TypeScriptExample>
:::note
`proxyToSandbox` is a module-level function imported directly from `@cloudflare/sandbox` — it is not a method on a `Sandbox` instance. It requires the Sandbox Durable Object binding (`env.Sandbox`) to look up and route requests to the correct container.
:::
## Methods
### `exposePort()`
Expose a port and get a preview URL for accessing services running in the sandbox.
```ts
const response = await sandbox.exposePort(port: number, options: ExposePortOptions): Promise<ExposePortResponse>
Parameters:
port - Port number to expose (1024-65535)
options:
hostname - Your Worker's domain name (e.g., 
'example.com'). Required to construct preview URLs with wildcard subdomains like 
https://8080-sandbox-abc123token.example.com. Cannot be a 
.workers.dev domain as it doesn't support wildcard DNS patterns.
name - Friendly name for the port (optional)
token - Custom token for the preview URL (optional). Must be 1-16 characters containing only lowercase letters (a-z), numbers (0-9), hyphens (-), and underscores (_). If not provided, a random 16-character token is generated automatically.
Returns: 
Promise<ExposePortResponse> with 
port, 
url (preview URL), 
name
```ts
// Extract hostname from request
const { hostname } = new URL(request.url);
// Basic usage with auto-generated token
await sandbox.startProcess('python -m http.server 8000');
const exposed = await sandbox.exposePort(8000, { hostname });
console.log('Available at:', exposed.url);
// https://8000-sandbox-id-abc123random.yourdomain.com
// With custom token for stable URLs across restarts
const stable = await sandbox.exposePort(8080, {
hostname,
token: 'my_service_v1' // 1-16 chars: a-z, 0-9, _
});
console.log('Stable URL:', stable.url);
// https://8080-sandbox-id-my_service_v1.yourdomain.com
// With custom token for stable URLs across deployments
await sandbox.startProcess('node api.js');
const api = await sandbox.exposePort(3000, {
hostname,
name: 'api',
token: 'prod-api-v1'  // URL stays same across restarts
});
console.log('Stable API URL:', api.url);
// https://3000-sandbox-id-prod-api-v1.yourdomain.com
// Multiple services with custom tokens
await sandbox.startProcess('npm run dev');
const frontend = await sandbox.exposePort(5173, {
hostname,
name: 'frontend',
token: 'dev-ui'
});
</TypeScriptExample>
:::note[Local development]
When using `wrangler dev`, you must add `EXPOSE` directives to your Dockerfile for each port. See [Expose Services guide](/sandbox/sdk/guides/expose-services/#local-development) for details.
:::
## Custom Tokens for Stable URLs
Custom tokens enable consistent preview URLs across container restarts and deployments. This is useful for:
- **Production environments** - Share stable URLs with users or teams
- **Development workflows** - Maintain bookmarks and integrations
- **CI/CD pipelines** - Reference consistent URLs in tests or deployment scripts
**Token Requirements:**
- 1-16 characters in length
- Only lowercase letters (a-z), numbers (0-9), hyphens (-), and underscores (_)
- Must be unique per sandbox (cannot reuse tokens across different ports)
<TypeScriptExample>
```ts
// Production API with stable URL
const { url } = await sandbox.exposePort(8080, {
  hostname: 'api.example.com',
  token: 'v1-stable'  // Always the same URL
});
// Error: Token collision prevention
await sandbox.exposePort(8081, { hostname, token: 'v1-stable' });
// Throws: Token 'v1-stable' is already in use by port 8080
// Success: Re-exposing same port with same token (idempotent)
await sandbox.exposePort(8080, { hostname, token: 'v1-stable' });
// Works - same port, same token
validatePortToken()
Validate if a token is authorized to access a specific exposed port. Useful for custom authentication or routing logic.
const isValid = await sandbox.validatePortToken(port: number, token: string): Promise<boolean>
Parameters:
port - Port number to check
token - Token to validate
Returns: 
Promise<boolean> - 
true if token is valid for the port, 
false otherwise
```ts
// Custom validation in your Worker
export default {
  async fetch(request: Request, env: Env): Promise {
    const url = new URL(request.url);
// Extract token from custom header or query param
const customToken = request.headers.get('x-access-token');
if (customToken) {
  const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
  const isValid = await sandbox.validatePortToken(8080, customToken);
  
  if (!isValid) {
    return new Response('Invalid token', { status: 403 });
  }
}
// Handle preview URL routing
const proxyResponse = await proxyToSandbox(request, env);
if (proxyResponse) return proxyResponse;
// Your application routes
return new Response('Not found', { status: 404 });
}
};
</TypeScriptExample>
### `unexposePort()`
Remove an exposed port and close its preview URL.
```ts
await sandbox.unexposePort(port: number): Promise<void>
Parameters:
port - Port number to unexpose
```ts
await sandbox.unexposePort(8000);
```
getExposedPorts()
Get information about all currently exposed ports.
const response = await sandbox.getExposedPorts(): Promise<GetExposedPortsResponse>
Returns: 
Promise<GetExposedPortsResponse> with 
ports array (containing 
port, 
url, 
name)
```
const { ports } = await sandbox.getExposedPorts();
for (const port of ports) {
console.log(
${port.name || port.port}: ${port.url});
}
</TypeScriptExample>
### `wsConnect()`
Connect to WebSocket servers running in the sandbox. Use this when your Worker needs to establish WebSocket connections with services in the sandbox.
**Common use cases:**
- Route incoming WebSocket upgrade requests with custom authentication or authorization
- Connect from your Worker to get real-time data from sandbox services
For exposing WebSocket services via public preview URLs, use `exposePort()` with `proxyToSandbox()` instead. See [WebSocket Connections guide](/sandbox/sdk/guides/websocket-connections/) for examples.
```ts
const response = await sandbox.wsConnect(request: Request, port: number): Promise<Response>
Parameters:
request - Incoming WebSocket upgrade request
port - Port number (1024-65535, excluding 3000)
Returns: 
Promise<Response> - WebSocket response establishing the connection
```ts
import { getSandbox } from "@cloudflare/sandbox";
export { Sandbox } from "@cloudflare/sandbox";
export default {
async fetch(request: Request, env: Env): Promise {
if (request.headers.get('Upgrade')?.toLowerCase() === 'websocket') {
const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
return await sandbox.wsConnect(request, 8080);
}
return new Response('WebSocket endpoint', { status: 200 });
}
};
</TypeScriptExample>
## Related resources
- [Preview URLs concept](/sandbox/sdk/concepts/preview-urls/) - How preview URLs work
- [Expose Services guide](/sandbox/sdk/guides/expose-services/) - Full workflow for starting services, exposing ports, and routing requests
- [WebSocket Connections guide](/sandbox/sdk/guides/websocket-connections/) - WebSocket routing via preview URLs
- [Commands API](/sandbox/sdk/api/commands/) - Start background processes
- [Tunnels API](/sandbox/sdk/api/tunnels/) - Zero-config `*.trycloudflare.com` URLs for quick development

Sessions
import { TypeScriptExample, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
Create shell sessions within a sandbox. Each session maintains its own shell state, environment variables, and working directory, while sharing the sandbox filesystem and process space. For more information, refer to Session management.
:::note
By default, for backwards compatibility, every sandbox has a default session that maintains shell state. It is recommended to set 
enableDefaultSession to 
false on 
getSandbox() so operations without an explicit 
sessionId run in isolation. Create additional sessions for separate workflows inside the same user workspace, such as development and runtime processes using the 
createSession() method. Use separate sandboxes for separate users. For sandbox-level operations like creating containers or destroying the entire sandbox, refer to the Lifecycle API.
:::
Methods
createSession()
Create a new shell session.
const session = await sandbox.createSession(options?: SessionOptions): Promise<ExecutionSession>
Parameters:
options (optional):
id - Custom session ID (auto-generated if not provided)
env - Environment variables for this session: 
Record<string, string | undefined>
cwd - Working directory (default: 
"/workspace")
commandTimeoutMs - Maximum time in milliseconds that any command in this session can run before timing out. Individual commands can override this with the 
timeout option on 
exec().
Returns: 
Promise<ExecutionSession> with all sandbox methods bound to this session
```ts
// Separate workflow environments
const prodSession = await sandbox.createSession({
  id: 'prod',
  env: { NODE_ENV: 'production', API_URL: 'https://api.example.com' },
  cwd: '/workspace/prod'
});
const testSession = await sandbox.createSession({
id: 'test',
env: {
NODE_ENV: 'test',
API_URL: 'http://localhost:3000',
DEBUG_MODE: undefined // Skipped, not set in this session
},
cwd: '/workspace/test'
});
// Run in parallel
const [prodResult, testResult] = await Promise.all([
prodSession.exec('npm run build'),
testSession.exec('npm run build')
]);
// Session with a default command timeout
const session = await sandbox.createSession({
commandTimeoutMs: 5000 // 5s timeout for all commands
});
await session.exec('sleep 10'); // Times out after 5s
// Per-command timeout overrides session-level timeout
await session.exec('sleep 10', { timeout: 3000 }); // Times out after 3s
</TypeScriptExample>
### `getSession()`
Retrieve an existing session by ID.
```ts
const session = await sandbox.getSession(sessionId: string): Promise<ExecutionSession>
Parameters:
sessionId - ID of an existing session
Returns: 
Promise<ExecutionSession> bound to the specified session
```ts
// First request - create a task-specific session
const session = await sandbox.createSession({ id: 'build' });
await session.exec('git clone https://github.com/user/repo.git');
await session.exec('cd repo && npm install');
// Second request - resume session (environment and cwd preserved)
const session = await sandbox.getSession('build');
const result = await session.exec('cd repo && npm run build');
</TypeScriptExample>
---
### `deleteSession()`
Delete a session and clean up its resources.
```ts
const result = await sandbox.deleteSession(sessionId: string): Promise<SessionDeleteResult>
Parameters:
sessionId - ID of the session to delete (cannot be 
"default")
Returns: 
Promise<SessionDeleteResult> containing:
success - Whether deletion succeeded
sessionId - ID of the deleted session
timestamp - Deletion timestamp
```ts
// Create a temporary session for a specific task
const tempSession = await sandbox.createSession({ id: 'temp-task' });
try {
await tempSession.exec('npm run heavy-task');
} finally {
// Clean up the session when done
await sandbox.deleteSession('temp-task');
}
</TypeScriptExample>
:::caution
Deleting a session immediately terminates all running commands. The default session cannot be deleted.
:::
---
### `setEnvVars()`
Set environment variables in the sandbox.
```ts
await sandbox.setEnvVars(envVars: Record<string, string | undefined>): Promise<void>
Parameters:
envVars - Key-value pairs of environment variables to set or unset
string values: Set the environment variable
undefined or 
null values: Unset the environment variable
:::caution
Call 
setEnvVars() before any other sandbox operations to ensure environment variables are available from the start.
:::
```ts
const sandbox = getSandbox(env.Sandbox, 'user-123');
// Set environment variables first
await sandbox.setEnvVars({
API_KEY: env.OPENAI_API_KEY,
DATABASE_URL: env.DATABASE_URL,
NODE_ENV: 'production',
OLD_TOKEN: undefined // Unsets OLD_TOKEN if previously set
});
// Now commands can access these variables
await sandbox.exec('python script.py');
</TypeScriptExample>
---
## ExecutionSession methods
The `ExecutionSession` object has all sandbox methods bound to the specific session:
| Category | Methods |
| -------- | ------- |
| **Commands** | [`exec()`](/sandbox/sdk/api/commands/#exec), [`execStream()`](/sandbox/sdk/api/commands/#execstream) |
| **Processes** | [`startProcess()`](/sandbox/sdk/api/commands/#startprocess), [`listProcesses()`](/sandbox/sdk/api/commands/#listprocesses), [`killProcess()`](/sandbox/sdk/api/commands/#killprocess), [`killAllProcesses()`](/sandbox/sdk/api/commands/#killallprocesses), [`getProcessLogs()`](/sandbox/sdk/api/commands/#getprocesslogs), [`streamProcessLogs()`](/sandbox/sdk/api/commands/#streamprocesslogs) |
| **Files** | [`writeFile()`](/sandbox/sdk/api/files/#writefile), [`readFile()`](/sandbox/sdk/api/files/#readfile), [`mkdir()`](/sandbox/sdk/api/files/#mkdir), [`deleteFile()`](/sandbox/sdk/api/files/#deletefile), [`renameFile()`](/sandbox/sdk/api/files/#renamefile), [`moveFile()`](/sandbox/sdk/api/files/#movefile), [`gitCheckout()`](/sandbox/sdk/api/files/#gitcheckout) |
| **Environment** | [`setEnvVars()`](/sandbox/sdk/api/sessions/#setenvvars) |
| **Terminal** | [`terminal()`](/sandbox/sdk/api/terminal/#terminal) |
| **Code Interpreter** | [`createCodeContext()`](/sandbox/sdk/api/interpreter/#createcodecontext), [`runCode()`](/sandbox/sdk/api/interpreter/#runcode), [`listCodeContexts()`](/sandbox/sdk/api/interpreter/#listcodecontexts), [`deleteCodeContext()`](/sandbox/sdk/api/interpreter/#deletecodecontext) |
## Related resources
- [Session management concept](/sandbox/sdk/concepts/sessions/) - How sessions work
- [Commands API](/sandbox/sdk/api/commands/) - Execute commands

Storage
import { TypeScriptExample, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/files/mount-an-r2-bucket/", title: "Mount an R2 bucket" }} />
Mount S3-compatible storage buckets (R2, S3, GCS) into the sandbox filesystem for persistent data access. 
mountBucket() supports R2 binding mounts, local R2 binding sync during development, and remote S3-compatible endpoint mounts.
Methods
mountBucket()
Mount an S3-compatible bucket to a local path in the sandbox.
await sandbox.mountBucket(
  bucket: string,
  mountPath: string,
  options?: MountBucketOptions
): Promise<void>
Parameters:
bucket - Bucket identifier
When 
options.endpoint is omitted, pass the Worker R2 binding name (for example, 
"MY_BUCKET")
When 
options.endpoint is provided, pass the remote bucket name (for example, 
"my-r2-bucket")
mountPath - Local filesystem path to mount at (e.g., 
"/data")
options (optional) - Mount configuration (see 
MountBucketOptions)
```
// Mount an R2 bucket by Worker binding name
await sandbox.mountBucket('MY_BUCKET', '/data');
// Read/write files directly
const data = await sandbox.readFile('/data/config.json');
await sandbox.writeFile('/data/results.json', JSON.stringify(data));
// Mount a remote S3-compatible bucket, including explicit R2 endpoints
await sandbox.mountBucket('my-bucket', '/storage', {
endpoint: 'https://s3.amazonaws.com',
credentials: {
accessKeyId: env.AWS_ACCESS_KEY_ID,
secretAccessKey: env.AWS_SECRET_ACCESS_KEY
}
});
// Mount an R2 bucket during local development with wrangler dev
await sandbox.mountBucket('MY_BUCKET', '/local-data', {
localBucket: true
});
// Mount a prefix from an R2 binding
await sandbox.mountBucket('MY_BUCKET', '/user-data', {
prefix: '/users/user-123',
readOnly: true
});
</TypeScriptExample>
**Throws**:
- `InvalidMountPointError` - Invalid mount path or conflicts with existing mounts
- `BucketAccessError` - Bucket does not exist or insufficient permissions
:::note[Authentication]
Authentication depends on the mount mode:
1. Omit `endpoint` to mount an R2 bucket by Worker binding name in production
2. Set `localBucket: true` to use the same R2 binding during local development
3. Set `endpoint` to mount a remote S3-compatible bucket, then provide explicit `credentials` or rely on environment variables (`R2_ACCESS_KEY_ID` / `R2_SECRET_ACCESS_KEY` or `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`)
Endpoint-based mounts remain supported for explicit R2 endpoint configuration and for other S3-compatible providers.
See the [Mount Buckets guide](/sandbox/sdk/guides/mount-buckets/) for detailed authentication options.
:::
### `unmountBucket()`
Unmount a previously mounted bucket.
```ts
await sandbox.unmountBucket(mountPath: string): Promise<void>
Parameters:
mountPath - Path where the bucket is mounted (e.g., 
"/data")
```
// Mount, process, unmount
await sandbox.mountBucket('MY_BUCKET', '/data');
await sandbox.exec('python process.py');
// Unmount
await sandbox.unmountBucket('/data');
</TypeScriptExample>
:::note[Automatic cleanup]
Mounted buckets are automatically unmounted when the container is destroyed.
:::
## Types
### `MountBucketOptions`
```ts
interface RemoteMountBucketOptions {
  endpoint: string;
  provider?: BucketProvider;
  credentials?: BucketCredentials;
  credentialProxy?: boolean;
  readOnly?: boolean;
  s3fsOptions?: string[];
  prefix?: string;
}
interface LocalMountBucketOptions {
  localBucket: true;
  prefix?: string;
  readOnly?: boolean;
}
interface R2BindingMountBucketOptions {
  endpoint?: never;
  prefix?: string;
  readOnly?: boolean;
  s3fsOptions?: string[];
}
type MountBucketOptions =
  | RemoteMountBucketOptions
  | LocalMountBucketOptions
  | R2BindingMountBucketOptions;
mountBucket() supports these three modes:
R2 binding mount - Omit 
endpoint to mount by Worker binding name in production
Uses credential-less egress interception for R2
Supports 
prefix, 
readOnly, and 
s3fsOptions
Local R2 binding mount - Set 
localBucket: true during 
wrangler dev
Uses the Worker R2 binding directly through local synchronization
Supports 
prefix and 
readOnly
Remote endpoint mount - Set 
endpoint to mount any S3-compatible provider
Supports explicit 
credentials or environment variable auto-detection
Set 
credentialProxy: true to keep credentials out of the container (egress interception)
Supports 
provider, 
prefix, 
readOnly, and 
s3fsOptions
Field details:
endpoint (remote endpoint mode only) - S3-compatible endpoint URL
R2: 
'https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com'
S3: 
'https://s3.amazonaws.com'
GCS: 
'https://storage.googleapis.com'
localBucket (local development mode only) - Mount an R2 bucket using the Worker's R2 binding during local development with 
wrangler dev
When 
true, the SDK syncs the R2 binding directly instead of using an S3 endpoint
provider (remote endpoint mode only) - Storage provider hint
Enables provider-specific optimizations
Values: 
'r2', 
's3', 
'gcs'
credentials (remote endpoint mode only) - API credentials
Contains 
accessKeyId and 
secretAccessKey
If not provided, uses environment variables
credentialProxy (remote endpoint mode only) - Route S3 requests through the Durable Object for signing
When 
true, credentials are never written to the container's disk. The Durable Object intercepts and re-signs all outbound S3 requests at the network layer before forwarding them upstream.
Supports AWS SigV4 signing for S3-compatible endpoints (including R2) and HMAC signing for Google Cloud Storage
Requires 
ContainerProxy to be exported from your Worker entrypoint
Default: 
false (backwards compatibility — recommended to set to 
true; will become the default in a future version)
readOnly (optional) - Mount in read-only mode
Default: 
false
prefix (optional) - Subdirectory within the bucket to mount
When specified, only contents under this prefix are visible at the mount point
Must start with 
/ (for example, 
/data/uploads or 
/data/uploads/)
Default: Mount entire bucket
s3fsOptions (R2 binding and remote endpoint modes only) - Advanced s3fs mount flags
Type: 
string[]
Example: 
['use_cache=/tmp/cache', 'stat_cache_expire=1']
BucketProvider
Storage provider hint for automatic s3fs flag optimization.
type BucketProvider = "r2" | "s3" | "gcs";
'r2' - Cloudflare R2 (recommended, applies 
nomixupload flag)
's3' - Amazon S3
'gcs' - Google Cloud Storage
Related resources
Mount Buckets guide - Complete bucket mounting walkthrough
Files API - Read and write files

Terminal
import { TypeScriptExample, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/commands/open-a-terminal-in-the-browser/", title: "Open a terminal in the browser" }} />
Connect browser-based terminal UIs to sandbox shells via WebSocket. The server-side 
terminal() method proxies WebSocket connections to the container, and the client-side 
SandboxAddon integrates with xterm.js for terminal rendering.
Server-side methods
terminal()
Proxy a WebSocket upgrade request to create a terminal connection.
const response = await sandbox.terminal(request: Request, options?: PtyOptions): Promise<Response>
Parameters:
request - WebSocket upgrade request from the browser (must include 
Upgrade: websocket header)
options (optional):
cols - Terminal width in columns (default: 
80)
rows - Terminal height in rows (default: 
24)
Returns: 
Promise<Response> — WebSocket upgrade response
```ts
// In your Worker's fetch handler
return await sandbox.terminal(request, { cols: 120, rows: 30 });
```
Works with both default and explicitly created sessions:
```ts
// Default session
return await sandbox.terminal(request);
// Specific session
const session = await sandbox.getSession('dev');
return await session.terminal(request);
</TypeScriptExample>
## Client-side addon
The `@cloudflare/sandbox/xterm` module provides `SandboxAddon` for xterm.js, which handles the WebSocket connection, reconnection, and terminal resize forwarding.
### `SandboxAddon`
```ts
import { SandboxAddon } from '@cloudflare/sandbox/xterm';
const addon = new SandboxAddon(options: SandboxAddonOptions);
Options:
getWebSocketUrl(params) - Build the WebSocket URL for each connection attempt. Receives:
sandboxId - Target sandbox ID
sessionId (optional) - Target session ID
origin - WebSocket origin derived from 
window.location (for example, 
wss://example.com)
reconnect - Enable automatic reconnection with exponential backoff (default: 
true)
onStateChange(state, error?) - Callback for connection state changes
```ts
import { Terminal } from '@xterm/xterm';
import { SandboxAddon } from '@cloudflare/sandbox/xterm';
const terminal = new Terminal({ cursorBlink: true });
terminal.open(document.getElementById('terminal'));
const addon = new SandboxAddon({
getWebSocketUrl: ({ sandboxId, sessionId, origin }) => {
const params = new URLSearchParams({ id: sandboxId });
if (sessionId) params.set('session', sessionId);
return 
${origin}/ws/terminal?${params};
},
onStateChange: (state, error) => {
console.log(
Terminal ${state}, error);
}
});
terminal.loadAddon(addon);
addon.connect({ sandboxId: 'my-sandbox' });
</TypeScriptExample>
### `connect()`
Establish a connection to a sandbox terminal.
```ts
addon.connect(target: ConnectionTarget): void
Parameters:
target:
sandboxId - Sandbox to connect to
sessionId (optional) - Session within the sandbox
Calling 
connect() with a new target disconnects from the current target and connects to the new one. Calling it with the same target while already connected is a no-op.
disconnect()
Close the connection and stop any reconnection attempts.
addon.disconnect(): void
Properties
Property
Type
Description
state
'disconnected' | 'connecting' | 'connected'
Current connection state
sandboxId
string | undefined
Current sandbox ID
sessionId
string | undefined
Current session ID
WebSocket protocol
The 
SandboxAddon handles the WebSocket protocol automatically. These details are for building custom terminal clients without the addon. For a complete example, refer to Connect without xterm.js.
Connection lifecycle
Client opens a WebSocket to your Worker endpoint. Set 
binaryType to 
arraybuffer.
The server replays any buffered output from a previous connection as binary frames. This may arrive before the 
ready message.
The server sends a 
ready status message — the terminal is now accepting input.
Binary frames flow in both directions: UTF-8 encoded keystrokes from the client, terminal output (including ANSI escape sequences) from the server.
If the client disconnects, the PTY stays alive. Reconnecting to the same session replays buffered output so the terminal appears unchanged.
Control messages (client to server)
Send JSON text frames to control the terminal.
Resize — update terminal dimensions (both 
cols and 
rows must be positive):
{ "type": "resize", "cols": 120, "rows": 30 }
Status messages (server to client)
The server sends JSON text frames for lifecycle events.
Ready — the PTY is initialized. Buffered output (if any) has already been sent:
{ "type": "ready" }
Exit — the shell process has terminated:
{ "type": "exit", "code": 0, "signal": "SIGTERM" }
Error — an error occurred (for example, invalid control message or session not found):
{ "type": "error", "message": "Session not found" }
Types
interface PtyOptions {
	cols?: number;
	rows?: number;
}
type ConnectionState = "disconnected" | "connecting" | "connected";
interface ConnectionTarget {
	sandboxId: string;
	sessionId?: string;
}
interface SandboxAddonOptions {
	getWebSocketUrl: (params: {
		sandboxId: string;
		sessionId?: string;
		origin: string;
	}) => string;
	reconnect?: boolean;
	onStateChange?: (state: ConnectionState, error?: Error) => void;
}
Related resources
Terminal connections — How terminal connections work
Browser terminals — Step-by-step setup guide
Sessions API — Session management
Commands API — Non-interactive command execution

Tunnels
import { TypeScriptExample, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
The 
sandbox.tunnels namespace exposes a service running inside a sandbox on the public internet through a Cloudflare Tunnel. The SDK runs 
cloudflared inside the container and opens a persistent QUIC connection to Cloudflare's edge.
Two flavors are available:
Quick tunnels (
sandbox.tunnels.get(port)) — zero-config. Cloudflare assigns a random 
*.trycloudflare.com hostname for each new 
cloudflared process. No Cloudflare account, API token, DNS record, or custom domain required. URLs change on every container restart.
Named tunnels (
sandbox.tunnels.get(port, { name })) — bind a stable hostname 
<name>.<your-zone> on a zone you control. The hostname survives container restarts and is shared across sandboxes that request the same 
name. Requires a Cloudflare API token, an account, and a zone.
:::note[When to use quick vs. named tunnels]
Use quick tunnels for local development, demos, and short-lived 
.workers.dev deployments where you do not need a stable URL. Use named tunnels for everything else — they are the recommended option for production traffic, webhook receivers, OAuth callbacks, and any URL that needs to be bookmarked. 
exposePort() remains an alternative when you want the Worker itself (rather than Cloudflare's edge) to front the request.
:::
Requirements
Both tunnel flavors require:
RPC transport. Calling 
sandbox.tunnels on HTTP/Websocket transports throws 
"RPC transport required". See Transport configuration.
Named tunnels additionally require a Cloudflare API token, account, and zone — refer to Named tunnels: prerequisites.
Methods
tunnels.get()
Return a tunnel record for 
port. The SDK spawns a fresh 
cloudflared process inside the container if not already running. The method is idempotent: repeated calls with the same 
(port, options) return the same record.
const tunnel = await sandbox.tunnels.get(
  port: number,
  options?: { name?: string }
): Promise<TunnelInfo>
Parameters:
port — Port number inside the sandbox to expose (1024-65535, excluding reserved ports). The service to tunnel to must already be listening on 
0.0.0.0:<port> inside the container.
options.name (optional) — Single DNS label (lowercase letters, digits, internal hyphens; 1–63 chars; no dots). When set, provisions a named tunnel bound to 
<name>.<your-zone>. When omitted, provisions a quick tunnel.
Returns: 
Promise<TunnelInfo> — the tunnel record. See 
TunnelInfo.
Calling 
get(port) with different 
options on a port that already has a tunnel throws. Call 
destroy(port) first.
```ts
import { getSandbox } from "@cloudflare/sandbox";
export { Sandbox } from "@cloudflare/sandbox";
export default {
async fetch(request: Request, env: Env): Promise {
const sandbox = getSandbox(env.Sandbox, "my-sandbox");
await sandbox.startProcess("python -m http.server 8080");
const tunnel = await sandbox.tunnels.get(8080);
console.log(tunnel.url);
// → https://random-words-here.trycloudflare.com
// Repeated calls for the same port return the same record.
const same = await sandbox.tunnels.get(8080);
console.log(same.url === tunnel.url); // true
return Response.json({ url: tunnel.url });
},
};
</TypeScriptExample>
### `tunnels.list()`
Return every tunnel currently tracked for this sandbox.
```ts
const tunnels = await sandbox.tunnels.list(): Promise<TunnelInfo[]>
Returns: 
Promise<TunnelInfo[]> — an array of 
TunnelInfo records. Empty when no tunnels are active.
```ts
const tunnels = await sandbox.tunnels.list();
for (const tunnel of tunnels) {
console.log(
port ${tunnel.port} → ${tunnel.url});
}
</TypeScriptExample>
### `tunnels.destroy()`
Tear down a tunnel. Accepts either the port number or the `TunnelInfo` record returned by `get()`. Idempotent — destroying an unknown port resolves successfully.
```ts
await sandbox.tunnels.destroy(portOrInfo: number | TunnelInfo): Promise<void>
Parameters:
portOrInfo — Either the port number or the 
TunnelInfo record returned by 
get().
```ts
const tunnel = await sandbox.tunnels.get(8080);
// Tear down by port number...
await sandbox.tunnels.destroy(8080);
// ...or by the record.
await sandbox.tunnels.destroy(tunnel);
</TypeScriptExample>
## Types
### `TunnelInfo`
Quick tunnels omit `name`; named tunnels carry the label passed via `options.name`.
| Field       | Type     | Description                                                                                                                       |
| ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `id`        | `string` | Tunnel identifier. `quick-<random>` for quick tunnels, the Cloudflare Tunnel UUID for named tunnels.                              |
| `port`      | `number` | Port number inside the sandbox that the tunnel proxies to.                                                                        |
| `url`       | `string` | Public URL — `https://<random>.trycloudflare.com` (quick) or `https://<name>.<your-zone>` (named).                                |
| `hostname`  | `string` | Hostname component of `url`.                                                                                                       |
| `createdAt` | `string` | ISO-8601 timestamp of when the tunnel was created.                                                                                |
| `name`      | `string` | **Named tunnels only.** The label passed via `options.name`. Absent on quick tunnels.                                              |
```ts
type TunnelInfo = QuickTunnelInfo | NamedTunnelInfo;
interface QuickTunnelInfo {
  id: string;
  port: number;
  url: string;
  hostname: string;
  createdAt: string;
  name?: never;
}
interface NamedTunnelInfo {
  id: string;
  port: number;
  url: string;
  hostname: string;
  createdAt: string;
  name: string;
}
```
## Named tunnels
Named tunnels bind a user-controlled hostname — `<name>.<your-zone>` — backed by a managed [Cloudflare Tunnel](/cloudflare-one/networks/connectors/cloudflare-tunnel/) and a proxied `CNAME` record on your zone. Unlike quick tunnels, the URL is **stable across container restarts** and **shared across sandboxes** that call `get(port, { name })` with the same `name`.
### How they differ from quick tunnels
| Aspect                  | Quick tunnel                                  | Named tunnel                                                          |
| ----------------------- | --------------------------------------------- | --------------------------------------------------------------------- |
| Hostname                | Random `*.trycloudflare.com`, assigned by Cloudflare | `<name>.<your-zone>`, chosen by you                            |
| Stability               | Changes on every container restart            | Stable; persists across restarts and sandbox lifecycles               |
| Cloudflare account      | Not required                                  | Required (API token + zone)                                           |
| Cloudflare-side resources | None                                        | Managed [Cloudflare Tunnel](/cloudflare-one/networks/connectors/cloudflare-tunnel/) + proxied DNS `CNAME` |
| Uptime guarantee        | None (debug aid)                              | Backed by your zone's standard Cloudflare SLA                         |
| TLS certificate         | Cloudflare-owned wildcard                     | Universal SSL on `<name>.<your-zone>` (single DNS label only)         |
| Server-Sent Events      | Not supported (edge buffers `text/event-stream`) | Supported                                                          |
### Prerequisites
To provision a named tunnel, you need:
1. A **Cloudflare account** with a **zone** (a domain you control on Cloudflare DNS).
2. A **Cloudflare API token** with the correct scopes.
3. The **account ID** and **zone ID** — the SDK can infer both from the token when the token is scoped to exactly one of each.
#### Create the API token
Create a token from **My Profile** > **API Tokens** > **Create Token** > **Custom token** with the following permissions:
| Scope                                                | Used for                                                                                          |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| **Account** · **Cloudflare Tunnel** · **Edit**       | Create, look up, and delete tunnels.                                                              |
| **Zone** · **DNS** · **Edit**                        | Upsert and delete the proxied `CNAME` for `<name>.<your-zone>`.                                   |
| **Zone** · **Zone** · **Read**                       | Look up the zone's name to derive `<name>.<your-zone>`.                                           |
| **Account** · **Account Settings** · **Read** *(optional)* | Lets the SDK infer the account ID from the token when not set explicitly.                 |
Under **Account Resources**, scope the token to the account that will own the tunnel. Under **Zone Resources**, scope it to the specific zone you want to bind to.
Both [User API Tokens](/fundamentals/api/get-started/create-token/) and [Account API Tokens](/fundamentals/api/get-started/account-owned-tokens/) (secret prefixed `cfat_`) are supported — the SDK detects the token kind and uses the appropriate introspection endpoint.
#### Create the token with the REST API
You can create the token without using the dashboard. The permission group IDs are stable; the snippet below uses placeholders — fetch the current IDs from [`GET /user/tokens/permission_groups`](/api/operations/permission-groups-list-permission-groups/).
```bash
curl -X POST "https://api.cloudflare.com/client/v4/user/tokens" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sandbox-named-tunnels",
    "policies": [
      {
        "effect": "allow",
        "resources": { "com.cloudflare.api.account.<ACCOUNT_ID>": "*" },
        "permission_groups": [{ "id": "<TUNNEL_EDIT_GROUP_ID>" }]
      },
      {
        "effect": "allow",
        "resources": { "com.cloudflare.api.account.zone.<ZONE_ID>": "*" },
        "permission_groups": [
          { "id": "<DNS_EDIT_GROUP_ID>" },
          { "id": "<ZONE_READ_GROUP_ID>" }
        ]
      }
    ]
  }'
```
#### Bind the token and IDs to the Worker
The SDK reads `CLOUDFLARE_API_TOKEN` from the Worker environment and attempts to derive the account ID and zone ID from the token automatically. If the token is associated with multiple accounts or zones the SDK cannot pick one unambiguously, and you must set `CLOUDFLARE_ACCOUNT_ID` and/or `CLOUDFLARE_ZONE_ID` explicitly.
| Variable                  | Required?                                | Notes                                                                            |
| ------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------- |
| `CLOUDFLARE_API_TOKEN`    | Yes                                      | Store as a secret with `wrangler secret put`.                                    |
| `CLOUDFLARE_ACCOUNT_ID`   | Only if the token sees multiple accounts | Inferred from the token otherwise.                                               |
| `CLOUDFLARE_ZONE_ID`      | Only if the token sees multiple zones    | Inferred from the token otherwise.                                               |
```bash
npx wrangler secret put CLOUDFLARE_API_TOKEN
```
For local development, place the variables in `.dev.vars` (gitignored). For production, set the non-secret IDs (when needed) under `vars` in your Wrangler config:
```jsonc
{
  "vars": {
    "CLOUDFLARE_ACCOUNT_ID": "<account-id>",
    "CLOUDFLARE_ZONE_ID": "<zone-id>"
  }
}
```
When inference fails, the SDK throws a clear error naming the variable to set.
### Example
<TypeScriptExample>
```ts
import { getSandbox } from "@cloudflare/sandbox";
export { Sandbox } from "@cloudflare/sandbox";
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const sandbox = getSandbox(env.Sandbox, "my-sandbox");
    // Reuse an existing app process across container restarts, or start it.
    let proc = await sandbox.getProcess('app');
    if (!proc) {
      try {
        proc = await sandbox.startProcess('python -m http.server 8080', { processId: 'app' });
      } catch (err) {
        if ((err as { code?: string })?.code !== 'PROCESS_ALREADY_EXISTS') throw err;
        proc = await sandbox.getProcess('app');
      }
    }
    // Provision (or reuse) https://app.example.com pointing at port 8080.
    const tunnel = await sandbox.tunnels.get(8080, { name: "app" });
    console.log(tunnel.url); // → https://app.example.com
    return Response.json({ url: tunnel.url });
  },
};
```
</TypeScriptExample>
:::caution[`name` must be a single DNS label]
`name` must match `^[a-z0-9]([a-z0-9-]*[a-z0-9])?$` and be 1–63 characters — no dots, no uppercase, no leading/trailing hyphens. This restriction exists because Cloudflare Universal SSL only issues certificates for `<label>.<zone>`. Multi-label hostnames need [Advanced Certificate Manager](/ssl/edge-certificates/advanced-certificate-manager/) or a delegated subdomain zone, which are out of scope for `sandbox.tunnels`.
:::
### Lifecycle
Named tunnels are designed to outlive the container that provisioned them:
1. **First call** to `sandbox.tunnels.get(port, { name })`:
   - Resolves `<name>.<your-zone>` from the configured zone ID.
   - Creates a [Cloudflare Tunnel](/cloudflare-one/networks/connectors/cloudflare-tunnel/) resource named `sandbox-<sandbox-id>-<name>` tagged with the sandbox ID.
   - Upserts a proxied `CNAME` from `<name>.<your-zone>` to `<tunnel-id>.cfargotunnel.com`.
   - Spawns `cloudflared` inside the container with the tunnel's token.
2. **Subsequent calls** with the same `(port, name)` return the cached record without contacting Cloudflare.
3. **Container restart** (Durable Object eviction, deploy, crash):
   - `cloudflared` dies with the container, but the Cloudflare Tunnel and DNS record are preserved.
   - On the next `get(port, { name })`, the SDK rediscovers the tagged tunnel via the Cloudflare API and respawns `cloudflared`. The hostname is unchanged.
4. **Explicit teardown** with `sandbox.tunnels.destroy(port)`:
   - Stops `cloudflared` inside the container.
   - Deletes the Cloudflare Tunnel resource.
   - Deletes the proxied `CNAME` record.
5. **Sandbox destroy** with `sandbox.destroy()` tears down every tunnel the sandbox provisioned, including the Cloudflare-side resources, before stopping the container.
If `destroy()` fails to reach the Cloudflare API (for example, the token was revoked between `get()` and `destroy()`), the SDK logs a warning naming the orphaned `tunnelId` and `dnsRecordId` so you can clean up manually from the dashboard.
### Cloudflare resources and tagging
Named tunnels create resources **on your Cloudflare account, outside the sandbox container**. They are not stored in Durable Object storage and do not count against sandbox quotas, but they do show up in the Cloudflare dashboard and consume your account's tunnel and DNS quotas.
For each `(sandbox, name)` pair, the SDK creates:
| Resource                | Name / location                                                | Identifier              |
| ----------------------- | -------------------------------------------------------------- | ----------------------- |
| Cloudflare Tunnel       | **Networking** > **Tunnels**                    | `sandbox-<sandbox-id>-<name>` |
| Proxied DNS record      | Your zone, **DNS** > **Records**                               | `CNAME <name>.<zone> → <tunnel-id>.cfargotunnel.com` |
Both resources are tagged so you can audit, query, and bulk-clean them from the dashboard or API:
- **Tunnel metadata**: `{ sandboxId, createdBy: 'sandbox-sdk', name, port }`
- **DNS record comment**: `sandbox-<sandbox-id>`
- **Resource tag** *(Enterprise plans only)*: `sandboxId:<sandbox-id>`
On non-Enterprise plans, Cloudflare rejects resource tags; the SDK detects this and retries the request without tags. The DNS comment and tunnel metadata still apply, so you can always trace a resource back to its sandbox.
To list every tunnel created by the SDK for a given account:
```bash
curl "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/cfd_tunnel?name=sandbox-" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```
## Limitations
**Both tunnel flavors:**
- **WARP / Zero Trust egress.** If your local machine runs Cloudflare WARP or another Zero Trust egress policy, outbound traffic to `api.trycloudflare.com` and the cloudflared edge can be blocked. When that happens, `tunnels.get()` hangs on the edge handshake and eventually times out. Disable WARP or add an egress exception for these destinations.
- **Brief DNS warm-up.** The first request through a brand-new URL can take a couple of seconds while DNS propagates, even after `get()` resolves.
**Quick tunnels only:**
- **URLs do not survive container restart.** Cloudflare assigns the hostname during `cloudflared`'s startup handshake, so every restart yields a new URL. The SDK clears its tunnel cache when the container starts, so the next `tunnels.get(port)` returns a fresh record. Use a [named tunnel](#named-tunnels) for a stable hostname.
- **No uptime guarantee.** Cloudflare positions `trycloudflare.com` as a debug aid, not a production target.
- **No Server-Sent Events.** The `trycloudflare.com` edge buffers `text/event-stream` responses, so SSE events never reach the client. WebSockets work normally. Use a [named tunnel](#named-tunnels) if your service streams SSE.
**Named tunnels only:**
- **Single DNS label.** `name` must not contain dots. Universal SSL only covers `<name>.<your-zone>`.
- **Counts against your zone's quotas.** Each named tunnel creates a Cloudflare Tunnel and a DNS record on your account. See [Cloudflare Tunnel limits](/cloudflare-one/networks/connectors/cloudflare-tunnel/configure-tunnels/).
- **Cleanup requires the API token.** If `destroy()` runs after the token has been revoked, the Cloudflare-side resources are orphaned. The SDK logs the orphan IDs so you can remove them manually.
## Related resources
- [Preview URLs concept](/sandbox/sdk/concepts/preview-urls/) — Worker-fronted preview URLs and how they differ from quick tunnels.
- [Ports API](/sandbox/sdk/api/ports/) — `exposePort()` and the Worker-fronted preview URL flow.
- [Expose services guide](/sandbox/sdk/guides/expose-services/) — End-to-end walkthrough for exposing services in production.
- [Transport configuration](/sandbox/sdk/configuration/transport/) — RPC vs. route-based transport.

HTTP API reference
import { WranglerConfig, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
This page documents every route exposed by the sandbox bridge on the stable template.
Authentication
All routes under 
/v1/sandbox/* and 
/v1/openapi.* require a Bearer token:
Authorization: Bearer <SANDBOX_API_KEY>
When 
SANDBOX_API_KEY is not configured, authentication is skipped for local development convenience. Always set the secret before deploying to production.
OpenAPI schema
The bridge serves its own API documentation:
Method
Route
Description
GET
/v1/openapi.json
Machine-readable OpenAPI 3.1 schema.
GET
/v1/openapi
Interactive HTML documentation.
Both routes accept authentication via Bearer header or 
?token= query parameter.
When running locally with 
npm run dev, open 
http://localhost:8787/v1/openapi in your browser to explore every endpoint interactively.
Sandbox lifecycle
Method
Route
Description
POST
/v1/sandbox
Create a new sandbox. Returns 
{"id": "<sandbox-id>"}.
DELETE
/v1/sandbox/:id
Destroy the sandbox container. Returns 
204.
GET
/v1/sandbox/:id/running
Check container liveness. Returns 
{"running": true|false}.
Command execution
Method
Route
Description
POST
/v1/sandbox/:id/exec
Run a command. Response is an SSE stream (see below).
The 
/exec endpoint accepts a JSON body:
{
  "argv": ["sh", "-lc", "echo hello"],
  "timeout_ms": 10000,
  "cwd": "/workspace"
}
Argv escaping
Each element of the 
argv array is escaped using ANSI-C 
$'...' quoting before being joined into a shell command. Tokens that contain only safe characters (
A-Za-z0-9@%+=:,./-) are passed through unchanged. All other tokens are wrapped in 
$'...' with backslashes, single quotes, newlines, carriage returns, and tabs escaped. This prevents shell injection while preserving arguments that contain spaces, quotes, or special characters.
SSE response format
The response is a 
text/event-stream with the following event types:
Event
Data
Description
stdout
Base64-encoded chunk
Standard output from the command.
stderr
Base64-encoded chunk
Standard error from the command.
exit
{"exit_code": N}
Command completed. Terminal event.
error
{"error": "…", "code": "…"}
Command failed. Terminal event.
File operations
Method
Route
Description
GET
/v1/sandbox/:id/file/*
Read a file. Returns raw bytes (
application/octet-stream).
PUT
/v1/sandbox/:id/file/*
Write a file. Request body is raw bytes. Returns 
{"ok": true}. Max 32 MiB.
The file path is encoded in the URL after 
/file/. All paths must resolve within 
/workspace. Path traversal attempts (for example, 
../../etc/passwd) are rejected.
Workspace persistence
Method
Route
Description
POST
/v1/sandbox/:id/persist
Serialize 
/workspace to a tar archive. Returns raw tar bytes.
POST
/v1/sandbox/:id/hydrate
Populate 
/workspace from a tar archive sent as the request body.
The 
/persist endpoint accepts an optional 
excludes query parameter — a comma-separated list of relative paths to exclude from the archive.
The 
/hydrate endpoint accepts a raw tar payload up to 32 MiB.
Bucket mounts
Method
Route
Description
POST
/v1/sandbox/:id/mount
Mount an S3-compatible bucket as a local directory.
POST
/v1/sandbox/:id/unmount
Unmount a previously mounted bucket.
The 
/mount endpoint accepts a JSON body. Two flows are supported:
R2 binding mounts
Omit 
endpoint and pass the Worker R2 binding name in 
bucket:
{
  "bucket": "MY_BUCKET",
  "mountPath": "/mnt/data",
  "options": {
    "readOnly": false,
    "prefix": "/subdir"
  }
}
When 
options.endpoint is omitted, 
bucket means the Worker R2 binding name.
For an explicit S3-compatible endpoint mount, include 
endpoint and optionally 
credentials:
{
  "bucket": "my-r2-bucket",
  "mountPath": "/mnt/data",
  "options": {
    "endpoint": "https://ACCOUNT_ID.r2.cloudflarestorage.com",
    "readOnly": false,
    "prefix": "/subdir",
    "credentials": {
      "accessKeyId": "...",
      "secretAccessKey": "..."
    }
  }
}
When 
endpoint is provided, 
bucket means the remote bucket name. Credentials are optional in this mode only — the bridge auto-detects from Worker secrets (
R2_ACCESS_KEY_ID / 
R2_SECRET_ACCESS_KEY or 
AWS_ACCESS_KEY_ID / 
AWS_SECRET_ACCESS_KEY) when omitted.
Sessions
Method
Route
Description
POST
/v1/sandbox/:id/session
Create a session. Returns 
{"id": "<session-id>"}.
DELETE
/v1/sandbox/:id/session/:sid
Delete a session. Returns 
204.
Sessions isolate working directory, environment variables, and command execution state within a sandbox. Pass the 
Session-Id header on 
/exec, 
/file/*, and 
/pty requests to scope them to a session.
When no 
Session-Id header is provided, requests use the sandbox's implicit execution mode. By default this is the default session, but SDKs configured with 
enableDefaultSession: false run those implicit operations sessionless instead.
Terminal (PTY)
Method
Route
Description
GET
/v1/sandbox/:id/pty
Upgrade to a WebSocket PTY session.
Query parameters:
Parameter
Type
Default
Description
cols
number
80
Terminal width in columns.
rows
number
24
Terminal height in rows.
shell
string
—
Shell binary (for example, 
/bin/bash).
session
string
—
Session ID for session-scoped PTY.
The WebSocket carries binary frames for terminal I/O and JSON text frames for control messages:
Direction
Frame type
Content
Client to server
Binary
UTF-8 encoded keystrokes.
Server to client
Binary
Terminal output including ANSI escape sequences.
Client to server
Text (JSON)
Control messages (for example, 
{"type": "resize", "cols": 120, "rows": 30}).
Server to client
Text (JSON)
Status messages (
ready, 
exit, 
error).
Warm pool
Method
Route
Description
GET
/v1/pool/stats
Current pool statistics.
POST
/v1/pool/prime
Start the warm pool alarm loop.
POST
/v1/pool/shutdown-prewarmed
Stop all idle warm containers.
The warm pool pre-starts sandbox containers so new sessions boot instantly. Configure it with environment variables in 
wrangler.jsonc:
[vars]
WARM_POOL_TARGET = "3"           # Number of idle containers to keep warm (0 = disabled)
WARM_POOL_REFRESH_INTERVAL = "10000"  # Health-check interval in milliseconds
A cron trigger (
* * * * *) primes the pool automatically after deployment. Set 
WARM_POOL_TARGET to 
"0" (the default) to disable the pool and avoid unexpected costs.
Health check
Method
Route
Description
GET
/health
Unauthenticated liveness probe. Returns 
{"ok": true}.
Related resources
Bridge overview — What the bridge is, deployment, and usage examples.
Sandbox API reference — Complete Sandbox SDK method reference.
Bridge source on GitHub — Worker, Dockerfile, and OpenAPI schema.

Sandbox bridge
import { Details, Tabs, TabItem, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
The sandbox bridge is a reference-implementation Cloudflare Worker that exposes the Sandbox SDK as an HTTP API. Any HTTP client — Python script, Node.js service, CI pipeline — can create and control sandboxes without writing a Worker. You deploy the Worker in your account; it is not a Cloudflare-hosted shared API.
Why use the bridge
The Sandbox SDK is designed for use within Cloudflare Workers. If your application runs outside of the Workers ecosystem, it cannot interact with sandboxes directly.
The bridge exposes the Sandbox SDK as a standard HTTP API so you can create and control sandboxes from any language or platform.
Key Sandbox SDK methods map to individual HTTP endpoints. The bridge adds authentication, input validation, workspace path containment, and an optional warm pool for instant container boot.
Deploy
Deploy the bridge Worker to your Cloudflare account:
The button deploys the Worker and generates a 
SANDBOX_API_KEY secret for authentication. When deployment finishes, note your Worker URL and API key — every example on this page uses them.
If you prefer to deploy step by step, scaffold the project and deploy manually.
Prerequisites:
A Cloudflare account with the Containers / Sandbox beta enabled.
Node.js and npm.
Docker running locally — 
wrangler deploy builds a container image from the bridge 
Dockerfile.
Steps:
Scaffold the bridge project:
npm create cloudflare -- sandbox-bridge --template=cloudflare/sandbox-sdk/bridge/worker#v0
cd sandbox-bridge
Authenticate with Cloudflare:
npx wrangler login
Set the API key secret. Choose any strong token value — clients must send this as a Bearer token:
openssl rand -hex 32 | tee /dev/stderr | npx wrangler secret put SANDBOX_API_KEY
The key is printed to your terminal and piped to Wrangler. Save it — you will need it to authenticate API requests.
Deploy the Worker:
npx wrangler deploy
Verify the deployment:
curl https://cloudflare-sandbox-bridge.<your-subdomain>.workers.dev/health
You should see 
{"ok":true}.
Container image
The bridge 
Dockerfile extends the 
cloudflare/sandbox base image and pre-installs common agent tooling:
Languages: Python 3.13, Node.js, Bun
Tools: git, ripgrep, curl, wget, jq, tar, sed, gawk, procps
Customize the 
Dockerfile to add languages, system packages, or tools your workloads need.
Usage
All examples assume the following environment variables are set:
export SANDBOX_API_URL=https://cloudflare-sandbox-bridge.<your-subdomain>.workers.dev
export SANDBOX_API_KEY=<your-token>
Create a sandbox and run a command
# Create a sandbox
SANDBOX_ID=$(curl -s -X POST "$SANDBOX_API_URL/v1/sandbox" \
  -H "Authorization: Bearer $SANDBOX_API_KEY" | jq -r '.id')
echo "Sandbox ID: $SANDBOX_ID"
# Run a command
curl -s -X POST "$SANDBOX_API_URL/v1/sandbox/$SANDBOX_ID/exec" \
  -H "Authorization: Bearer $SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"argv": ["sh", "-lc", "echo hello from the sandbox"], "timeout_ms": 10000}'
# Destroy the sandbox when done
curl -s -X DELETE "$SANDBOX_API_URL/v1/sandbox/$SANDBOX_ID" \
  -H "Authorization: Bearer $SANDBOX_API_KEY"
const API_URL = process.env.SANDBOX_API_URL;
const API_KEY = process.env.SANDBOX_API_KEY;
const headers = {
  Authorization: `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
};
// Create a sandbox
const { id } = await fetch(`${API_URL}/v1/sandbox`, {
  method: "POST",
  headers,
}).then((r) => r.json());
console.log(`Sandbox ID: ${id}`);
// Run a command
// Response is a text/event-stream with the following SSE events:
//   event: stdout  — data is a base64-encoded output chunk
//   event: stderr  — data is a base64-encoded error chunk
//   event: exit    — data is JSON: {"exit_code": 0}
//   event: error   — data is JSON: {"error": "...", "code": "..."}
const execRes = await fetch(`${API_URL}/v1/sandbox/${id}/exec`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    argv: ["sh", "-lc", "echo hello from the sandbox"],
    timeout_ms: 10000,
  }),
});
console.log(await execRes.text());
// Destroy the sandbox when done
await fetch(`${API_URL}/v1/sandbox/${id}`, {
  method: "DELETE",
  headers,
});
# /// script
# dependencies = ["httpx"]
# ///
import os
import httpx
API_URL = os.environ["SANDBOX_API_URL"]
API_KEY = os.environ["SANDBOX_API_KEY"]
headers = {"Authorization": f"Bearer {API_KEY}"}
# Create a sandbox
resp = httpx.post(f"{API_URL}/v1/sandbox", headers=headers)
sandbox_id = resp.json()["id"]
print(f"Sandbox ID: {sandbox_id}")
# Run a command
# Response is a text/event-stream with the following SSE events:
#   event: stdout  — data is a base64-encoded output chunk
#   event: stderr  — data is a base64-encoded error chunk
#   event: exit    — data is JSON: {"exit_code": 0}
#   event: error   — data is JSON: {"error": "...", "code": "..."}
exec_resp = httpx.post(
    f"{API_URL}/v1/sandbox/{sandbox_id}/exec",
    headers=headers,
    json={
        "argv": ["sh", "-lc", "echo hello from the sandbox"],
        "timeout_ms": 10000,
    },
)
print(exec_resp.text)
# Destroy the sandbox when done
httpx.delete(f"{API_URL}/v1/sandbox/{sandbox_id}", headers=headers)
Write and read files
# Write a file
curl -s -X PUT "$SANDBOX_API_URL/v1/sandbox/$SANDBOX_ID/file/workspace/hello.py" \
  -H "Authorization: Bearer $SANDBOX_API_KEY" \
  --data-binary 'print("hello world")'
# Read a file
curl -s "$SANDBOX_API_URL/v1/sandbox/$SANDBOX_ID/file/workspace/hello.py" \
  -H "Authorization: Bearer $SANDBOX_API_KEY"
// Write a file
await fetch(`${API_URL}/v1/sandbox/${id}/file/workspace/hello.py`, {
  method: "PUT",
  headers,
  body: 'print("hello world")',
});
// Read a file
const content = await fetch(
  `${API_URL}/v1/sandbox/${id}/file/workspace/hello.py`,
  { headers },
).then((r) => r.text());
console.log(content);
# /// script
# dependencies = ["httpx"]
# ///
import os
import httpx
API_URL = os.environ["SANDBOX_API_URL"]
API_KEY = os.environ["SANDBOX_API_KEY"]
SANDBOX_ID = os.environ["SANDBOX_ID"]  # from the "Create a sandbox" step
headers = {"Authorization": f"Bearer {API_KEY}"}
# Write a file
httpx.put(
    f"{API_URL}/v1/sandbox/{SANDBOX_ID}/file/workspace/hello.py",
    headers=headers,
    content=b'print("hello world")',
)
# Read a file
content = httpx.get(
    f"{API_URL}/v1/sandbox/{SANDBOX_ID}/file/workspace/hello.py",
    headers=headers,
).text
print(content)
Keep the bridge updated
The bulk of the bridge logic is in the 
@cloudflare/sandbox package. To pull in the latest improvements:
Update the SDK dependency:
npm update @cloudflare/sandbox
Redeploy:
npx wrangler deploy
Check the sandbox-sdk releases for changes to the 
Dockerfile or bridge configuration that may require manual updates.
Source code and examples
The bridge source code and examples are available on GitHub:
Bridge source — Worker, Dockerfile, deploy script, and OpenAPI schema.
Workspace chat example — Full-stack chat application with a file browser sidebar.
Basic example — One-shot Python coding agent using the OpenAI Agents SDK.
Related resources
HTTP API reference — Complete route reference for the bridge API.
Getting started — Build your first sandbox application directly on Workers.
Architecture — How the Sandbox SDK layers Workers, Durable Objects, and Containers.
API reference — Complete Sandbox SDK method reference.
OpenAI Agents SDK tutorial — Build a Python coding agent with the bridge.

Architecture
import { WranglerConfig, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
Sandbox SDK lets you execute untrusted code safely from your Workers. It combines three Cloudflare technologies to provide secure, stateful, and isolated execution:
Workers - Your application logic that calls the Sandbox SDK
Durable Objects - Persistent sandbox instances with unique identities
Containers - Isolated Linux environments where code actually runs
Architecture overview
flowchart TB
    accTitle: Sandbox SDK Architecture
    accDescr: Three-layer architecture showing how Cloudflare Sandbox SDK combines Workers, Durable Objects, and Containers for secure code execution
    subgraph UserSpace["<b>Your Worker</b>"]
        Worker["Application code using the methods exposed by the Sandbox SDK"]
    end
    subgraph SDKSpace["<b>Sandbox SDK Implementation</b>"]
        DO["Sandbox Durable Object routes requests & maintains state"]
        Container["Isolated Ubuntu container executes untrusted code safely"]
        DO -->|HTTP API| Container
    end
    Worker -->|RPC call via the Durable Object stub returned by `getSandbox`| DO
    style UserSpace fill:#fff8f0,stroke:#f6821f,stroke-width:2px
    style SDKSpace fill:#f5f5f5,stroke:#666,stroke-width:2px,stroke-dasharray: 5 5
    style Worker fill:#ffe8d1,stroke:#f6821f,stroke-width:2px
    style DO fill:#dce9f7,stroke:#1d8cf8,stroke-width:2px
    style Container fill:#d4f4e2,stroke:#17b26a,stroke-width:2px
Layer 1: Client SDK
The developer-facing API you use in your Workers:
import { getSandbox } from "@cloudflare/sandbox";
const sandbox = getSandbox(env.Sandbox, "my-sandbox");
const result = await sandbox.exec("python script.py");
Purpose: Provide a clean, type-safe TypeScript interface for all sandbox operations.
Layer 2: Durable Object
Manages sandbox lifecycle and routing:
export class Sandbox extends DurableObject<Env> {
	// Extends Cloudflare Container for isolation
	// Routes requests between client and container
	// Manages preview URLs and state
}
Purpose: Provide persistent, stateful sandbox instances with unique identities.
Why Durable Objects:
Persistent identity - Same sandbox ID always routes to same instance
Container management - Durable Object owns and manages the container lifecycle
Geographic distribution - Sandboxes run close to users
Automatic scaling - Cloudflare manages provisioning
Layer 3: Container Runtime
Executes code in isolation with full Linux capabilities.
Purpose: Safely execute untrusted code.
Why containers:
VM-based isolation - Each sandbox runs in its own VM
Full environment - Ubuntu Linux with Python, Node.js, Git, etc.
Communication transports
The SDK supports three transport protocols for communication between the Durable Object and container:
HTTP transport (default)
Each SDK method makes a separate HTTP request to the container API. Simple, reliable, and works for most use cases.
// Default behavior - uses HTTP
const sandbox = getSandbox(env.Sandbox, "my-sandbox");
await sandbox.exec("python script.py");
RPC transport
Multiplexes all SDK calls over a single persistent connection. It avoids subrequest limits when making many concurrent operations.
Enable RPC transport by setting the 
SANDBOX_TRANSPORT variable in your Worker's configuration:
```jsonc
{
	"vars": {
		"SANDBOX_TRANSPORT": "rpc"
	},
}
```
WebSocket transport
WebSocket transport is deprecated. Use RPC transport for new applications.
The transport layer is transparent to your application code — all SDK methods work identically regardless of transport. For details on when to use each transport and configuration examples, refer to Transport modes.
Request flow
When you execute a command:
await sandbox.exec("python script.py");
HTTP transport flow:
Client SDK validates parameters and sends HTTP request to Durable Object
Durable Object authenticates and forwards HTTP request to container
Container Runtime validates inputs, executes command, captures output
Response flows back through all layers with proper error transformation
RPC transport flow:
Client SDK validates parameters and sends the request to the Durable Object
Durable Object maintains the persistent connection to the container and multiplexes concurrent requests
Container Runtime adapts RPC messages to HTTP-style request and response handling
Response flows back over the same connection with proper error transformation
The Durable Object establishes the persistent connection to the container on first SDK call and reuses it for all subsequent operations, reducing overhead for high-frequency operations.
Related resources
Sandbox lifecycle - How sandboxes are created and managed
Container runtime - Inside the execution environment
Security model - How isolation and validation work
Session management - Advanced state management

Directory backups
import { Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/concepts/lifetime/", title: "Sandbox lifetime" }} />
Backup and restore snapshot a sandbox directory into an R2 archive, then bring that tree back later. The public API is the same in production and in 
wrangler dev. The restore mechanism is not.
Use backups when you want a project directory such as 
/workspace to return later. Use bucket mounts when a separate storage path such as 
/data should persist independently of the sandbox filesystem.
Production restore
In production, 
restoreBackup() mounts the squashfs archive with FUSE overlayfs:
The backup is a read-only lower layer.
New writes go to a writable upper layer.
The original archive in R2 does not change.
Restoring the same handle again discards the upper layer.
The overlay exists only while the container is running. When the sandbox sleeps or the container restarts, the mount is gone and the directory is empty. Store the 
DirectoryBackup handle and restore again.
Local restore
With 
localBucket: true, 
wrangler dev extracts the archive with 
unsquashfs. The target directory is replaced. There is no overlay, so local restore does not reproduce production FUSE behavior.
Cross-device renames
Overlayfs treats the lower and upper layers as different devices. A rename that moves a directory from the restored lower layer into the writable upper layer can fail with 
EXDEV (
cross-device link not permitted).
Vite does this with 
node_modules/.vite/deps. Omit that directory from the backup, or delete it after restore.
For the procedure, refer to Exclude generated caches.
Related resources
Backup and restore - Create, restore, and exclude caches
Backups API - Method signatures and options
Sandbox lifecycle - What happens when a sandbox sleeps

Container runtime
import { Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
Each sandbox runs in an isolated Linux container with Python, Node.js, and common development tools pre-installed. For a complete list of pre-installed software and how to customize the container image, see Dockerfile reference.
Runtime software installation
Install additional software at runtime using standard package managers:
# Python packages
pip install scikit-learn tensorflow
# Node.js packages
npm install express
# System packages (requires apt-get update first)
apt-get update && apt-get install -y redis-server
Filesystem
The container provides a standard Linux filesystem. You can read and write anywhere you have permissions.
Standard directories:
/workspace - Default working directory for user code
/tmp - Temporary files
/home - User home directory
/usr/bin, 
/usr/local/bin - Executable binaries
Example:
await sandbox.writeFile('/workspace/app.py', 'print("Hello")');
await sandbox.writeFile('/tmp/cache.json', '{}');
await sandbox.exec('ls -la /workspace');
Process management
Processes run as you'd expect in a regular Linux environment.
Foreground processes (
exec()):
const result = await sandbox.exec('npm test');
// Waits for completion, returns output
Background processes (
startProcess()):
const process = await sandbox.startProcess('node server.js');
// Returns immediately, process runs in background
Network capabilities
Outbound connections work:
curl https://api.example.com/data
pip install requests
npm install express
Inbound connections require port exposure:
const { hostname } = new URL(request.url);
await sandbox.startProcess('python -m http.server 8000');
const exposed = await sandbox.exposePort(8000, { hostname });
console.log(exposed.url); // Public URL
:::note[Local development]
When using 
wrangler dev, you must add 
EXPOSE directives to your Dockerfile for each port. See Local development with ports.
:::
Localhost works within sandbox:
redis-server &      # Start server
redis-cli ping      # Connect locally
Security
Between sandboxes (isolated):
Each sandbox is a separate container
Filesystem, memory and network are all isolated
Within sandbox (shared):
All processes see the same files
Processes can communicate with each other
Environment variables are session-scoped
To run untrusted code, use separate sandboxes per user:
const sandbox = getSandbox(env.Sandbox, `user-${userId}`);
Limitations
Cannot:
Load kernel modules or access host hardware
Related resources
Deploy a Sandbox application - Deploy and keep package and image aligned
Deploy Containers - Containers deploy path
Architecture - How containers fit in the system
Security model - Container isolation details
Sandbox lifecycle - Container lifecycle management
Docker-in-Docker - Run Docker containers inside a Sandbox

Concepts
import { Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
These pages explain how the Sandbox SDK works, why it's designed the way it is, and the concepts you need to understand to use it effectively.
Architecture - How the SDK is structured and why
Sandbox lifecycle - Understanding sandbox states and behavior
Container runtime - How code executes in isolated containers
Session management - When and how to use sessions
Preview URLs - How to expose sandboxed services on the public internet.
Security model - Isolation, validation, and safety mechanisms
Terminal connections - How browser terminal connections work
Directory backups - Overlay restore, local extract, and cross-device renames
Related resources
Tutorials - Learn by building complete applications
How-to guides - Solve specific problems
API reference - Technical details and method signatures

Preview URLs
import { Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/previews/", title: "Preview a web application" }} />
Quick deployment
For quick preview deployments we recommend using Cloudflare Tunnel to generate preview URLs to your web services. These work across local development, workers.dev and production usage.
await sandbox.startProcess("python -m http.server 8000");
const tunnel = await sandbox.tunnels.get(8000);
console.log(tunnel.url);
// https://acute-llama-dancing-roundly.trycloudflare.app
// Request will be routed directly to the webserver running on the sandbox.
const req = await fetch(`${tunnel.url}/api/users`); // => GET http://localhost:8000/api/users
Cloudflare Tunnel support currently has the following limitations:
No control over generated URL.
No authentication mechanism beyond randomly generated URL.
Each URL uses an additional 
cloudflared process on the sandbox.
:::note[Production requires custom domain]
We are working on production deployments, custom hostnames and authentication for Cloudflare Tunnel support. In the mean time we recommend using 
exposePort() and 
proxyToSandbox() documented below under Production usage, stable URLs and custom domains.
:::
See the tunnels API reference for the full API and feature set.
Production usage, stable URLs & custom domains
For production use we recommend using the 
exposePort() API and routing traffic through your worker.
:::note[Custom domain for exposePort production URLs]
Local development does not need a custom domain or wildcard DNS for 
exposePort() preview URLs. For production, you need a custom domain with wildcard DNS routing. Refer to Configure preview URLs on a custom domain.
:::
Preview URLs provide public HTTPS access to services running inside sandboxes. When you expose a port, you get a unique URL that proxies requests to your service.
// Extract hostname from request
const { hostname } = new URL(request.url);
await sandbox.startProcess("python -m http.server 8000");
const exposed = await sandbox.exposePort(8000, { hostname });
console.log(exposed.url);
// Production: https://8000-sandbox-id-abc123random4567.yourdomain.com
// Local dev: http://8000-sandbox-id-abc123random4567.localhost:{port}/
URL Format
Production: 
https://{port}-{sandbox-id}-{token}.yourdomain.com
With auto-generated token: 
https://8080-abc123-random16chars12.yourdomain.com
With custom token: 
https://8080-abc123-my_api_v1.yourdomain.com
Local development: 
http://{port}-{sandbox-id}-{token}.localhost:{dev-server-port}
Token Types
Auto-generated tokens (default)
When no custom token is specified, a random 16-character token is generated:
const exposed = await sandbox.exposePort(8000, { hostname });
// https://8000-sandbox-id-abc123random4567.yourdomain.com
URLs with auto-generated tokens change when you unexpose and re-expose a port.
Custom tokens for stable URLs
For production deployments or shared URLs, specify a custom token to maintain consistency across container restarts:
const stable = await sandbox.exposePort(8000, {
	hostname,
	token: "api_v1",
});
// https://8000-sandbox-id-api_v1.yourdomain.com
// Same URL every time ✓
Token requirements:
1-16 characters long
Lowercase letters (a-z), numbers (0-9), and underscores (_) only
Must be unique within each sandbox
Use cases for custom tokens:
Production APIs with stable endpoints
Sharing demo URLs with external users
Documentation with consistent examples
Integration testing with predictable URLs
ID Case Sensitivity
Preview URLs extract the sandbox ID from the hostname to route requests. Since hostnames are case-insensitive (per RFC 3986), they're always lowercased: 
8080-MyProject-123.yourdomain.com becomes 
8080-myproject-123.yourdomain.com.
The problem: If you create a sandbox with 
"MyProject-123", it exists as a Durable Object with that exact ID. But the preview URL routes to 
"myproject-123" (lowercased from the hostname). These are different Durable Objects, so your sandbox is unreachable via preview URL.
// Problem scenario
const sandbox = getSandbox(env.Sandbox, "MyProject-123");
// Durable Object ID: "MyProject-123"
await sandbox.exposePort(8080, { hostname });
// Preview URL: 8080-myproject-123-token123.yourdomain.com
// Routes to: "myproject-123" (different DO - doesn't exist!)
The solution: Use 
normalizeId: true to lowercase IDs when creating sandboxes:
const sandbox = getSandbox(env.Sandbox, "MyProject-123", {
	normalizeId: true,
});
// Durable Object ID: "myproject-123" (lowercased)
// Preview URL: 8080-myproject-123-token123.yourdomain.com
// Routes to: "myproject-123" (same DO - works!)
Without 
normalizeId: true, 
exposePort() throws an error when the ID contains uppercase letters.
Best practice: Use lowercase IDs from the start (
'my-project-123'). See Sandbox options - normalizeId for details.
Request Routing
You must call 
proxyToSandbox() first in your Worker's fetch handler to route preview URL requests:
import { proxyToSandbox, getSandbox } from "@cloudflare/sandbox";
export { Sandbox } from "@cloudflare/sandbox";
export default {
	async fetch(request, env) {
		// Handle preview URL routing first
		const proxyResponse = await proxyToSandbox(request, env);
		if (proxyResponse) return proxyResponse;
		// Your application routes
		// ...
	},
};
Requests flow: Browser → Your Worker → Durable Object (sandbox) → Your Service.
Multiple Ports
Expose multiple services simultaneously:
// Extract hostname from request
const { hostname } = new URL(request.url);
await sandbox.startProcess("node api.js"); // Port 3000
await sandbox.startProcess("node admin.js"); // Port 3001
const api = await sandbox.exposePort(3000, { hostname, name: "api" });
const admin = await sandbox.exposePort(3001, { hostname, name: "admin" });
// Each gets its own URL with unique tokens:
// https://3000-abc123-random16chars01.yourdomain.com
// https://3001-abc123-random16chars02.yourdomain.com
What Works
HTTP/HTTPS requests
WebSocket connections
Server-Sent Events
All HTTP methods (GET, POST, PUT, DELETE, etc.)
Request and response headers
What Does Not Work
Raw TCP/UDP connections
Custom protocols (must wrap in HTTP)
Ports outside range 1024-65535
Port 3000 (used internally by the SDK)
WebSocket Support
Preview URLs support WebSocket connections. When a WebSocket upgrade request hits an exposed port, the routing layer automatically handles the connection handshake.
// Extract hostname from request
const { hostname } = new URL(request.url);
// Start a WebSocket server
await sandbox.startProcess("bun run ws-server.ts 8080");
const { url } = await sandbox.exposePort(8080, { hostname });
// Clients connect using WebSocket protocol
// Browser: new WebSocket('wss://8080-abc123-token123.yourdomain.com')
// Your Worker routes automatically
export default {
	async fetch(request, env) {
		const proxyResponse = await proxyToSandbox(request, env);
		if (proxyResponse) return proxyResponse;
	},
};
For custom routing scenarios where your Worker needs to control which sandbox or port to connect to based on request properties, see 
wsConnect() in the Ports API.
Security
:::caution
Preview URLs are publicly accessible by default, but require a valid access token that is generated when you expose a port.
:::
Built-in security:
Token-based access - Each exposed port gets a unique token in the URL (for example, 
https://8080-sandbox-abc123token456.yourdomain.com)
HTTPS in production - All traffic is encrypted with TLS. Certificates are provisioned automatically for first-level wildcards (
*.yourdomain.com). If your Worker runs on a subdomain, refer to the TLS note for custom domains.
Unpredictable URLs - Auto-generated tokens are randomly generated and difficult to guess
Token collision prevention - Custom tokens are validated to ensure uniqueness within each sandbox
Add application-level authentication:
For additional security, implement authentication within your application:
from flask import Flask, request, abort
app = Flask(__name__)
@app.route('/data')
def get_data():
    # Check for your own authentication token
    auth_token = request.headers.get('Authorization')
    if auth_token != 'Bearer your-secret-token':
        abort(401)
    return {'data': 'protected'}
This adds a second layer of security on top of the URL token.
Troubleshooting
URL Not Accessible
Check if service is running and listening:
// 1. Is service running?
const processes = await sandbox.listProcesses();
// 2. Is port exposed?
const ports = await sandbox.getExposedPorts();
// 3. Is service binding to 0.0.0.0 (not 127.0.0.1)?
// Good:
app.run((host = "0.0.0.0"), (port = 3000));
// Bad (localhost only):
app.run((host = "127.0.0.1"), (port = 3000));
Production Errors
For custom domain issues, refer to preview URL custom domain troubleshooting.
Local Development
:::caution[Local development limitation]
When using 
wrangler dev, you must expose ports in your Dockerfile:
FROM docker.io/cloudflare/sandbox:0.12.14
# Required for local development
EXPOSE 3000
EXPOSE 8080
Without 
EXPOSE, you'll see: 
connect(): Connection refused: container port not found
This is only required for local development. In production, all container ports are automatically accessible.
:::
Related Resources
Configure preview URLs on a custom domain - Wildcard DNS and TLS for 
exposePort()
Deploy a Sandbox application - Worker and container image deploys
Expose Services - Practical patterns for exposing ports
Ports API - Complete API reference
Tunnels API - Zero-config 
*.trycloudflare.com URLs as an alternative for development
Security Model - Security best practices

Sandbox lifecycle
import { Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/concepts/lifetime/", title: "Sandbox lifetime" }} />
A sandbox is an isolated execution environment where your code runs. Each sandbox:
Has a unique identifier (sandbox ID)
Contains an isolated filesystem
Runs in a dedicated Linux container
Maintains state while the container is active
Exists as a Cloudflare Durable Object
Lifecycle states
Creation
A sandbox is created the first time you reference its ID:
const sandbox = getSandbox(env.Sandbox, "user-123");
await sandbox.exec('echo "Hello"'); // First request creates sandbox
Active
The sandbox container is running and processing requests. All state remains available: files, running processes, shell sessions, and environment variables.
Idle
After a period of inactivity (10 minutes by default, configurable via 
sleepAfter), the container stops to free resources. When the next request arrives, a fresh container starts. All previous state is lost and the environment resets to its initial state.
Note: Containers with 
keepAlive: true never enter the idle state. They automatically send heartbeat pings every 30 seconds to prevent eviction.
Destruction
Sandboxes are explicitly destroyed or automatically cleaned up:
await sandbox.destroy();
// All files, processes, and state deleted permanently
Container lifetime and state
Sandbox state exists only while the container is active. Understanding this is critical for building reliable applications.
While the container is active (typically minutes to hours of activity):
Files written to 
/workspace, 
/tmp, 
/home remain available
Background processes continue running
Shell sessions maintain their working directory and environment
Code interpreter contexts retain variables and imports
When the container stops (due to inactivity or explicit destruction):
All files are deleted
All processes terminate
All shell state resets
All code interpreter contexts are cleared
The next request creates a fresh container with a clean environment.
Naming strategies
Per-user sandboxes
const sandbox = getSandbox(env.Sandbox, `user-${userId}`);
Use this pattern for interactive environments, playgrounds, and notebooks where each user returns to their own active workspace.
Per-session sandboxes
const sessionId = `session-${Date.now()}-${Math.random()}`;
const sandbox = getSandbox(env.Sandbox, sessionId);
// Later:
await sandbox.destroy();
Use this pattern for one-time execution, CI/CD, and tests that need a clean environment.
Per-task sandboxes
const sandbox = getSandbox(env.Sandbox, `build-${repoName}-${commit}`);
Idempotent operations with clear task-to-sandbox mapping. Good for builds, pipelines, and background jobs.
Request routing
The first request to a sandbox determines its geographic location. Subsequent requests route to the same location.
For global apps:
Option 1: Multiple sandboxes per user with region suffix (
user-123-us, 
user-123-eu)
Option 2: Single sandbox per user (simpler, but some users see higher latency)
Lifecycle management
When to destroy
try {
	const sandbox = getSandbox(env.Sandbox, sessionId);
	await sandbox.exec("npm run build");
} finally {
	await sandbox.destroy(); // Clean up temporary sandboxes
}
Destroy when: Session ends, task completes, resources no longer needed
Do not destroy: Personal environments, long-running services
Managing keepAlive containers
Containers with 
keepAlive: true require explicit management since they do not timeout automatically:
const sandbox = getSandbox(env.Sandbox, 'persistent-task', {
  keepAlive: true
});
// Later, when done with long-running work
await sandbox.setKeepAlive(false); // Allow normal timeout behavior
// Or explicitly destroy:
await sandbox.destroy();
Handling container restarts
Containers restart after inactivity or failures. Design your application to handle state loss:
// Check if required files exist before using them
const files = await sandbox.listFiles("/workspace");
if (!files.includes("data.json")) {
	// Reinitialize: container restarted and lost previous state
	await sandbox.writeFile("/workspace/data.json", initialData);
}
await sandbox.exec("python process.py");
Version compatibility
The SDK automatically checks that your npm package version matches the Docker container image version. Version mismatches can cause features to break or behave unexpectedly.
What happens:
On sandbox startup, the SDK queries the container's version
If versions do not match, a warning is logged
Some features may not work correctly if versions are incompatible
When you might see warnings:
You updated the npm package (
npm install @cloudflare/sandbox@0) but forgot to update the 
FROM line in your Dockerfile
How to fix:
Update your Dockerfile to match your npm package version. For example, if using 
@cloudflare/sandbox@0.12.14:
# Default image (JavaScript/TypeScript)
FROM docker.io/cloudflare/sandbox:0.12.14
# Or Python image if you need Python support
FROM docker.io/cloudflare/sandbox:0.12.14-python
See Dockerfile reference for details on image variants and extending the base image.
Best practices
Name consistently - Use clear, predictable naming schemes
Clean up temporary sandboxes - Always destroy when done
Reuse user workspaces - One long-lived sandbox per user is often sufficient
Batch operations - Combine commands: 
npm install && npm test && npm build
Design for ephemeral state - Containers restart after inactivity, losing all state
Related resources
Architecture - How sandboxes fit in the system
Container runtime - What runs inside sandboxes
Session management - Advanced state isolation
Directory backups - Why restored files do not survive sleep unless you restore again
Lifecycle API - Create and manage sandboxes
Sessions API - Create and manage execution sessions

Security model
import { Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/concepts/security/", title: "Sandbox security" }} />
The Sandbox SDK is built on Containers, which run each sandbox in its own VM for strong isolation.
Container isolation
Each sandbox runs in a separate VM, providing complete isolation:
Filesystem isolation - Sandboxes cannot access other sandboxes' files
Process isolation - Processes in one sandbox cannot see or affect others
Network isolation - Sandboxes have separate network stacks
Resource limits - CPU, memory, and disk quotas are enforced per sandbox
For complete security details about the underlying container platform, see Containers architecture.
Within a sandbox
All code within a single sandbox shares resources:
Filesystem - All processes see the same files
Processes - All sessions can see all processes
Network - Processes can communicate via localhost
For complete isolation, use separate sandboxes per user:
// Good - Each user in separate sandbox
const userSandbox = getSandbox(env.Sandbox, `user-${userId}`);
// Bad - Users sharing one sandbox
const shared = getSandbox(env.Sandbox, 'shared');
// Users can read each other's files!
Input validation
Command injection
Always validate user input before using it in commands:
// Dangerous - user input directly in command
const filename = userInput;
await sandbox.exec(`cat ${filename}`);
// User could input: "file.txt; rm -rf /"
// Safe - validate input
const filename = userInput.replace(/[^a-zA-Z0-9._-]/g, '');
await sandbox.exec(`cat ${filename}`);
// Better - use file API
await sandbox.writeFile('/tmp/input', userInput);
await sandbox.exec('cat /tmp/input');
Authentication
Sandbox access
Sandbox IDs provide basic access control but aren't cryptographically secure. Add application-level authentication:
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const userId = await authenticate(request);
    if (!userId) {
      return new Response('Unauthorized', { status: 401 });
    }
    // User can only access their sandbox
    const sandbox = getSandbox(env.Sandbox, userId);
    return Response.json({ authorized: true });
  }
};
Preview URLs
Preview URLs include randomly generated tokens. Anyone with the URL can access the service.
To revoke access, unexpose the port:
await sandbox.unexposePort(8080);
Quick tunnel URLs
Quick tunnels (
sandbox.tunnels.get(port)) return a 
*.trycloudflare.com URL with a random hostname assigned by Cloudflare — there is no separate access token. The hostname itself is the access control: anyone who knows the URL can reach the service. To revoke access, destroy the tunnel:
await sandbox.tunnels.destroy(8080);
URLs do not survive a container restart, so a restart effectively rotates the hostname. As with preview URLs, add application-level authentication for any sensitive service. See the Tunnels API for details.
from flask import Flask, request, abort
import os
app = Flask(__name__)
def check_auth():
    token = request.headers.get('Authorization')
    if token != f"Bearer {os.environ['AUTH_TOKEN']}":
        abort(401)
@app.route('/api/data')
def get_data():
    check_auth()
    return {'data': 'protected'}
Secrets management
Use environment variables, not hardcoded secrets, for values the sandbox process must consume directly:
// Bad - hardcoded in file
await sandbox.writeFile('/workspace/config.js', `
  const API_KEY = 'sk_live_abc123';
`);
// Good - use environment variables for values the sandbox process needs
await sandbox.startProcess('node app.js', {
  env: {
    API_KEY: env.API_KEY,  // From Worker environment binding
  }
});
For external API credentials that the sandbox does not need to read directly, keep the credential in the Worker and inject it with an outbound handler.
Clean up temporary sensitive data:
try {
  await sandbox.writeFile('/tmp/sensitive.txt', secretData);
  await sandbox.exec('python process.py /tmp/sensitive.txt');
} finally {
  await sandbox.deleteFile('/tmp/sensitive.txt');
}
Handle outbound traffic
Passing external API credentials directly to a sandbox — via environment variables or files — means the sandbox process holds a live credential that any code running inside it can read. Outbound handlers remove that exposure by keeping credentials in the Worker and injecting them into outbound requests.
The flow works as follows:
Sandbox request → Outbound handler (injects real credentials) → External API
The sandbox never sees the real credential. Rotate the secret in your Worker's environment and every request uses the updated value.
This pattern is useful when accessing GitHub for private repository operations, AI services, or object storage where you want to keep credentials out of the container entirely. For implementation details, refer to Handle outbound traffic.
What the SDK protects against
Sandbox-to-sandbox access (VM isolation)
Resource exhaustion (enforced quotas)
Container escapes (VM-based isolation)
What you must implement
Authentication and authorization
Input validation and sanitization
Rate limiting
Application-level security (SQL injection, XSS, etc.)
Best practices
Use separate sandboxes for isolation:
const sandbox = getSandbox(env.Sandbox, `user-${userId}`);
Validate all inputs:
const safe = input.replace(/[^a-zA-Z0-9._-]/g, '');
await sandbox.exec(`command ${safe}`);
Use environment variables for secrets:
await sandbox.startProcess('node app.js', {
  env: { API_KEY: env.API_KEY }
});
Clean up temporary resources:
try {
  const sandbox = getSandbox(env.Sandbox, sessionId);
  await sandbox.exec('npm test');
} finally {
  await sandbox.destroy();
}
Related resources
Containers architecture - Underlying platform security
Sandbox lifecycle - Resource management

Session management
import { Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
Sessions are bash shell execution contexts within a sandbox. Think of them as terminal tabs in the same computer.
Sandbox = A user or task workspace
Session = A shell in that workspace
Sessions are useful for organizing work inside one sandbox. They are not a security boundary between users because sessions share the same filesystem and process space.
Default session
By default, every sandbox has a default session that maintains shell state between commands while the container is active:
const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
// These commands run in the default session
await sandbox.exec("cd /app");
await sandbox.exec("pwd");  // Output: /app
await sandbox.exec("export MY_VAR=hello");
await sandbox.exec("echo $MY_VAR");  // Output: hello
Working directory, environment variables, and exported variables carry over between commands. This state resets if the container restarts due to inactivity.
If you set 
enableDefaultSession: false when calling 
getSandbox(), operations without an explicit 
sessionId run in isolation instead of using the default session:
const sandbox = getSandbox(env.Sandbox, 'my-sandbox', {
  enableDefaultSession: false
});
await sandbox.exec("cd /app");
await sandbox.exec("pwd");  // Output: /workspace (cd was not inherited)
Without the default session, the second command does not inherit shell state from the first command. It is recommended that you always apply this setting as it will become the default in a future Sandbox SDK release. Create or retrieve an explicit session when you want commands to share shell state.
Automatic session creation
The container automatically creates sessions on first use. If you reference a non-existent session ID, the container creates it with default settings:
// This session does not exist yet
const result = await sandbox.exec('echo hello', { sessionId: 'new-session' });
// Container automatically creates 'new-session' with defaults:
// - cwd: '/workspace'
// - env: {} (empty)
This behavior is particularly relevant after deleting a session:
// Create and configure a session
const session = await sandbox.createSession({
  id: 'temp',
  env: { MY_VAR: 'value' }
});
// Delete the session
await sandbox.deleteSession('temp');
// Using the same session ID again works - auto-created with defaults
const result = await sandbox.exec('echo $MY_VAR', { sessionId: 'temp' });
// Output: (empty) - MY_VAR is not set in the freshly created session
This auto-creation means commands still run when they reference a non-existent session. However, custom configuration (environment variables, working directory) is lost after deletion.
Creating sessions
Create additional sessions for separate workflows in the same sandbox:
const buildSession = await sandbox.createSession({
  id: "build",
  env: { NODE_ENV: "production" },
  cwd: "/build"
});
const testSession = await sandbox.createSession({
  id: "test",
  env: { NODE_ENV: "test" },
  cwd: "/test"
});
// Different shell contexts
await buildSession.exec("npm run build");
await testSession.exec("npm test");
You can also set a default command timeout for all commands in a session:
const session = await sandbox.createSession({
  id: "ci",
  commandTimeoutMs: 30000 // 30s timeout for all commands
});
await session.exec("npm test"); // Times out after 30s if still running
Individual commands can override the session timeout with the 
timeout option on 
exec(). For more details, refer to the Sessions API and the execute commands guide.
What is scoped to a session
Each session has its own:
Shell environment:
await session1.exec("export MY_VAR=hello");
await session2.exec("echo $MY_VAR");  // Empty - different shell
Working directory:
await session1.exec("cd /workspace/project1");
await session2.exec("pwd");  // Different working directory
Environment variables (set via 
createSession options):
const session1 = await sandbox.createSession({
  env: { API_KEY: 'key-1' }
});
const session2 = await sandbox.createSession({
  env: { API_KEY: 'key-2' }
});
What is shared across sessions
All sessions in a sandbox share:
Filesystem:
await session1.writeFile('/workspace/file.txt', 'data');
await session2.readFile('/workspace/file.txt');  // Can read it
Processes:
await session1.startProcess('node server.js');
await session2.listProcesses();  // Sees the server
When to use sessions
Use sessions when:
You need separate shell state for one user's tasks
Running parallel operations with different environments
Keeping AI agent credentials separate from app runtime
Example - separate dev and runtime environments:
// Phase 1: AI agent writes code (with API keys)
const devSession = await sandbox.createSession({
  id: "dev",
  env: { ANTHROPIC_API_KEY: env.ANTHROPIC_API_KEY }
});
await devSession.exec('ai-tool "build a web server"');
// Phase 2: Run the code (without API keys)
const appSession = await sandbox.createSession({
  id: "app",
  env: { PORT: "3000" }
});
await appSession.exec("node server.js");
Use separate sandboxes when:
You need complete isolation for untrusted code
Different users need separate workspaces
User data must stay separated
Independent resource allocation is needed
Best practices
Session cleanup
Clean up temporary sessions to free resources while keeping the sandbox running:
try {
  const session = await sandbox.createSession({ id: 'temp' });
  await session.exec('command');
} finally {
  await sandbox.deleteSession('temp');
}
Default session cannot be deleted:
// This throws an error
await sandbox.deleteSession('default');
// Error: Cannot delete default session. Use sandbox.destroy() instead.
Filesystem scope
Sessions share the sandbox filesystem - file operations affect all sessions:
// Bad - affects all sessions
await session.exec('rm -rf /workspace/*');
// For user data or untrusted code, use a separate sandbox
const userSandbox = getSandbox(env.Sandbox, `user-${userId}`);
Related resources
Sandbox lifecycle - Understanding sandbox management
Sessions API - Complete session API reference

Terminal connections
import { Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/commands/open-a-terminal-in-the-browser/", title: "Open a terminal in the browser" }} />
Terminal connections let browser-based UIs interact directly with sandbox shells. Instead of executing discrete commands with 
exec(), a terminal connection opens a persistent, bidirectional channel to a bash shell — the same model as SSH or a local terminal emulator.
How terminal connections work
Terminal connections use WebSockets to stream raw bytes between a browser terminal (like xterm.js) and a pseudo-terminal (PTY) process running inside the sandbox container.
Browser (xterm.js) <-- WebSocket --> Worker <-- proxy --> Container PTY (bash)
The browser sends a WebSocket upgrade request to your Worker
Your Worker calls 
sandbox.terminal(request), which proxies the upgrade to the container
The container spawns a bash shell attached to a PTY
Raw bytes flow bidirectionally — keystrokes in, terminal output out
This is fundamentally different from 
exec():
exec() runs a single command to completion and returns the result
terminal() opens a persistent shell where users type commands interactively
Output buffering
The container buffers terminal output in a ring buffer. When a client disconnects and reconnects, the server replays buffered output so the terminal appears unchanged. This means:
Short network interruptions are invisible to users
Reconnected terminals show previous output without re-running commands
The buffer has a fixed size, so very old output may be lost
No client-side code is needed to handle buffering — the container manages it transparently.
Automatic reconnection
Network interruptions are common in browser-based applications. Terminal connections handle this through a combination of server-side buffering (described above) and client-side reconnection with exponential backoff.
The 
SandboxAddon for xterm.js implements this automatically. If you are building a custom client, you are responsible for your own reconnection logic — the server-side buffering works regardless of which client connects. Refer to the WebSocket protocol reference for details on the connection lifecycle.
Session-specific terminals
Each session can have its own terminal with independent shell state:
const devSession = await sandbox.createSession({
	id: "dev",
	cwd: "/workspace/frontend",
	env: { NODE_ENV: "development" },
});
const testSession = await sandbox.createSession({
	id: "test",
	cwd: "/workspace",
	env: { NODE_ENV: "test" },
});
// Each session's terminal has its own working directory,
// environment variables, and command history
Multiple browser clients can connect to the same session's terminal simultaneously. They all see the same shell output and can send input. Use this pattern for intentional collaboration inside one workspace, not to separate independent users.
WebSocket protocol
Terminal connections use binary WebSocket frames for terminal I/O (for performance) and JSON text frames for control and status messages (for structure). This keeps the data path fast while still allowing structured communication for operations like terminal resizing.
For the full protocol specification, including the connection lifecycle and message formats, refer to the Terminal API reference.
When to use terminals vs commands
Use case
Approach
Run a command and get the result
exec() or 
execStream()
Interactive shell for end users
terminal()
Long-running process with real-time output
startProcess() + 
streamProcessLogs()
Collaborative terminal sharing
terminal() with shared session
Related resources
Terminal API reference — Method signatures and types
Browser terminals — Step-by-step setup guide
Session management — How sessions work
Architecture — Overall SDK design

Dockerfile reference
import { Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
Customize the sandbox container image with your own packages, tools, and configurations by extending the base runtime image.
Base images
The Sandbox SDK provides multiple image variants. All except 
-musl are based on Ubuntu. Choose the one that fits your use case:
Image
Tag suffix
Use case
Default
(none)
Lean image for JavaScript/TypeScript workloads
Python
-python
Data science, ML, Python code execution
OpenCode
-opencode
AI coding agents with OpenCode CLI
musl
-musl
Minimal Alpine image with Git, curl, and bash
# Default - lean, no Python
FROM docker.io/cloudflare/sandbox:0.12.14
# Python - includes Python 3.11 + data science packages
FROM docker.io/cloudflare/sandbox:0.12.14-python
# OpenCode - includes OpenCode CLI for AI coding
FROM docker.io/cloudflare/sandbox:0.12.14-opencode
# musl - minimal Alpine image, no Node.js, Bun, or Python
FROM docker.io/cloudflare/sandbox:0.12.14-musl
:::caution[Version synchronization required]
Always match the Docker image version to your npm package version. If you are using 
@cloudflare/sandbox@0.12.14, use 
docker.io/cloudflare/sandbox:0.12.14 (or variant) as your base image.
Why this matters: The SDK automatically checks version compatibility on startup. Mismatched versions can cause features to break or behave unexpectedly. If versions don't match, you'll see warnings in your logs.
See Version compatibility for troubleshooting version mismatch warnings.
:::
Default image
The default image is optimized for JavaScript and TypeScript workloads:
Ubuntu 22.04 LTS base
Node.js 22 LTS with npm
Bun 1.x (JavaScript/TypeScript runtime)
System utilities: curl, wget, git, jq, zip, unzip, file, procps, ca-certificates
Python image
The 
-python variant includes everything in the default image plus:
Python 3.11 with pip and venv
Pre-installed packages: matplotlib, numpy, pandas, ipython
OpenCode image
The 
-opencode variant includes everything in the default image plus:
OpenCode CLI for AI-powered coding agents
musl image
The 
-musl variant is a minimal image:
Alpine Linux 3.21 base
Git, curl, and bash
No Node.js, Bun, or Python
Its sandbox binary is built for musl, so it also runs in other Alpine-based images. Docker in Docker copies it into 
docker:dind.
Creating a custom image
Create a 
Dockerfile in your project root:
FROM docker.io/cloudflare/sandbox:0.12.14-python
# Install additional Python packages
RUN pip install --no-cache-dir \
    scikit-learn==1.3.0 \
    tensorflow==2.13.0 \
    transformers==4.30.0
# Install Node.js packages globally
RUN npm install -g typescript ts-node prettier
# Install system packages
RUN apt-get update && apt-get install -y \
    postgresql-client \
    redis-tools \
    && rm -rf /var/lib/apt/lists/*
Update 
wrangler.jsonc to reference your Dockerfile:
{
	"containers": [
		{
			"class_name": "Sandbox",
			"image": "./Dockerfile",
		},
	],
}
When you run 
wrangler dev or 
wrangler deploy, Wrangler automatically builds your Docker image and pushes it to Cloudflare's container registry. You don't need to manually build or publish images.
Using arbitrary base images
You can add sandbox capabilities to any Docker image using the standalone binary. This approach lets you use your existing images without depending on the Cloudflare base images:
FROM your-custom-image:tag
# Copy the sandbox binary from the official image
COPY --from=docker.io/cloudflare/sandbox:0.12.14 /container-server/sandbox /sandbox
ENTRYPOINT ["/sandbox"]
The 
/sandbox binary starts the HTTP API server that enables SDK communication. You can optionally run your own startup command:
FROM node:22-slim
COPY --from=docker.io/cloudflare/sandbox:0.12.14 /container-server/sandbox /sandbox
# Copy your application
COPY . /app
WORKDIR /app
ENTRYPOINT ["/sandbox"]
CMD ["node", "server.js"]
When using 
CMD, the sandbox binary runs your command as a child process with proper signal forwarding.
Custom startup scripts
For more complex startup sequences, create a custom startup script:
FROM docker.io/cloudflare/sandbox:0.12.14-python
COPY my-app.js /workspace/my-app.js
COPY startup.sh /workspace/startup.sh
RUN chmod +x /workspace/startup.sh
CMD ["/workspace/startup.sh"]
The base image already sets the correct 
ENTRYPOINT, so you only need to provide a 
CMD. The sandbox binary starts the HTTP API server, then spawns your 
CMD as a child process with proper signal forwarding.
#!/bin/bash
# Start your services in the background
node /workspace/my-app.js &
# Start additional services
redis-server --daemonize yes
until redis-cli ping; do sleep 1; done
# Keep the script running (the sandbox binary handles the API server)
wait
:::note[Legacy startup scripts]
If you have existing startup scripts that end with 
exec bun /container-server/dist/index.js, they will continue to work for backwards compatibility. However, we recommend migrating to the new approach using 
CMD for your startup script. Do not override 
ENTRYPOINT when extending the base image.
:::
Related resources
Image Management - Building and pushing images to Cloudflare's registry
Wrangler configuration - Using custom images in wrangler.jsonc
Docker documentation - Complete Dockerfile syntax
Container concepts - Understanding the runtime environment

Environment variables
import { WranglerConfig, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
Pass configuration, secrets, and runtime settings to your sandboxes using environment variables.
SDK configuration variables
These environment variables configure how the Sandbox SDK behaves. Set these as Worker 
vars in your 
wrangler.jsonc file. The SDK reads them from the Worker's environment bindings.
SANDBOX_TRANSPORT
Type
"http" | 
"websocket" | 
"rpc"
Default
"http"
Controls the transport protocol for SDK-to-container communication. RPC transport multiplexes all operations over a single persistent connection, avoiding subrequest limits when performing many SDK operations per request.
```jsonc
{
	"vars": {
		"SANDBOX_TRANSPORT": "rpc"
	}
}
```
For a complete guide including valid transport modes, performance considerations, and migration instructions, refer to Transport modes.
COMMAND_TIMEOUT_MS
Type
number (milliseconds)
Default
None (no timeout)
Sets a global default timeout for every 
exec() call. When set, any command that exceeds this duration raises an error on the caller side and closes the connection.
Per-command 
timeout on 
exec() and session-level 
commandTimeoutMs on 
createSession() both override this value. For more details on timeout precedence, refer to Execute commands - Timeouts.
```jsonc
{
	"vars": {
		"COMMAND_TIMEOUT_MS": "30000"
	}
}
```
:::note
A timeout does not kill the underlying process. It only terminates the connection to the caller. The process continues running until the session is deleted or the sandbox is destroyed.
:::
Three ways to set environment variables
The Sandbox SDK provides three methods for setting environment variables, each suited for different use cases:
1. Sandbox-level with setEnvVars()
Set environment variables globally for all commands in the sandbox:
const sandbox = getSandbox(env.Sandbox, "my-sandbox");
// Set once, available for all subsequent commands
await sandbox.setEnvVars({
	DATABASE_URL: env.DATABASE_URL,
	API_KEY: env.API_KEY,
});
await sandbox.exec("python migrate.py"); // Has DATABASE_URL and API_KEY
await sandbox.exec("python seed.py"); // Has DATABASE_URL and API_KEY
// Unset variables by passing undefined
await sandbox.setEnvVars({
	API_KEY: "new-key", // Updates API_KEY
	OLD_SECRET: undefined, // Unsets OLD_SECRET
});
Use when: You need the same environment variables for multiple commands.
Unsetting variables: Pass 
undefined or 
null to unset environment variables:
await sandbox.setEnvVars({
	API_KEY: 'new-key',     // Sets API_KEY
	OLD_SECRET: undefined,  // Unsets OLD_SECRET
	DEBUG_MODE: null        // Unsets DEBUG_MODE
});
2. Per-command with exec() options
Pass environment variables for a specific command:
await sandbox.exec("node app.js", {
	env: {
		NODE_ENV: "production",
		PORT: "3000",
	},
});
// Also works with startProcess()
await sandbox.startProcess("python server.py", {
	env: {
		DATABASE_URL: env.DATABASE_URL,
	},
});
Use when: You need different environment variables for different commands, or want to override sandbox-level variables.
:::note
Per-command environment variables with 
undefined values are skipped (treated as "not configured"), unlike 
setEnvVars() where 
undefined explicitly unsets a variable.
:::
3. Session-level with createSession()
Create an isolated session with its own environment variables:
const session = await sandbox.createSession({
	env: {
		DATABASE_URL: env.DATABASE_URL,
		SECRET_KEY: env.SECRET_KEY,
	},
});
// All commands in this session have these vars
await session.exec("python migrate.py");
await session.exec("python seed.py");
Use when: You need isolated execution contexts with different environment variables running concurrently.
Unsetting environment variables
The Sandbox SDK supports unsetting environment variables by passing 
undefined or 
null values. This enables idiomatic JavaScript patterns for managing configuration:
await sandbox.setEnvVars({
	// Set new values
	API_KEY: 'new-key',
	DATABASE_URL: env.DATABASE_URL,
	// Unset variables (removes them from the environment)
	OLD_API_KEY: undefined,
	TEMP_TOKEN: null
});
Before this change: Passing 
undefined values would throw a runtime error.
After this change: 
undefined and 
null values run 
unset VARIABLE_NAME in the shell.
Use cases for unsetting
Remove sensitive data after use:
// Use a temporary token
await sandbox.setEnvVars({ TEMP_TOKEN: 'abc123' });
await sandbox.exec('curl -H "Authorization: $TEMP_TOKEN" api.example.com');
// Clean up the token
await sandbox.setEnvVars({ TEMP_TOKEN: undefined });
Conditional environment setup:
await sandbox.setEnvVars({
	API_KEY: env.API_KEY,
	DEBUG_MODE: env.NODE_ENV === 'development' ? 'true' : undefined,
	PROFILING: env.ENABLE_PROFILING ? 'true' : undefined
});
Reset to system defaults:
// Unset to fall back to container's default NODE_ENV
await sandbox.setEnvVars({ NODE_ENV: undefined });
Common patterns
Pass Worker secrets to sandbox
Securely pass secrets from your Worker to the sandbox. First, set secrets using Wrangler:
wrangler secret put OPENAI_API_KEY
wrangler secret put DATABASE_URL
Then pass them to your sandbox:
import { getSandbox } from "@cloudflare/sandbox";
export { Sandbox } from "@cloudflare/sandbox";
interface Env {
	Sandbox: DurableObjectNamespace<Sandbox>;
	OPENAI_API_KEY: string;
	DATABASE_URL: string;
}
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const sandbox = getSandbox(env.Sandbox, "user-sandbox");
		// Option 1: Set globally for all commands
		await sandbox.setEnvVars({
			OPENAI_API_KEY: env.OPENAI_API_KEY,
			DATABASE_URL: env.DATABASE_URL,
		});
		await sandbox.exec("python analyze.py");
		// Option 2: Pass per-command
		await sandbox.exec("python analyze.py", {
			env: {
				OPENAI_API_KEY: env.OPENAI_API_KEY,
			},
		});
		return Response.json({ success: true });
	},
};
Combine default and specific variables
const defaults = { NODE_ENV: "production", LOG_LEVEL: "info" };
await sandbox.exec("npm start", {
	env: { ...defaults, PORT: "3000", API_KEY: env.API_KEY },
});
Multiple isolated sessions
Run different tasks with different environment variables concurrently:
// Production database session
const prodSession = await sandbox.createSession({
	env: { DATABASE_URL: env.PROD_DATABASE_URL },
});
// Staging database session
const stagingSession = await sandbox.createSession({
	env: { DATABASE_URL: env.STAGING_DATABASE_URL },
});
// Run migrations on both concurrently
await Promise.all([
	prodSession.exec("python migrate.py"),
	stagingSession.exec("python migrate.py"),
]);
Configure transport mode
Set 
SANDBOX_TRANSPORT in your Worker's 
vars to switch between HTTP, WebSocket, and RPC transport. For details on when and how to configure each transport, refer to Transport modes.
Bucket mounting credentials
When mounting S3-compatible object storage, the SDK uses s3fs-fuse under the hood, which requires AWS-style credentials. For R2, generate API tokens from the Cloudflare dashboard and provide them using AWS environment variable names:
Get R2 API tokens:
Go to R2 > Overview in the Cloudflare dashboard
Select Manage R2 API Tokens
Create a token with Object Read & Write permissions
Copy the Access Key ID and Secret Access Key
Set credentials as Worker secrets:
wrangler secret put AWS_ACCESS_KEY_ID
# Paste your R2 Access Key ID
wrangler secret put AWS_SECRET_ACCESS_KEY
# Paste your R2 Secret Access Key
Mount buckets with automatic credential detection:
import { getSandbox } from "@cloudflare/sandbox";
export { Sandbox } from "@cloudflare/sandbox";
interface Env {
	Sandbox: DurableObjectNamespace<Sandbox>;
	AWS_ACCESS_KEY_ID: string;
	AWS_SECRET_ACCESS_KEY: string;
}
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const sandbox = getSandbox(env.Sandbox, "data-processor");
		// Credentials automatically detected from environment
		await sandbox.mountBucket("my-r2-bucket", "/data", {
			endpoint: "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com",
		});
		// Access mounted bucket using standard file operations
		await sandbox.exec("python", { args: ["process.py", "/data/input.csv"] });
		return Response.json({ success: true });
	},
};
The SDK automatically detects 
AWS_ACCESS_KEY_ID and 
AWS_SECRET_ACCESS_KEY from your Worker's environment when you call 
mountBucket() without explicit credentials.
Pass credentials explicitly (if using custom secret names):
await sandbox.mountBucket("my-r2-bucket", "/data", {
	endpoint: "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com",
	credentials: {
		accessKeyId: env.R2_ACCESS_KEY_ID,
		secretAccessKey: env.R2_SECRET_ACCESS_KEY,
	},
});
:::note[AWS nomenclature for R2]
The SDK uses AWS-style credential names (
AWS_ACCESS_KEY_ID, 
AWS_SECRET_ACCESS_KEY) because bucket mounting is powered by s3fs-fuse, which expects S3-compatible credentials. R2's API tokens work with this format since R2 implements the S3 API.
:::
See Mount buckets guide for complete bucket mounting documentation.
Environment variable precedence
When the same variable is set at multiple levels, the most specific level takes precedence:
Command-level (highest) - Passed to 
exec() or 
startProcess() options
Sandbox or session-level - Set with 
setEnvVars()
Container default - Built into the Docker image with 
ENV
System default (lowest) - Operating system defaults
Example:
// In Dockerfile: ENV NODE_ENV=development
// Sandbox-level
await sandbox.setEnvVars({ NODE_ENV: "staging" });
// Command-level overrides all
await sandbox.exec("node app.js", {
	env: { NODE_ENV: "production" }, // This wins
});
Related resources
Transport modes - Configure HTTP, WebSocket, and RPC transport
Wrangler configuration - Setting Worker-level environment
Secrets - Managing sensitive data
Sessions API - Session-level environment variables
Security model - Understanding data isolation
Handle outbound traffic - Keep credentials out of the sandbox entirely using outbound handlers

Configuration
import { LinkTitleCard, CardGrid, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
Configure your Sandbox SDK deployment with Wrangler, customize container images, and manage environment variables.
<LinkTitleCard
title="Wrangler configuration"
href="/sandbox/sdk/configuration/wrangler/"
icon="puzzle"
Configure Durable Objects bindings, container images, and Worker settings in
wrangler.jsonc.
<LinkTitleCard
title="Dockerfile reference"
href="/sandbox/sdk/configuration/dockerfile/"
icon="seti:docker"
Customize the sandbox container image with your own packages, tools, and
configurations.
<LinkTitleCard
title="Environment variables"
href="/sandbox/sdk/configuration/environment-variables/"
icon="seti:powershell"
Pass configuration and secrets to your sandboxes using environment variables.
<LinkTitleCard
title="Transport modes"
href="/sandbox/sdk/configuration/transport/"
icon="connection"
Configure HTTP or RPC transport to optimize communication and avoid subrequest limits.
<LinkTitleCard
title="Sandbox options"
href="/sandbox/sdk/configuration/sandbox-options/"
icon="setting"
Configure sandbox behavior with options like `keepAlive` for long-running processes.
Related resources
Get Started guide - Initial setup walkthrough
Wrangler documentation - Complete Wrangler reference
Docker documentation - Dockerfile syntax
Security model - Understanding environment isolation

Sandbox options
import { TypeScriptExample, WranglerConfig, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
Configure sandbox behavior by passing options when creating a sandbox instance with 
getSandbox().
Available options
import { getSandbox } from '@cloudflare/sandbox';
const sandbox = getSandbox(binding, sandboxId, options?: SandboxOptions);
enableDefaultSession
Type: 
boolean
Default: 
true
Controls what happens when you call sandbox methods without an explicit 
sessionId. When 
true, implicit operations use the sandbox's default session and preserve shell state between calls. When 
false, implicit operations run in isolation and do not inherit shell state from prior calls unless you explicitly target a session.
Use 
enableDefaultSession: true for interactive or stateful workflows where commands should share working directory and exported variables. Use 
enableDefaultSession: false for stateless request handling where one call should not affect the next one. It is recommended to set this to 
false — default session support will be removed in a future version of the Sandbox SDK, and using 
createSession() explicitly is the preferred pattern going forward.
```ts
// Default behavior: implicit operations use the default session
const statefulSandbox = getSandbox(env.Sandbox, 'user-123');
await statefulSandbox.exec('cd /workspace/app');
const statefulResult = await statefulSandbox.exec('pwd');
// statefulResult.stdout: "/workspace/app"
// The second exec inherited the working directory from the first.
// Sessionless behavior: implicit operations do not share shell state
const statelessSandbox = getSandbox(env.Sandbox, 'api-worker', {
enableDefaultSession: false
});
await statelessSandbox.exec('cd /workspace/app');
const statelessResult = await statelessSandbox.exec('pwd');
// statelessResult.stdout: "/workspace"
// The second exec did not inherit shell state from the first.
</TypeScriptExample>
### keepAlive
**Type**: `boolean`
**Default**: `false`
Keep the container alive indefinitely by preventing automatic shutdown. When `true`, the container automatically sends heartbeat pings every 30 seconds to prevent eviction and will never auto-timeout.
**How it works**: The sandbox automatically schedules lightweight ping requests to the container every 30 seconds. This prevents the container from being evicted due to inactivity while minimizing resource overhead. You can also enable/disable keepAlive dynamically using [`setKeepAlive()`](/sandbox/sdk/api/lifecycle/#setkeepalive).
The `keepAlive` flag persists across Durable Object hibernation and wakeup cycles. Once enabled, you do not need to re-set it after the sandbox wakes from hibernation.
<TypeScriptExample>
```ts
// For long-running processes that need the container to stay alive
const sandbox = getSandbox(env.Sandbox, 'user-123', {
  keepAlive: true
});
// Run your long-running process
await sandbox.startProcess('python long_running_script.py');
// Important: Must explicitly destroy when done
try {
  // Your work here
} finally {
  await sandbox.destroy(); // Required to prevent containers running indefinitely
}
:::caution[Resource management with keepAlive]
When 
keepAlive: true is set, containers automatically send heartbeat pings to prevent eviction and will not automatically timeout. They must be explicitly destroyed using 
destroy() or disabled with 
setKeepAlive(false) to prevent containers running indefinitely and counting toward your account limits.
:::
sleepAfter
Type: 
string | number
Default: 
"10m" (10 minutes)
Duration of inactivity before the sandbox automatically sleeps. Accepts duration strings (
"30s", 
"5m", 
"1h") or numbers (seconds).
:::note[Bug fix in v0.2.17]
Prior to v0.2.17, the 
sleepAfter option passed to 
getSandbox() was ignored due to a timing issue. The option is now properly applied when creating sandbox instances.
:::
```ts
// Sleep after 30 seconds of inactivity
const sandbox = getSandbox(env.Sandbox, 'user-123', {
  sleepAfter: '30s'
});
// Sleep after 5 minutes (using number)
const sandbox2 = getSandbox(env.Sandbox, 'user-456', {
sleepAfter: 300  // 300 seconds = 5 minutes
});
</TypeScriptExample>
:::note[Ignored when keepAlive is true]
When `keepAlive: true` is set, `sleepAfter` is ignored and the sandbox never sleeps automatically.
:::
### containerTimeouts
**Type**: `object`
Configure timeouts for container startup operations.
<TypeScriptExample>
```ts
// Extended startup with custom Dockerfile work
// (installing packages, starting services before SDK)
const sandbox = getSandbox(env.Sandbox, 'data-processor', {
  containerTimeouts: {
    portReadyTimeoutMS: 180_000  // 3 minutes for startup work
  }
});
// Wait longer during traffic spikes
const sandbox2 = getSandbox(env.Sandbox, 'user-env', {
  containerTimeouts: {
    instanceGetTimeoutMS: 60_000   // 1 minute for provisioning
  }
});
Available timeout options:
instanceGetTimeoutMS - How long to wait for Cloudflare to provision a new container instance. Increase during traffic spikes when many containers provision simultaneously. Default: 
30000 (30 seconds)
portReadyTimeoutMS - How long to wait for the sandbox API to become ready. Increase if you extend the base Dockerfile with custom startup work (installing packages, starting services). Default: 
90000 (90 seconds)
Environment variable overrides:
SANDBOX_INSTANCE_TIMEOUT_MS - Override 
instanceGetTimeoutMS
SANDBOX_PORT_TIMEOUT_MS - Override 
portReadyTimeoutMS
Precedence: 
options > 
env vars > SDK defaults
Logging
Type: Environment variables
Control SDK logging for debugging and monitoring. Set these in your Worker's 
wrangler.jsonc file.
Available options:
SANDBOX_LOG_LEVEL - Minimum log level: 
debug, 
info, 
warn, 
error. Default: 
info
SANDBOX_LOG_FORMAT - Output format: 
json, 
pretty. Default: 
json
```jsonc
{
	"vars": {
		"SANDBOX_LOG_LEVEL": "debug",
		"SANDBOX_LOG_FORMAT": "pretty"
	}
}
```
:::note[Read at startup]
Logging configuration is read when your Worker starts and cannot be changed at runtime. Changes require redeploying your Worker.
:::
Use 
debug + 
pretty for local development. Use 
info or 
warn + 
json for production (structured logging).
normalizeId
Type: 
boolean
Default: 
false (will become 
true in a future version)
Lowercase sandbox IDs when creating sandboxes. When 
true, the ID you provide is lowercased before creating the Durable Object (e.g., "MyProject-123" → "myproject-123").
Why this matters: Preview URLs extract the sandbox ID from the hostname, which is always lowercase due to DNS case-insensitivity. Without normalization, a sandbox created with "MyProject-123" becomes unreachable via preview URL because the URL routing looks for "myproject-123" (different Durable Object).
```ts
// Without normalization (default)
const sandbox1 = getSandbox(env.Sandbox, 'MyProject-123');
// Creates Durable Object with ID: "MyProject-123"
// Preview URL: 8000-myproject-123.example.com
// Problem: URL routes to "myproject-123" (different DO)
// With normalization
const sandbox2 = getSandbox(env.Sandbox, 'MyProject-123', {
normalizeId: true
});
// Creates Durable Object with ID: "myproject-123"
// Preview URL: 8000-myproject-123.example.com
// Works: URL routes to "myproject-123" (same DO)
</TypeScriptExample>
:::caution[Different normalizeId values = different sandboxes]
`getSandbox(ns, 'MyProject-123')` and `getSandbox(ns, 'MyProject-123', { normalizeId: true })` create two separate Durable Objects. If you have existing sandboxes with uppercase IDs, enabling normalization creates new sandboxes—you won't access the old ones.
:::
:::note[Future default]
In a future SDK version, `normalizeId` will default to `true`. All sandbox IDs will be lowercase regardless of input casing. Use lowercase IDs now or explicitly set `normalizeId: true` to prepare for this change.
:::
## When to use normalizeId
Use `normalizeId: true` when:
- **Using preview URLs** - Required for port exposure if your IDs contain uppercase letters
- **New projects** - Either enable this option OR use lowercase IDs from the start (both work)
- **Migrating existing code** - Create new sandboxes with this enabled; old uppercase sandboxes will eventually be destroyed (explicitly or after timeout)
**Best practice**: Use lowercase IDs from the start (`'my-project-123'` instead of `'MyProject-123'`).
## When to use sleepAfter
Use custom `sleepAfter` values to:
- **Reduce costs** - Shorter timeouts (e.g., `"1m"`) for infrequent workloads
- **Extend availability** - Longer timeouts (e.g., `"30m"`) for interactive workflows
- **Balance performance** - Fine-tune based on your application's usage patterns
The default 10-minute timeout works well for most applications. Adjust based on your needs.
## When to use keepAlive
Use `keepAlive: true` for:
- **Long-running builds** - CI/CD pipelines that may have idle periods between steps
- **Batch processing** - Jobs that process data in waves with gaps between batches
- **Monitoring tasks** - Processes that periodically check external services
- **Interactive sessions** - User-driven workflows where the container should remain available
With `keepAlive`, containers send automatic heartbeat pings every 30 seconds to prevent eviction and never sleep automatically. Use for scenarios where you control the lifecycle explicitly.
## Related resources
- [Expose services guide](/sandbox/sdk/guides/expose-services/) - Using `normalizeId` with preview URLs
- [Preview URLs concept](/sandbox/sdk/concepts/preview-urls/) - Understanding DNS case-insensitivity
- [Background processes guide](/sandbox/sdk/guides/background-processes/) - Using `keepAlive` with long-running processes
- [Lifecycle API](/sandbox/sdk/api/lifecycle/) - Create and manage sandboxes with `setKeepAlive()`
- [Sandboxes concept](/sandbox/sdk/concepts/sandboxes/) - Understanding sandbox lifecycle

Transport modes
import { WranglerConfig, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
Configure how the Sandbox SDK communicates with containers using transport modes.
Overview
The Sandbox SDK supports three transport modes for communication between the Durable Object and the container:
HTTP transport (default) - Each SDK operation makes a separate HTTP request to the container.
NEW: RPC transport - All SDK operations are multiplexed over a single persistent WebSocket connection. Will replace HTTP as the default transport in future. Available since 0.9.1.
Deprecated: WebSocket transport - All SDK operations are multiplexed over a single persistent WebSocket. Superseded by RPC transport which uses an improved protocol.
When to use RPC transport
Use the RPC transport when your Worker or Durable Object makes many SDK operations per request. This avoids hitting subrequest limits.
Subrequest limits
Cloudflare Workers have subrequest limits that apply when making requests to external services, including container API calls:
Workers Free: 50 subrequests per request
Workers Paid: 1,000 subrequests per request
With HTTP transport (default), each SDK operation (
exec(), 
readFile(), 
writeFile(), etc.) consumes one subrequest. Applications that perform many sandbox operations in a single request can hit these limits.
How RPC transport helps
RPC transport establishes a single persistent connection to the container and multiplexes all SDK operations over it. The WebSocket upgrade counts as one subrequest regardless of how many operations you perform afterwards.
Example with HTTP transport (4 subrequests):
await sandbox.exec("python setup.py");
await sandbox.writeFile("/app/config.json", config);
await sandbox.exec("python process.py");
const result = await sandbox.readFile("/app/output.txt");
Same code with RPC transport (1 subrequest):
// Identical code - transport is configured via environment variable
await sandbox.exec("python setup.py");
await sandbox.writeFile("/app/config.json", config);
await sandbox.exec("python process.py");
const result = await sandbox.readFile("/app/output.txt");
RPC transport also removes the 32 MiB limitation that the HTTP transport has. Pass a 
ReadableStream instance to the 
writeFile() method.
const req = await fetch("https://example.com/archive.tar.gz");
await sandbox.writeFile("/archive.tar.gz", req.body);
Configuration
Set the 
SANDBOX_TRANSPORT environment variable in your Worker's configuration. The SDK reads this from the Worker environment bindings (not from inside the container).
HTTP transport (default)
HTTP transport is the default and requires no additional configuration.
RPC transport
Enable RPC transport by adding 
SANDBOX_TRANSPORT to your Worker's 
vars:
```jsonc
{
	"name": "my-sandbox-worker",
	"main": "src/index.ts",
	"upload_source_maps": true,
	"compatibility_date": "$today",
	"vars": {
		"SANDBOX_TRANSPORT": "rpc"
	},
	"containers": [
		{
			"class_name": "Sandbox",
			"image": "./Dockerfile",
		},
	],
	"durable_objects": {
		"bindings": [
			{
				"class_name": "Sandbox",
				"name": "Sandbox",
			},
		],
	},
}
```
No application code changes are needed. The SDK automatically uses the configured transport for all operations.
Transport behavior
Connection lifecycle
HTTP transport:
Creates a new HTTP request for each SDK operation
No persistent connection
Each request is independent and stateless
RPC transport:
Establishes a WebSocket connection on the first SDK operation
Maintains the persistent connection for all subsequent operations
Connection is closed when the sandbox sleeps or is evicted
Automatically reconnects if the connection drops
Streaming support
All transports support streaming operations (like 
exec() with real-time output):
HTTP transport - Uses Server-Sent Events (SSE)
RPC transport - Uses WebSocket streaming messages
Your code remains identical regardless of transport mode.
Error handling
All transports provide identical error handling behavior. The SDK automatically retries on transient errors (like 503 responses) with exponential backoff.
WebSocket-specific behavior:
Connection failures trigger automatic reconnection
The SDK transparently handles WebSocket disconnections
In-flight operations are not lost during reconnection
Choosing a transport
We expect the RPC transport to replace the default HTTP transport in a future release. New functionality may support only the RPC transport. Switching to use it now will avoid migrations in the future.
Migration guide
Switching between transports requires no code changes.
Switch from HTTP to RPC
:::caution[Requires staged deployment]
Using the 
rpc transport requires version 0.9.1 or newer. If you are using an older version of the Sandbox SDK upgrade and deploy your application with the newer 
@cloudflare/sandbox and image first. Otherwise there will be issues with newer SDK clients attempting to connect to older sandboxes that do not support the new transport.
:::
Add 
SANDBOX_TRANSPORT to your 
wrangler.jsonc:
```jsonc
{
	"vars": {
		"SANDBOX_TRANSPORT": "rpc"
	},
}
```
Then deploy:
npx wrangler deploy
Switch from RPC to HTTP
Remove the 
SANDBOX_TRANSPORT variable (or set it to 
"http"):
```jsonc
{
	"vars": {
		// Remove SANDBOX_TRANSPORT or set to "http"
	},
}
```
Switch from deprecated WebSocket to RPC
:::caution[Requires staged deployment]
Using the 
rpc transport requires version 0.9.1 or newer. If you are using an older version of the Sandbox SDK upgrade and deploy your application with the newer 
@cloudflare/sandbox and image first. Otherwise there will be issues with newer SDK clients attempting to connect to older sandboxes that do not support the new transport.
:::
Set the 
SANDBOX_TRANSPORT variable to 
"rpc":
```jsonc
{
	"vars": {
		"SANDBOX_TRANSPORT": "rpc"
	},
}
```
Related resources
Wrangler configuration - Complete Worker configuration
Environment variables - Passing configuration to sandboxes
Workers subrequest limits - Understanding subrequest limits
Architecture - How Sandbox SDK components communicate

Wrangler configuration
import { WranglerConfig, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
Minimal configuration
The minimum required configuration for using Sandbox SDK:
```jsonc
{
	"name": "my-sandbox-worker",
	"main": "src/index.ts",
	"upload_source_maps": true,
	"compatibility_date": "$today",
	"compatibility_flags": ["nodejs_compat"],
	"containers": [
		{
			"class_name": "Sandbox",
			"image": "./Dockerfile",
		},
	],
	"durable_objects": {
		"bindings": [
			{
				"class_name": "Sandbox",
				"name": "Sandbox",
			},
		],
	},
	"migrations": [
		{
			"new_sqlite_classes": ["Sandbox"],
			"tag": "v1",
		},
	],
}
```
Required settings
The Sandbox SDK is built on Cloudflare Containers. Your configuration requires three sections:
containers - Define the container image (your runtime environment)
durable_objects.bindings - Bind the Sandbox Durable Object to your Worker
migrations - Initialize the Durable Object class
The minimal configuration shown above includes all required settings. For detailed configuration options, refer to the Containers configuration documentation.
Backup storage
To use the backup and restore API, you need an R2 bucket binding and presigned URL credentials. The container uploads and downloads backup archives directly to/from R2 using presigned URLs, which requires R2 API token credentials.
1. Create the R2 bucket
npx wrangler r2 bucket create my-backup-bucket
2. Add the binding and environment variables
```jsonc
{
	"vars": {
		"BACKUP_BUCKET_NAME": "my-backup-bucket",
		"CLOUDFLARE_ACCOUNT_ID": "",
	},
	"r2_buckets": [
		{
			"binding": "BACKUP_BUCKET",
			"bucket_name": "my-backup-bucket",
		},
	],
}
```
3. Set R2 API credentials as secrets
npx wrangler secret put R2_ACCESS_KEY_ID
npx wrangler secret put R2_SECRET_ACCESS_KEY
Create an R2 API token in the Cloudflare dashboard under R2 > Overview > Manage R2 API Tokens. The token needs Object Read & Write permissions for your backup bucket.
The SDK uses these credentials to generate presigned URLs that allow the container to transfer backup archives directly to and from R2. For a complete setup walkthrough, refer to the backup and restore guide.
Troubleshooting
Binding not found
Error: 
TypeError: env.Sandbox is undefined
Solution: Ensure your 
wrangler.jsonc includes the Durable Objects binding:
```jsonc
{
	"durable_objects": {
		"bindings": [
			{
				"class_name": "Sandbox",
				"name": "Sandbox",
			},
		],
	},
}
```
Missing migrations
Error: Durable Object not initialized
Solution: Add migrations for the Sandbox class:
```jsonc
{
	"migrations": [
		{
			"new_sqlite_classes": ["Sandbox"],
			"tag": "v1",
		},
	],
}
```
Related resources
Deploy a Sandbox application - Deploy and keep package and image aligned
Deploy Containers - Containers deploy path
Transport modes - Configure HTTP, WebSocket, and RPC transport
Wrangler documentation - Complete Wrangler reference
Durable Objects setup - DO-specific configuration
Dockerfile reference - Custom container images
Environment variables - Passing configuration to sandboxes
Get Started guide - Initial setup walkthrough

Run background processes
import { TypeScriptExample, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
This guide shows you how to start, monitor, and manage long-running background processes in the sandbox.
When to use background processes
Use 
startProcess() instead of 
exec() when:
Running web servers - HTTP servers, APIs, WebSocket servers
Long-running services - Database servers, caches, message queues
Development servers - Hot-reloading dev servers, watch modes
Continuous monitoring - Log watchers, health checkers
Parallel execution - Multiple services running simultaneously
:::note
For one-time commands, builds, or scripts that complete and exit, use 
exec() instead. See the Execute commands guide.
:::
Start a background process
```
import { getSandbox } from '@cloudflare/sandbox';
const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
// Start a web server
const server = await sandbox.startProcess('python -m http.server 8000');
console.log('Server started');
console.log('Process ID:', server.id);
console.log('PID:', server.pid);
console.log('Status:', server.status); // 'running'
// Process runs in background - your code continues
</TypeScriptExample>
## Configure process environment
Set working directory and environment variables:
<TypeScriptExample>
const process = await sandbox.startProcess('node server.js', {
cwd: '/workspace/api',
env: {
NODE_ENV: 'production',
PORT: '8080',
API_KEY: env.API_KEY,
DATABASE_URL: env.DATABASE_URL
}
});
console.log('API server started');
</TypeScriptExample>
## Monitor process status
List and check running processes:
<TypeScriptExample>
const processes = await sandbox.listProcesses();
console.log(
Running ${processes.length} processes:);
for (const proc of processes) {
console.log(
${proc.id}: ${proc.command} (${proc.status}));
}
// Check if specific process is running
const isRunning = processes.some(p => p.id === processId && p.status === 'running');
</TypeScriptExample>
## Wait for process readiness
Wait for a process to be ready before proceeding:
<TypeScriptExample>
const server = await sandbox.startProcess('node server.js');
// Wait for server to respond on port 3000
await server.waitForPort(3000);
console.log('Server is ready');
</TypeScriptExample>
Or wait for specific log patterns:
<TypeScriptExample>
const server = await sandbox.startProcess('node server.js');
// Wait for log message
const result = await server.waitForLog('Server listening');
console.log('Server is ready:', result.line);
</TypeScriptExample>
## Monitor process logs
Stream logs in real-time:
<TypeScriptExample>
import { parseSSEStream, type LogEvent } from '@cloudflare/sandbox';
const server = await sandbox.startProcess('node server.js');
// Stream logs
const logStream = await sandbox.streamProcessLogs(server.id);
for await (const log of parseSSEStream(logStream)) {
console.log(log.data);
}
</TypeScriptExample>
Or get accumulated logs:
<TypeScriptExample>
const logs = await sandbox.getProcessLogs(server.id);
console.log('Logs:', logs);
</TypeScriptExample>
## Stop processes
Stop background processes and their children:
<TypeScriptExample>
// Stop specific process (terminates entire process tree)
await sandbox.killProcess(server.id);
// Force kill if needed
await sandbox.killProcess(server.id, 'SIGKILL');
// Stop all processes
await sandbox.killAllProcesses();
</TypeScriptExample>
`killProcess()` terminates the specified process and all child processes it spawned. This ensures that processes running in the background do not leave orphaned child processes when terminated.
For example, if your process spawns multiple worker processes or background tasks, `killProcess()` will clean up the entire process tree:
<TypeScriptExample>
// This script spawns multiple child processes
const batch = await sandbox.startProcess(
'bash -c "process1 & process2 & process3 & wait"'
);
// killProcess() terminates the bash process AND all three child processes
await sandbox.killProcess(batch.id);
</TypeScriptExample>
## Run multiple processes
Start services in sequence, waiting for dependencies:
<TypeScriptExample>
// Start database first
const db = await sandbox.startProcess('redis-server');
// Wait for database to be ready
await db.waitForPort(6379, { mode: 'tcp' });
// Now start API server (depends on database)
const api = await sandbox.startProcess('node api-server.js', {
env: { DATABASE_URL: 'redis://localhost:6379' }
});
// Wait for API to be ready
await api.waitForPort(8080, { path: '/health' });
console.log('All services running');
</TypeScriptExample>
## Keep containers alive for long-running processes
By default, containers automatically shut down after 10 minutes of inactivity. For long-running processes that may have idle periods (like CI/CD pipelines, batch jobs, or monitoring tasks), use the [`keepAlive` option](/sandbox/sdk/configuration/sandbox-options/#keepalive):
<TypeScriptExample>
```ts
import { getSandbox, parseSSEStream, type LogEvent } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // Enable keepAlive for long-running processes
    const sandbox = getSandbox(env.Sandbox, 'build-job-123', {
      keepAlive: true
    });
    try {
      // Start a long-running build process
      const build = await sandbox.startProcess('npm run build:production');
      // Monitor progress
      const logs = await sandbox.streamProcessLogs(build.id);
      // Process can run indefinitely without container shutdown
      for await (const log of parseSSEStream<LogEvent>(logs)) {
        console.log(log.data);
        if (log.data.includes('Build complete')) {
          break;
        }
      }
      return new Response('Build completed');
    } finally {
      // Important: Must explicitly destroy when done
      await sandbox.destroy();
    }
  }
};
:::caution[Always destroy with keepAlive]
When using 
keepAlive: true, containers will not automatically timeout. You must call 
sandbox.destroy() when finished to prevent containers running indefinitely and counting toward your account limits.
:::
Best practices
Wait for readiness - Use 
waitForPort() or 
waitForLog() to detect when services are ready
Clean up - Always stop processes when done
Handle failures - Monitor logs for errors and restart if needed
Use try/finally - Ensure cleanup happens even on errors
Use 
keepAlive for long-running tasks - Prevent container shutdown during processes with idle periods
Troubleshooting
Process exits immediately
Check logs to see why:
```
const process = await sandbox.startProcess('node server.js');
await new Promise(resolve => setTimeout(resolve, 1000));
const processes = await sandbox.listProcesses();
if (!processes.find(p => p.id === process.id)) {
const logs = await sandbox.getProcessLogs(process.id);
console.error('Process exited:', logs);
}
</TypeScriptExample>
### Port already in use
Kill existing processes before starting:
<TypeScriptExample>
await sandbox.killAllProcesses();
const server = await sandbox.startProcess('node server.js');
</TypeScriptExample>
## Related resources
- [Commands API reference](/sandbox/sdk/api/commands/) - Complete process management API
- [Sandbox options configuration](/sandbox/sdk/configuration/sandbox-options/) - Configure `keepAlive` and other options
- [Lifecycle API](/sandbox/sdk/api/lifecycle/) - Create and manage sandboxes
- [Sessions API reference](/sandbox/sdk/api/sessions/) - Create isolated execution contexts
- [Execute commands guide](/sandbox/sdk/guides/execute-commands/) - One-time command execution
- [Expose services guide](/sandbox/sdk/guides/expose-services/) - Make processes accessible
- [Streaming output guide](/sandbox/sdk/guides/streaming-output/) - Monitor process output

Backup and restore
import { TypeScriptExample, WranglerConfig, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/files/save-and-restore-a-workspace/", title: "Save and restore a sandbox with snapshots" }} />
This guide shows you how to snapshot a sandbox directory to R2 and restore it later.
Use backup and restore when a project directory such as 
/workspace should come back after the sandbox sleeps. For a separate persisted storage path, mount a bucket instead. If you mount a bucket over 
/workspace, the mount overlays files seeded by your image in production.
For why production restore uses an overlay, refer to Directory backups.
Prerequisites
Create an R2 bucket:
npx wrangler r2 bucket create my-backup-bucket
Add the 
BACKUP_BUCKET R2 binding and presigned URL settings to your Wrangler configuration:
{
	"name": "my-sandbox-worker",
	"main": "src/index.ts",
    "upload_source_maps": true,
	"compatibility_date": "$today",
	"compatibility_flags": ["nodejs_compat"],
	"containers": [
		{
			"class_name": "Sandbox",
			"image": "./Dockerfile",
		},
	],
	"durable_objects": {
		"bindings": [
			{
				"class_name": "Sandbox",
				"name": "Sandbox",
			},
		],
	},
	"migrations": [
		{
			"new_sqlite_classes": ["Sandbox"],
			"tag": "v1",
		},
	],
	"vars": {
		"BACKUP_BUCKET_NAME": "my-backup-bucket",
		"CLOUDFLARE_ACCOUNT_ID": "<YOUR_ACCOUNT_ID>",
	},
	"r2_buckets": [
		{
			"binding": "BACKUP_BUCKET",
			"bucket_name": "my-backup-bucket",
		},
	],
}
If the bucket uses a jurisdiction-specific endpoint, add 
BACKUP_BUCKET_ENDPOINT to 
vars. For an EU bucket, use 
https://<ACCOUNT_ID>.eu.r2.cloudflarestorage.com.
Store R2 API credentials as secrets:
npx wrangler secret put R2_ACCESS_KEY_ID
npx wrangler secret put R2_SECRET_ACCESS_KEY
Create the token in the Cloudflare dashboard under R2 > Overview > Manage R2 API Tokens. Grant Object Read & Write on the backup bucket.
:::note
The 
vars and API secrets in steps 2 and 3 are required for production. For 
wrangler dev, only the 
BACKUP_BUCKET binding is required. Refer to Use backup and restore in local development.
:::
Create a backup
import { getSandbox } from "@cloudflare/sandbox";
const sandbox = getSandbox(env.Sandbox, "my-sandbox");
const backup = await sandbox.createBackup({ dir: "/workspace" });
The directory must be an absolute path under 
/workspace, 
/home, 
/tmp, 
/var/tmp, or 
/app.
Restore a backup
Stop processes that write to the target directory, then restore:
import { getSandbox } from "@cloudflare/sandbox";
const sandbox = getSandbox(env.Sandbox, "my-sandbox");
const backup = await sandbox.createBackup({ dir: "/workspace" });
const result = await sandbox.restoreBackup(backup);
In production, restore mounts a copy-on-write overlay. The mount is lost when the sandbox sleeps or the container restarts. Restore again from the stored handle.
The restore target is 
backup.dir. You can point that field at a different allowed directory than the one you originally backed up.
Exclude generated caches
After a production restore, renaming a directory inside the restored tree can fail with 
EXDEV (
cross-device link not permitted). Omit disposable generated directories from the backup, or delete them after restore. Vite's cache is one such directory:
const backup = await sandbox.createBackup({
	dir: "/workspace/app",
	excludes: ["node_modules/.vite"],
});
await sandbox.restoreBackup(backup);
await sandbox.exec("rm -rf /workspace/app/node_modules/.vite");
This failure does not occur in 
wrangler dev, which extracts the archive. For overlay restore, refer to Directory backups.
Exclude gitignored files
To skip 
.gitignore matches such as 
node_modules/ or 
dist/ in a git repository:
const backup = await sandbox.createBackup({
	dir: "/workspace",
	gitignore: true,
});
If the directory is not inside a git repository, 
gitignore has no effect. If 
git is not installed in the container, the SDK logs a warning and continues without git-based exclusions. Nested 
.gitignore files apply.
Checkpoint and roll back
const sandbox = getSandbox(env.Sandbox, "my-sandbox");
const checkpoint = await sandbox.createBackup({ dir: "/workspace" });
try {
	await sandbox.exec("npm install <some-experimental-package>");
	await sandbox.exec("npm run build");
} catch (error) {
	await sandbox.restoreBackup(checkpoint);
}
Store backup handles
DirectoryBackup is serializable. Persist it to KV, D1, or Durable Object storage:
const backup = await sandbox.createBackup({
	dir: "/workspace",
	name: "deploy-v2",
	ttl: 604800, // 7 days
});
await env.KV.put(`backup:${userId}`, JSON.stringify(backup));
const stored = await env.KV.get(`backup:${userId}`);
if (stored) {
	await sandbox.restoreBackup(JSON.parse(stored));
}
Set a name and TTL
Names can be up to 256 characters. The default TTL is 3 days (
259200 seconds). The SDK rejects an expired backup at restore time. It does not delete the R2 objects.
const sandbox = getSandbox(env.Sandbox, "my-sandbox");
const shortBackup = await sandbox.createBackup({
	dir: "/workspace",
	ttl: 600, // 10 minutes
});
const longBackup = await sandbox.createBackup({
	dir: "/workspace",
	name: "daily-snapshot",
	ttl: 604800, // 7 days
});
To delete expired objects automatically, add an R2 object lifecycle rule on the 
backups/ prefix. If your longest TTL is 7 days, expire objects older than 7 days.
Clean up backup objects
Archives live at 
backups/{backupId}/data.sqsh and 
backups/{backupId}/meta.json.
Replace the latest backup
if (previousBackup) {
	await env.BACKUP_BUCKET.delete([
		`backups/${previousBackup.id}/data.sqsh`,
		`backups/${previousBackup.id}/meta.json`,
	]);
}
const backup = await sandbox.createBackup({
	dir: "/workspace",
	name: "latest",
});
await env.KV.put("latest-backup", JSON.stringify(backup));
Delete a backup by ID
await env.BACKUP_BUCKET.delete([
	`backups/${backup.id}/data.sqsh`,
	`backups/${backup.id}/meta.json`,
]);
Delete backups by age
List objects under 
backups/ and delete by upload time:
const listed = await env.BACKUP_BUCKET.list({ prefix: "backups/" });
const sevenDaysMs = 7 * 24 * 60 * 60 * 1000;
for (const object of listed.objects) {
	const ageMs = Date.now() - object.uploaded.getTime();
	if (ageMs > sevenDaysMs) {
		await env.BACKUP_BUCKET.delete(object.key);
	}
}
Use backup and restore in local development
Pass 
localBucket: true so 
wrangler dev uses the 
BACKUP_BUCKET binding. Presigned URL credentials are not required.
const backup = await sandbox.createBackup({
	dir: "/workspace",
	localBucket: Boolean(env.LOCAL_DEV),
});
const result = await sandbox.restoreBackup(backup);
Local restore extracts the archive with 
unsquashfs and replaces the directory. The stored handle's 
localBucket field selects the restore path.
Fix path permissions
createBackup() must read every file under the target directory. Files with mode 
0600 or directories owned by another user cause 
BackupCreateError.
Set permissions in the image when you can. 
a+rX adds read permission on files and execute permission on directories:
RUN mkdir -p /home/sandbox && chmod -R a+rX /home/sandbox
If a process creates restrictive files at runtime, fix them before the backup:
await sandbox.exec("chmod -R a+rX /home/sandbox/.claude");
const backup = await sandbox.createBackup({ dir: "/home/sandbox" });
Handle errors
import { getSandbox } from "@cloudflare/sandbox";
const sandbox = getSandbox(env.Sandbox, "my-sandbox");
try {
	const backup = await sandbox.createBackup({ dir: "/workspace" });
} catch (error) {
	if (error.code === "INVALID_BACKUP_CONFIG") {
		console.error("Configuration error:", error.message);
	} else if (error.code === "BACKUP_CREATE_FAILED") {
		console.error("Backup failed:", error.message);
	}
}
try {
	await sandbox.restoreBackup(backup);
} catch (error) {
	if (error.code === "BACKUP_NOT_FOUND") {
		console.error("Backup not found in R2:", error.message);
	} else if (error.code === "BACKUP_EXPIRED") {
		console.error("Backup TTL has elapsed:", error.message);
	} else if (error.code === "BACKUP_RESTORE_FAILED") {
		console.error("Restore failed:", error.message);
	}
}
Related resources
Directory backups - Overlay restore, local extract, and 
EXDEV
Backups API - Methods, options, and types
Storage API - Mount S3-compatible buckets
R2 documentation - R2 buckets and credentials
R2 lifecycle rules - Automatic object cleanup

Browser terminals
import { TypeScriptExample, PackageManagers, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/commands/open-a-terminal-in-the-browser/", title: "Open a terminal in the browser" }} />
This guide shows you how to connect a browser-based terminal to a sandbox shell. You can use the 
SandboxAddon with xterm.js, or connect directly over WebSockets.
Prerequisites
You need an existing Cloudflare Worker with a sandbox binding. Refer to Getting started if you do not have one.
Install the terminal dependencies in your frontend project:
If you are not using xterm.js, you only need 
@cloudflare/sandbox for types.
Handle WebSocket upgrades in the Worker
Add a route that proxies WebSocket connections to the sandbox terminal. The example below supports both the default session and named sessions via a query parameter:
import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
    if (url.pathname === '/ws/terminal' && request.headers.get('Upgrade') === 'websocket') {
      const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
      const sessionId = url.searchParams.get('session');
      if (sessionId) {
        const session = await sandbox.getSession(sessionId);
        return await session.terminal(request);
      }
      return await sandbox.terminal(request, { cols: 80, rows: 24 });
    }
    return new Response('Not found', { status: 404 });
  }
};
Connect with xterm.js and SandboxAddon
Create the terminal in your browser code and attach the 
SandboxAddon. The addon manages the WebSocket connection, automatic reconnection, and resize forwarding.
import { Terminal } from '@xterm/xterm';
import { FitAddon } from '@xterm/addon-fit';
import { SandboxAddon } from '@cloudflare/sandbox/xterm';
import '@xterm/xterm/css/xterm.css';
const terminal = new Terminal({ cursorBlink: true });
const fitAddon = new FitAddon();
terminal.loadAddon(fitAddon);
const addon = new SandboxAddon({
  getWebSocketUrl: ({ sandboxId, sessionId, origin }) => {
    const params = new URLSearchParams({ id: sandboxId });
    if (sessionId) params.set('session', sessionId);
    return `${origin}/ws/terminal?${params}`;
  },
  onStateChange: (state, error) => {
    console.log(`Terminal ${state}`, error ?? '');
  }
});
terminal.loadAddon(addon);
terminal.open(document.getElementById('terminal'));
fitAddon.fit();
// Connect to the default session
addon.connect({ sandboxId: 'my-sandbox' });
// Or connect to a specific session
// addon.connect({ sandboxId: 'my-sandbox', sessionId: 'development' });
window.addEventListener('resize', () => fitAddon.fit());
For the full addon API, refer to the Terminal API reference.
Connect without xterm.js
If you are building a custom terminal UI or running in an environment without xterm.js, connect directly over WebSockets. The protocol uses binary frames for terminal data and JSON text frames for control messages.
const ws = new WebSocket('wss://example.com/ws/terminal?id=my-sandbox');
ws.binaryType = 'arraybuffer';
const decoder = new TextDecoder();
const encoder = new TextEncoder();
ws.addEventListener('message', (event) => {
  if (event.data instanceof ArrayBuffer) {
    // Terminal output (binary) — includes ANSI escape sequences
    const text = decoder.decode(event.data);
    appendToDisplay(text);
    return;
  }
  // Control message (JSON text)
  const msg = JSON.parse(event.data);
  switch (msg.type) {
    case 'ready':
      // Terminal is accepting input — send initial resize
      ws.send(JSON.stringify({ type: 'resize', cols: 80, rows: 24 }));
      break;
    case 'exit':
      console.log(`Shell exited: code ${msg.code}`);
      break;
    case 'error':
      console.error('Terminal error:', msg.message);
      break;
  }
});
// Send keystrokes as binary
function sendInput(text: string): void {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(encoder.encode(text));
  }
}
Key protocol details:
Set 
binaryType to 
arraybuffer before connecting.
Buffered output from a previous connection arrives as binary frames before the 
ready message.
Send keystrokes as binary (UTF-8). Send control messages (
resize) as JSON text.
The PTY stays alive when a client disconnects. Reconnecting replays buffered output.
For the full protocol specification, refer to the WebSocket protocol section in the API reference.
Best practices
Always use FitAddon — Without it, terminal dimensions do not match the container and text wraps incorrectly.
Handle resize events — Call 
fitAddon.fit() on window resize so the terminal and PTY stay in sync.
Clean up on unmount — Call 
addon.disconnect() when removing the terminal from the page.
Scope terminals to a user sandbox — Use sessions for multiple terminal contexts in the same workspace. Use separate sandboxes for separate users.
Related resources
Terminal API reference — Method signatures, addon API, and WebSocket protocol
Terminal connections — How terminal connections work
Session management — How sessions work

Use code interpreter
import { TypeScriptExample, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
This guide shows you how to execute Python and JavaScript code with rich outputs using the Code Interpreter API.
When to use code interpreter
Use the Code Interpreter API for simple, direct code execution with minimal setup:
Quick code execution - Run Python/JS code without environment setup
Rich outputs - Get charts, tables, images, HTML automatically
AI-generated code - Execute LLM-generated code with structured results
Persistent state - Variables preserved between executions in the same context
Use 
exec() for advanced or custom workflows:
System operations - Install packages, manage files, run builds
Custom environments - Configure specific versions, dependencies
Shell commands - Git operations, system utilities, complex pipelines
Long-running processes - Background services, servers
Create an execution context
Code contexts maintain state between executions:
```
import { getSandbox } from '@cloudflare/sandbox';
const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
// Create a Python context
const pythonContext = await sandbox.createCodeContext({
language: 'python'
});
console.log('Context ID:', pythonContext.id);
console.log('Language:', pythonContext.language);
// Create a JavaScript context
const jsContext = await sandbox.createCodeContext({
language: 'javascript'
});
</TypeScriptExample>
## Execute code
### Simple execution
<TypeScriptExample>
// Create context
const context = await sandbox.createCodeContext({
language: 'python'
});
// Execute code
const result = await sandbox.runCode(
print("Hello from Code Interpreter!") result = 2 + 2 print(f"2 + 2 = {result}"), { context: context.id });
console.log('Output:', result.output);
console.log('Success:', result.success);
</TypeScriptExample>
### State within a context
Variables and imports remain available between executions in the same context, as long as the container stays active:
<TypeScriptExample>
const context = await sandbox.createCodeContext({
language: 'python'
});
// First execution - import and define variables
await sandbox.runCode(`
import pandas as pd
import numpy as np
data = [1, 2, 3, 4, 5]
print("Data initialized")
`, { context: context.id });
// Second execution - use previously defined variables
const result = await sandbox.runCode(
mean = np.mean(data) print(f"Mean: {mean}"), { context: context.id });
console.log(result.output); // "Mean: 3.0"
</TypeScriptExample>
:::note
Context state is lost if the container restarts due to inactivity. For critical data, store results outside the sandbox or design your code to reinitialize as needed.
:::
## Handle rich outputs
The code interpreter returns multiple output formats:
<TypeScriptExample>
const result = await sandbox.runCode(`
import matplotlib.pyplot as plt
plt.plot([1, 2, 3], [1, 4, 9])
plt.title('Simple Chart')
plt.show()
`, { context: context.id });
// Check available formats
console.log('Formats:', result.formats);  // ['text', 'png']
// Access outputs
if (result.outputs.png) {
// Return as image
return new Response(atob(result.outputs.png), {
headers: { 'Content-Type': 'image/png' }
});
}
if (result.outputs.html) {
// Return as HTML (pandas DataFrames)
return new Response(result.outputs.html, {
headers: { 'Content-Type': 'text/html' }
});
}
if (result.outputs.json) {
// Return as JSON
return Response.json(result.outputs.json);
}
</TypeScriptExample>
## Stream execution output
For long-running code, stream output in real-time:
<TypeScriptExample>
const context = await sandbox.createCodeContext({
language: 'python'
});
const result = await sandbox.runCode(
`
import time
for i in range(10):
print(f"Processing item {i+1}/10...")
time.sleep(0.5)
print("Done!")
`,
{
context: context.id,
stream: true,
onOutput: (data) => {
console.log('Output:', data);
},
onResult: (result) => {
console.log('Result:', result);
},
onError: (error) => {
console.error('Error:', error);
}
}
);
</TypeScriptExample>
## Execute AI-generated code
Run LLM-generated code safely in a sandbox:
<TypeScriptExample>
// 1. Generate code with Claude
const response = await fetch('https://api.anthropic.com/v1/messages', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': env.ANTHROPIC_API_KEY,
'anthropic-version': '2023-06-01'
},
body: JSON.stringify({
model: 'claude-3-5-sonnet-20241022',
max_tokens: 1024,
messages: [{
role: 'user',
content: 'Write Python code to calculate fibonacci sequence up to 100'
}]
})
});
const { content } = await response.json();
const code = content[0].text;
// 2. Execute in sandbox
const context = await sandbox.createCodeContext({ language: 'python' });
const result = await sandbox.runCode(code, { context: context.id });
console.log('Generated code:', code);
console.log('Output:', result.output);
console.log('Success:', result.success);
</TypeScriptExample>
## Manage contexts
### List all contexts
<TypeScriptExample>
const contexts = await sandbox.listCodeContexts();
console.log(
${contexts.length} active contexts:);
for (const ctx of contexts) {
console.log(
  ${ctx.id} (${ctx.language}));
}
</TypeScriptExample>
### Delete contexts
<TypeScriptExample>
// Delete specific context
await sandbox.deleteCodeContext(context.id);
console.log('Context deleted');
// Clean up all contexts
const contexts = await sandbox.listCodeContexts();
for (const ctx of contexts) {
await sandbox.deleteCodeContext(ctx.id);
}
console.log('All contexts deleted');
</TypeScriptExample>
## Best practices
- **Clean up contexts** - Delete contexts when done to free resources
- **Handle errors** - Always check `result.success` and `result.error`
- **Stream long operations** - Use streaming for code that takes >2 seconds
- **Validate AI code** - Review generated code before execution
## Related resources
- [Code Interpreter API reference](/sandbox/sdk/api/interpreter/) - Complete API documentation
- [AI code executor tutorial](/sandbox/sdk/tutorials/ai-code-executor/) - Build complete AI executor
- [Execute commands guide](/sandbox/sdk/guides/execute-commands/) - Lower-level command execution

Deploy a Sandbox application
import { PackageManagers, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
Sandbox runs on Containers. For deploy commands, Workers Builds, and rollout flags, refer to Deploy Containers and Rollouts.
To put 
exposePort() on a custom domain, refer to Configure preview URLs on a custom domain.
Keep the package and image aligned
The Worker depends on 
@cloudflare/sandbox. The container image must come from the same release line (Dockerfile and base image tags from the template or docs for that version).
When you bump the npm package:
Update the Dockerfile or image reference for the same line.
Run 
wrangler deploy so the new image is published.
If the Worker and image must cut over together, deploy with an immediate rollout:
Use this for breaking package and image pairs. Refer to Rollouts.
Deploy from your machine
Start Docker if 
image is a Dockerfile path. Registry image references do not need Docker at deploy time.
From the project root:
Confirm the Worker URL responds, then exercise a sandbox route.
The first deploy can take several minutes while the image provisions.
Workers Builds
For production, use 
wrangler deploy so the package and image can update together.
Non-production Workers Builds defaults to 
wrangler versions upload, which does not publish a new image. Version URLs are not generated for these Workers (they implement Durable Objects). Test with 
wrangler dev, or with a staging Worker or environment that runs 
wrangler deploy.
More detail: Before production.
Related
Deploy Containers
Rollouts
Configure preview URLs on a custom domain

Run Docker-in-Docker
import { Render, TypeScriptExample } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
This guide shows you how to run Docker inside a Sandbox, enabling you to build and run container images from within a secure sandbox.
When to use Docker-in-Docker
Use Docker-in-Docker when you need to:
Develop containerized applications - Run 
docker build to create images from Dockerfiles
Run Docker as part of CI/CD - Respond to code changes and build and push images using Cloudflare Containers
Run arbitrary container images - Start containers from an end-user provided image
Create a Docker-enabled image
Create a custom Dockerfile that combines the sandbox binary with Docker. The Docker daemon runs as 
root:
FROM docker:dind
# Use the musl build so it runs on Alpine-based docker:dind
COPY --from=docker.io/cloudflare/sandbox:0.12.14-musl /container-server/sandbox /sandbox
COPY --from=docker.io/cloudflare/sandbox:0.12.14-musl /usr/lib/libstdc++.so.6 /usr/lib/libstdc++.so.6
COPY --from=docker.io/cloudflare/sandbox:0.12.14-musl /usr/lib/libgcc_s.so.1 /usr/lib/libgcc_s.so.1
COPY --from=docker.io/cloudflare/sandbox:0.12.14-musl /bin/bash /bin/bash
COPY --from=docker.io/cloudflare/sandbox:0.12.14-musl /usr/lib/libreadline.so.8 /usr/lib/libreadline.so.8
COPY --from=docker.io/cloudflare/sandbox:0.12.14-musl /usr/lib/libreadline.so.8.2 /usr/lib/libreadline.so.8.2
# Start dockerd without iptables or IP forwarding, wait up to 60 seconds
# for it to accept connections, then keep running
RUN printf '#!/bin/sh\n\
set -eu\n\
dockerd-entrypoint.sh dockerd --iptables=false --ip6tables=false --ip-forward=false --exec-opt native.cgroupdriver=cgroupfs &\n\
timeout 60 sh -c "until docker version >/dev/null 2>&1; do sleep 0.2; done"\n\
echo "Docker is ready"\n\
wait\n' > /usr/local/bin/start-docker.sh && chmod +x /usr/local/bin/start-docker.sh
# Mount /tmp before the sandbox starts. Otherwise the docker:dind
# entrypoint mounts a new /tmp over the sandbox's session files.
ENTRYPOINT ["/bin/sh", "-c", "mountpoint -q /tmp || mount -t tmpfs none /tmp; exec /sandbox \"$@\"", "--"]
CMD ["/usr/local/bin/start-docker.sh"]
Match the 
cloudflare/sandbox image tag to the version of 
@cloudflare/sandbox in your Worker.
The sandbox runs the 
CMD script when it starts:
--iptables=false, 
--ip6tables=false, and 
--ip-forward=false stop Docker from changing network settings that Containers do not allow.
--exec-opt native.cgroupdriver=cgroupfs makes Docker manage cgroups directly instead of through systemd, which the container does not run.
If dockerd does not accept connections within 60 seconds, the script exits and the sandbox stops, so the failure shows up in your logs. Set 
SANDBOX_LOG_LEVEL to 
debug to log the output of dockerd. Refer to Sandbox options.
The script does not appear in 
listProcesses(), because the sandbox starts it outside its process list.
:::caution[Deployed sandboxes only]
Docker-in-Docker does not work under 
wrangler dev. Docker needs a privileged container, and local development cannot start one.
:::
Use Docker in your sandbox
Once deployed, you can run Docker commands through the sandbox. Docker becomes ready a few seconds after the sandbox starts, so wait for 
docker version to succeed first:
import { getSandbox } from "@cloudflare/sandbox";
const sandbox = getSandbox(env.Sandbox, "docker-sandbox");
// Wait for the Docker daemon
const ready = await sandbox.exec(
	"timeout 60 sh -c 'until docker version >/dev/null 2>&1; do sleep 0.2; done'",
);
if (!ready.success) {
	throw new Error("Docker did not start");
}
// Build an image
await sandbox.writeFile(
	"/workspace/Dockerfile",
	`
FROM alpine:latest
RUN apk add --no-cache curl
CMD ["echo", "Hello from Docker!"]
`,
);
const build = await sandbox.exec(
	"docker build --network=host -t my-image /workspace",
);
if (!build.success) {
	console.error("Build failed:", build.stderr);
}
// Run a container
const run = await sandbox.exec("docker run --network=host --rm my-image");
console.log(run.stdout); // "Hello from Docker!"
Limitations
Docker-in-Docker in Cloudflare Containers has the following limitations:
No iptables - Network isolation features that rely on iptables are not available
Ephemeral storage - Built images and containers are lost when the sandbox sleeps. You must persist them manually.
No local development - Docker cannot start under 
wrangler dev
Related resources
Dockerfile reference - Customize your sandbox image
Execute commands - Run commands in the sandbox
Background processes - Manage long-running processes

Execute commands
import { TypeScriptExample, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/containers/api/durable-object-container/#exec", title: "Container API" }} />
This guide shows you how to execute commands in the sandbox, handle output, and manage errors effectively.
Choose the right method
The SDK provides multiple approaches for running commands:
exec() - Run a command and wait for complete result. Best for one-time commands like builds, installations, and scripts.
execStream() - Stream output in real-time. Best for long-running commands where you need immediate feedback.
startProcess() - Start a background process. Best for web servers, databases, and services that need to keep running.
:::note
For web servers, databases, or services that need to keep running, use 
startProcess() instead. See the Background processes guide.
:::
Execute basic commands
Use 
exec() for simple commands that complete quickly:
```
import { getSandbox } from '@cloudflare/sandbox';
const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
// Execute a single command
const result = await sandbox.exec('python --version');
console.log(result.stdout);   // "Python 3.11.0"
console.log(result.exitCode); // 0
console.log(result.success);  // true
</TypeScriptExample>
## Pass arguments safely
When passing user input or dynamic values, avoid string interpolation to prevent injection attacks:
<TypeScriptExample>
// Unsafe - vulnerable to injection
const filename = userInput;
await sandbox.exec(
cat ${filename});
// Safe - use proper escaping or validation
const safeFilename = filename.replace(/[^a-zA-Z0-9_.-]/g, '');
await sandbox.exec(
cat ${safeFilename});
// Better - write to file and execute
await sandbox.writeFile('/tmp/input.txt', userInput);
await sandbox.exec('python process.py /tmp/input.txt');
</TypeScriptExample>
## Handle errors
Commands can fail in two ways:
1. **Non-zero exit code** - Command ran but failed (result.success === false)
2. **Execution error** - Command couldn't start (throws exception)
<TypeScriptExample>
try {
const result = await sandbox.exec('python analyze.py');
if (!result.success) {
// Command failed (non-zero exit code)
console.error('Analysis failed:', result.stderr);
console.log('Exit code:', result.exitCode);
// Handle specific exit codes
if (result.exitCode === 1) {
  throw new Error('Invalid input data');
} else if (result.exitCode === 2) {
  throw new Error('Missing dependencies');
}
}
// Success - process output
return JSON.parse(result.stdout);
} catch (error) {
// Execution error (couldn't start command)
console.error('Execution failed:', error.message);
throw error;
}
</TypeScriptExample>
## Execute shell commands
The sandbox supports shell features like pipes, redirects, and chaining:
<TypeScriptExample>
// Pipes and filters
const result = await sandbox.exec('ls -la | grep ".py" | wc -l');
console.log('Python files:', result.stdout.trim());
// Output redirection
await sandbox.exec('python generate.py > output.txt 2> errors.txt');
// Multiple commands
await sandbox.exec('cd /workspace && npm install && npm test');
</TypeScriptExample>
## Execute Python scripts
<TypeScriptExample>
// Run inline Python
const result = await sandbox.exec('python -c "print(sum([1, 2, 3, 4, 5]))"');
console.log('Sum:', result.stdout.trim()); // "15"
// Run a script file
await sandbox.writeFile('/workspace/analyze.py', 
import sys print(f"Argument: {sys.argv[1]}"));
await sandbox.exec('python /workspace/analyze.py data.csv');
</TypeScriptExample>
## Timeouts
Set a maximum execution time for commands to prevent long-running operations from blocking indefinitely.
### Per-command timeout
Pass `timeout` in the options to set a timeout for a single command:
<TypeScriptExample>
const result = await sandbox.exec('npm run build', {
timeout: 30000 // 30 seconds
});
</TypeScriptExample>
### Session-level timeout
Set a default timeout for all commands in a session with `commandTimeoutMs`:
<TypeScriptExample>
const session = await sandbox.createSession({
commandTimeoutMs: 10000 // 10s default for all commands
});
await session.exec('npm install');    // Times out after 10s
await session.exec('npm run build');  // Times out after 10s
// Per-command timeout overrides the session default
await session.exec('npm test', { timeout: 60000 }); // 60s for this command
</TypeScriptExample>
### Global timeout
Set the `COMMAND_TIMEOUT_MS` [environment variable](/sandbox/sdk/configuration/environment-variables/#command_timeout_ms) to define a global default timeout for every `exec()` call across all sessions.
### Timeout precedence
When multiple timeouts are configured, the most specific value wins:
1. **Per-command** `timeout` on `exec()` (highest priority)
2. **Session-level** `commandTimeoutMs` on `createSession()`
3. **Global** `COMMAND_TIMEOUT_MS` environment variable (lowest priority)
If none are set, commands run without a timeout.
### Timeout does not kill the process
:::caution
When a command times out, the SDK raises an error and closes the connection. The underlying process **continues running** inside the container. To stop a timed-out process, delete the session with [`deleteSession()`](/sandbox/sdk/api/sessions/#deletesession) or destroy the sandbox with [`destroy()`](/sandbox/sdk/api/lifecycle/#destroy).
:::
## Best practices
- **Check exit codes** - Always verify `result.success` and `result.exitCode`
- **Validate inputs** - Escape or validate user input to prevent injection
- **Use streaming** - For long operations, use `execStream()` for real-time feedback
- **Use background processes** - For services that need to keep running (web servers, databases), use the [Background processes guide](/sandbox/sdk/guides/background-processes/) instead
- **Handle errors** - Check stderr for error details
## Troubleshooting
### Command not found
Verify the command exists in the container:
<TypeScriptExample>
const check = await sandbox.exec('which python3');
if (!check.success) {
console.error('python3 not found');
}
</TypeScriptExample>
### Working directory issues
Use absolute paths or change directory:
<TypeScriptExample>
// Use absolute path
await sandbox.exec('python /workspace/my-app/script.py');
// Or change directory
await sandbox.exec('cd /workspace/my-app && python script.py');
</TypeScriptExample>
## Related resources
- [Commands API reference](/sandbox/sdk/api/commands/) - Complete method documentation
- [Background processes guide](/sandbox/sdk/guides/background-processes/) - Managing long-running processes
- [Streaming output guide](/sandbox/sdk/guides/streaming-output/) - Advanced streaming patterns
- [Code Interpreter guide](/sandbox/sdk/guides/code-execution/) - Higher-level code execution

Expose services
import { TypeScriptExample, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/previews/", title: "Preview a web application" }} />
:::note[Production requires custom domain]
Preview URLs require a custom domain with wildcard DNS routing in production. See Configure preview URLs on a custom domain for setup instructions.
:::
:::note[Prefer 
sandbox.tunnels for public URLs]
sandbox.tunnels is the recommended option for most public-URL use cases, including production. Quick tunnels give you a zero-config 
*.trycloudflare.com URL; named tunnels bind a stable 
<name>.<your-zone> hostname. Follow this guide when you specifically want the Worker itself to front the request (for example, to inject authentication or rewrite responses).
:::
This guide shows you how to expose services running in your sandbox to the internet via preview URLs.
When to expose ports
Expose ports when you need to:
Test web applications - Preview frontend or backend apps
Share demos - Give others access to running applications
Develop APIs - Test endpoints from external tools
Debug services - Access internal services for troubleshooting
Build dev environments - Create shareable development workspaces
Basic port exposure
The typical workflow is: start service → wait for ready → expose port → handle requests with 
proxyToSandbox.
```
import { getSandbox, proxyToSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';
export default {
async fetch(request: Request, env: Env): Promise {
// Proxy requests to exposed ports first
const proxyResponse = await proxyToSandbox(request, env);
if (proxyResponse) return proxyResponse;
// Extract hostname from request
const { hostname } = new URL(request.url);
const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
// 1. Start a web server
await sandbox.startProcess('python -m http.server 8000');
// 2. Wait for service to start
await new Promise(resolve => setTimeout(resolve, 2000));
// 3. Expose the port
const exposed = await sandbox.exposePort(8000, { hostname });
// 4. Preview URL is now available (public by default)
console.log('Server accessible at:', exposed.url);
// Production: https://8000-abc123.yourdomain.com
// Local dev: http://localhost:8787/...
return Response.json({ url: exposed.url });
}
};
</TypeScriptExample>
:::caution
**Preview URLs are public by default.** Anyone with the URL can access your service. Add authentication if needed.
:::
:::note[Local development requirement]
When using `wrangler dev`, you must add `EXPOSE` directives to your Dockerfile for each port you plan to expose. Without this, you'll see "Connection refused: container port not found". See [Local development](#local-development) section below for setup details.
:::
:::caution[Uppercase sandbox IDs don't work with preview URLs]
Preview URLs extract the sandbox ID from the hostname, which is always lowercase (e.g., `8000-myproject-123.yourdomain.com`). If you created your sandbox with an uppercase ID like `"MyProject-123"`, the URL routes to `"myproject-123"` (a different Durable Object), making your sandbox unreachable.
To fix this, use `normalizeId: true` when creating sandboxes for port exposure:
```ts
const sandbox = getSandbox(env.Sandbox, 'MyProject-123', { normalizeId: true });
This lowercases the ID during creation so it matches preview URL routing. Without this, 
exposePort() throws an error.
Best practice: Use lowercase IDs from the start (
'my-project-123').
See Sandbox options for details.
:::
Stable URLs with custom tokens
For production deployments or when sharing URLs with users, use custom tokens to maintain consistent preview URLs across container restarts:
```
// Extract hostname from request
const { hostname } = new URL(request.url);
// Without custom token - URL changes on restart
const exposed = await sandbox.exposePort(8080, { hostname });
// https://8080-sandbox-id-random16chars12.yourdomain.com
// With custom token - URL stays the same across restarts
const stable = await sandbox.exposePort(8080, {
hostname,
token: 'api-v1'
});
// https://8080-sandbox-id-api-v1.yourdomain.com
// Same URL after container restart ✓
return Response.json({
'Temporary URL (changes on restart)': exposed.url,
'Stable URL (consistent)': stable.url
});
</TypeScriptExample>
**Token requirements:**
- 1-16 characters long
- Lowercase letters (a-z), numbers (0-9), hyphens (-), and underscores (_) only
- Must be unique within each sandbox
**Use cases:**
- Production APIs with stable endpoints
- Sharing demo URLs with external users
- Integration testing with predictable URLs
- Documentation with consistent examples
## Name your exposed ports
When exposing multiple ports, use names to stay organized:
<TypeScriptExample>
// Extract hostname from request
const { hostname } = new URL(request.url);
// Start and expose API server with stable token
await sandbox.startProcess('node api.js', { env: { PORT: '8080' } });
await new Promise(resolve => setTimeout(resolve, 2000));
const api = await sandbox.exposePort(8080, {
hostname,
name: 'api',
token: 'api-prod'
});
// Start and expose frontend with stable token
await sandbox.startProcess('npm run dev', { env: { PORT: '5173' } });
await new Promise(resolve => setTimeout(resolve, 2000));
const frontend = await sandbox.exposePort(5173, {
hostname,
name: 'frontend',
token: 'web-app'
});
console.log('Services:');
console.log('- API:', api.url);
console.log('- Frontend:', frontend.url);
</TypeScriptExample>
## Wait for service readiness
Always verify a service is ready before exposing. Use a simple delay for most cases:
<TypeScriptExample>
// Extract hostname from request
const { hostname } = new URL(request.url);
// Start service
await sandbox.startProcess('npm run dev', { env: { PORT: '8080' } });
// Wait 2-3 seconds
await new Promise(resolve => setTimeout(resolve, 2000));
// Now expose
await sandbox.exposePort(8080, { hostname });
</TypeScriptExample>
For critical services, poll the health endpoint:
<TypeScriptExample>
// Extract hostname from request
const { hostname } = new URL(request.url);
await sandbox.startProcess('node api-server.js', { env: { PORT: '8080' } });
// Wait for health check
for (let i = 0; i < 10; i++) {
await new Promise(resolve => setTimeout(resolve, 1000));
const check = await sandbox.exec('curl -f http://localhost:8080/health || echo "not ready"');
if (check.stdout.includes('ok')) {
break;
}
}
await sandbox.exposePort(8080, { hostname });
</TypeScriptExample>
## Multiple services
Expose multiple ports for full-stack applications:
<TypeScriptExample>
// Extract hostname from request
const { hostname } = new URL(request.url);
// Start backend
await sandbox.startProcess('node api/server.js', {
env: { PORT: '8080' }
});
await new Promise(resolve => setTimeout(resolve, 2000));
// Start frontend
await sandbox.startProcess('npm run dev', {
cwd: '/workspace/frontend',
env: { PORT: '5173', API_URL: 'http://localhost:8080' }
});
await new Promise(resolve => setTimeout(resolve, 3000));
// Expose both
const api = await sandbox.exposePort(8080, { hostname, name: 'api' });
const frontend = await sandbox.exposePort(5173, { hostname, name: 'frontend' });
return Response.json({
api: api.url,
frontend: frontend.url
});
</TypeScriptExample>
## Manage exposed ports
### List currently exposed ports
<TypeScriptExample>
const { ports, count } = await sandbox.getExposedPorts();
console.log(
${count} ports currently exposed:);
for (const port of ports) {
console.log(
  Port ${port.port}: ${port.url});
if (port.name) {
console.log(
    Name: ${port.name});
}
}
</TypeScriptExample>
### Unexpose ports
<TypeScriptExample>
// Unexpose a single port
await sandbox.unexposePort(8000);
// Unexpose multiple ports
for (const port of [3000, 5173, 8080]) {
await sandbox.unexposePort(port);
}
</TypeScriptExample>
## Best practices
- **Wait for readiness** - Don't expose ports immediately after starting processes
- **Use named ports** - Easier to track when exposing multiple ports
- **Clean up** - Unexpose ports when done to prevent abandoned URLs
- **Add authentication** - Preview URLs are public; protect sensitive services
## Local development
When developing locally with `wrangler dev`, you must expose ports in your Dockerfile:
```dockerfile title="Dockerfile"
FROM docker.io/cloudflare/sandbox:0.12.14
# Expose ports you plan to use
EXPOSE 8000
EXPOSE 8080
EXPOSE 5173
Update 
wrangler.jsonc to use your Dockerfile:
{
  "containers": [
    {
      "class_name": "Sandbox",
      "image": "./Dockerfile"
    }
  ]
}
In production, all ports are available and controlled programmatically via 
exposePort() / 
unexposePort().
Troubleshooting
Port 3000 is reserved
Port 3000 is used by the internal Bun server and cannot be exposed:
```
// Extract hostname from request
const { hostname } = new URL(request.url);
// ❌ This will fail
await sandbox.exposePort(3000, { hostname });  // Error: Port 3000 is reserved
// ✅ Use a different port
await sandbox.startProcess('node server.js', { env: { PORT: '8080' } });
await sandbox.exposePort(8080, { hostname });
</TypeScriptExample>
### Port not ready
Wait for the service to start before exposing:
<TypeScriptExample>
// Extract hostname from request
const { hostname } = new URL(request.url);
await sandbox.startProcess('npm run dev');
await new Promise(resolve => setTimeout(resolve, 3000));
await sandbox.exposePort(8080, { hostname });
</TypeScriptExample>
### Port already exposed
Check before exposing to avoid errors:
<TypeScriptExample>
// Extract hostname from request
const { hostname } = new URL(request.url);
const { ports } = await sandbox.getExposedPorts();
if (!ports.some(p => p.port === 8080)) {
await sandbox.exposePort(8080, { hostname });
}
</TypeScriptExample>
### Uppercase sandbox ID error
**Error**: `Preview URLs require lowercase sandbox IDs`
**Cause**: You created a sandbox with uppercase characters (e.g., `"MyProject-123"`) but preview URLs always use lowercase in routing, causing a mismatch.
**Solution**:
<TypeScriptExample>
// Create sandbox with normalization
const sandbox = getSandbox(env.Sandbox, 'MyProject-123', { normalizeId: true });
await sandbox.exposePort(8080, { hostname });
</TypeScriptExample>
This creates the Durable Object with ID `"myproject-123"`, matching the preview URL routing.
See [Sandbox options - normalizeId](/sandbox/sdk/configuration/sandbox-options/#normalizeid) for details.
## Preview URL Format
**Production**: `https://{port}-{sandbox-id}-{token}.yourdomain.com`
- Auto-generated token: `https://8080-abc123-random16chars12.yourdomain.com`
- Custom token: `https://8080-abc123-my-api-v1.yourdomain.com`
**Local development**: `http://localhost:8787/...`
**Note**: Port 3000 is reserved for the internal Bun server and cannot be exposed.
## Related resources
- [Ports API reference](/sandbox/sdk/api/ports/) - Complete port exposure API
- [Background processes guide](/sandbox/sdk/guides/background-processes/) - Managing services
- [Execute commands guide](/sandbox/sdk/guides/execute-commands/) - Starting services
- [Tunnels API reference](/sandbox/sdk/api/tunnels/) - Recommended alternative for most public-URL use cases (quick or named tunnels)

Watch filesystem changes
import { TypeScriptExample, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
This guide shows you how to monitor filesystem changes in real-time using the Sandbox SDK's file watching API. File watching is useful for building development tools, automated workflows, and applications that react to file changes as they happen.
The 
watch() method returns an SSE (Server-Sent Events) stream that you consume with 
parseSSEStream(). Each event in the stream describes a filesystem change.
Basic file watching
Start by watching a directory for any changes:
import { parseSSEStream } from "@cloudflare/sandbox";
import type { FileWatchSSEEvent } from "@cloudflare/sandbox";
const stream = await sandbox.watch("/workspace/src");
for await (const event of parseSSEStream<FileWatchSSEEvent>(stream)) {
	if (event.type === "event") {
		console.log(`${event.eventType}: ${event.path}`);
		console.log(`Is directory: ${event.isDirectory}`);
	}
}
The stream emits four lifecycle event types:
watching — Watch established, includes the 
watchId
event — A filesystem change occurred
error — The watch encountered an error
stopped — The watch was stopped
Filesystem change events (
event.eventType) include:
create — File or directory was created
modify — File content changed
delete — File or directory was removed
move_from / 
move_to — File or directory was moved or renamed
attrib — File attributes changed (permissions, timestamps)
Filter by file type
Use 
include patterns to watch only specific file types:
import { parseSSEStream } from "@cloudflare/sandbox";
import type { FileWatchSSEEvent } from "@cloudflare/sandbox";
// Only watch TypeScript and JavaScript files
const stream = await sandbox.watch("/workspace/src", {
	include: ["*.ts", "*.tsx", "*.js", "*.jsx"],
});
for await (const event of parseSSEStream<FileWatchSSEEvent>(stream)) {
	if (event.type === "event") {
		console.log(`${event.eventType}: ${event.path}`);
	}
}
Common include patterns:
*.ts — TypeScript files
*.js — JavaScript files
*.json — JSON configuration files
*.md — Markdown documentation
package*.json — Package files specifically
Exclude directories
Use 
exclude patterns to skip certain directories or files:
import { parseSSEStream } from "@cloudflare/sandbox";
import type { FileWatchSSEEvent } from "@cloudflare/sandbox";
const stream = await sandbox.watch("/workspace", {
	exclude: ["node_modules", "dist", "*.log", ".git", "*.tmp"],
});
for await (const event of parseSSEStream<FileWatchSSEEvent>(stream)) {
	if (event.type === "event") {
		console.log(`Change detected: ${event.path}`);
	}
}
:::note[Default exclusions]
The following patterns are excluded by default: 
.git, 
node_modules, 
.DS_Store. You can override this by providing your own 
exclude array.
:::
Build responsive development tools
Auto-rebuild on changes
Trigger builds automatically when source files are modified:
import { parseSSEStream } from "@cloudflare/sandbox";
import type { FileWatchSSEEvent } from "@cloudflare/sandbox";
const stream = await sandbox.watch("/workspace/src", {
	include: ["*.ts", "*.tsx"],
});
let buildInProgress = false;
for await (const event of parseSSEStream<FileWatchSSEEvent>(stream)) {
	if (
		event.type === "event" &&
		event.eventType === "modify" &&
		!buildInProgress
	) {
		buildInProgress = true;
		console.log(`File changed: ${event.path}, rebuilding...`);
		try {
			const result = await sandbox.exec("npm run build");
			if (result.success) {
				console.log("Build completed successfully");
			} else {
				console.error("Build failed:", result.stderr);
			}
		} catch (error) {
			console.error("Build error:", error);
		} finally {
			buildInProgress = false;
		}
	}
}
Auto-run tests on change
Re-run tests when test files are modified:
import { parseSSEStream } from "@cloudflare/sandbox";
import type { FileWatchSSEEvent } from "@cloudflare/sandbox";
const stream = await sandbox.watch("/workspace/tests", {
	include: ["*.test.ts", "*.spec.ts"],
});
for await (const event of parseSSEStream<FileWatchSSEEvent>(stream)) {
	if (event.type === "event" && event.eventType === "modify") {
		console.log(`Test file changed: ${event.path}`);
		const result = await sandbox.exec(`npm test -- ${event.path}`);
		console.log(result.success ? "Tests passed" : "Tests failed");
	}
}
Incremental indexing
Re-index only changed files instead of rescanning an entire directory tree:
import { parseSSEStream } from "@cloudflare/sandbox";
import type { FileWatchSSEEvent } from "@cloudflare/sandbox";
const stream = await sandbox.watch("/workspace/docs", {
	include: ["*.md", "*.mdx"],
});
for await (const event of parseSSEStream<FileWatchSSEEvent>(stream)) {
	if (event.type === "event") {
		switch (event.eventType) {
			case "create":
			case "modify":
				console.log(`Indexing ${event.path}...`);
				await indexFile(event.path);
				break;
			case "delete":
				console.log(`Removing ${event.path} from index...`);
				await removeFromIndex(event.path);
				break;
		}
	}
}
Advanced patterns
Process events with a helper function
Extract event processing into a reusable function that handles stream lifecycle:
import { parseSSEStream } from "@cloudflare/sandbox";
import type { FileWatchSSEEvent } from "@cloudflare/sandbox";
async function watchFiles(
	sandbox: any,
	path: string,
	options: { include?: string[]; exclude?: string[] },
	handler: (
		eventType: string,
		filePath: string,
		isDirectory: boolean,
	) => Promise<void>,
) {
	const stream = await sandbox.watch(path, options);
	for await (const event of parseSSEStream<FileWatchSSEEvent>(stream)) {
		switch (event.type) {
			case "watching":
				console.log(`Watching ${event.path}`);
				break;
			case "event":
				await handler(event.eventType, event.path, event.isDirectory);
				break;
			case "error":
				console.error(`Watch error: ${event.error}`);
				break;
			case "stopped":
				console.log(`Watch stopped: ${event.reason}`);
				return;
		}
	}
}
// Usage
await watchFiles(
	sandbox,
	"/workspace/src",
	{ include: ["*.ts"] },
	async (eventType, filePath) => {
		console.log(`${eventType}: ${filePath}`);
	},
);
Debounced file operations
Avoid excessive operations by collecting changes before processing:
import { parseSSEStream } from "@cloudflare/sandbox";
import type { FileWatchSSEEvent } from "@cloudflare/sandbox";
const stream = await sandbox.watch("/workspace/src");
const changedFiles = new Set<string>();
let debounceTimeout: ReturnType<typeof setTimeout> | null = null;
for await (const event of parseSSEStream<FileWatchSSEEvent>(stream)) {
	if (event.type === "event") {
		changedFiles.add(event.path);
		if (debounceTimeout) {
			clearTimeout(debounceTimeout);
		}
		debounceTimeout = setTimeout(async () => {
			console.log(`Processing ${changedFiles.size} changed files...`);
			for (const filePath of changedFiles) {
				await processFile(filePath);
			}
			changedFiles.clear();
			debounceTimeout = null;
		}, 1000);
	}
}
Watch with non-recursive mode
Watch only the top level of a directory, without descending into subdirectories:
import { parseSSEStream } from "@cloudflare/sandbox";
import type { FileWatchSSEEvent } from "@cloudflare/sandbox";
// Only watch root-level config files
const stream = await sandbox.watch("/workspace", {
	include: ["package.json", "tsconfig.json", "vite.config.ts"],
	recursive: false,
});
for await (const event of parseSSEStream<FileWatchSSEEvent>(stream)) {
	if (event.type === "event") {
		console.log("Configuration changed, rebuilding project...");
		await sandbox.exec("npm run build");
	}
}
Stop a watch
The stream ends naturally when the container sleeps or shuts down. There are two ways to stop a watch early:
Use an AbortController
Pass an 
AbortSignal to 
parseSSEStream. Aborting the signal cancels the stream reader, which propagates cleanup to the server. This is the recommended approach when you need to cancel the watch from outside the consuming loop:
import { parseSSEStream } from "@cloudflare/sandbox";
import type { FileWatchSSEEvent } from "@cloudflare/sandbox";
const stream = await sandbox.watch("/workspace/src");
const controller = new AbortController();
// Cancel after 60 seconds
setTimeout(() => controller.abort(), 60_000);
for await (const event of parseSSEStream<FileWatchSSEEvent>(
	stream,
	controller.signal,
)) {
	if (event.type === "event") {
		console.log(`${event.eventType}: ${event.path}`);
	}
}
console.log("Watch stopped");
Break out of the loop
Breaking out of the 
for await loop also cancels the stream:
import { parseSSEStream } from "@cloudflare/sandbox";
import type { FileWatchSSEEvent } from "@cloudflare/sandbox";
const stream = await sandbox.watch("/workspace/src");
let eventCount = 0;
for await (const event of parseSSEStream<FileWatchSSEEvent>(stream)) {
	if (event.type === "event") {
		console.log(`${event.eventType}: ${event.path}`);
		eventCount++;
		// Stop after 100 events
		if (eventCount >= 100) {
			break; // Breaking out of the loop cancels the stream
		}
	}
}
console.log("Watch stopped");
Best practices
Use server-side filtering
Filter with 
include or 
exclude patterns rather than filtering events in JavaScript. Server-side filtering happens at the inotify level, which reduces the number of events sent over the network.
:::note
include and 
exclude are mutually exclusive. Use one or the other, not both. If you need to watch specific file types while ignoring certain directories, use 
include patterns that match the files you want.
:::
import { parseSSEStream } from "@cloudflare/sandbox";
import type { FileWatchSSEEvent } from "@cloudflare/sandbox";
// Efficient: filtering happens at the inotify level
const stream = await sandbox.watch("/workspace/src", {
	include: ["*.ts"],
});
// Less efficient: all events are sent and then filtered in JavaScript
const stream2 = await sandbox.watch("/workspace/src");
for await (const event of parseSSEStream<FileWatchSSEEvent>(stream2)) {
	if (event.type === "event") {
		if (!event.path.endsWith(".ts")) continue;
		// Handle event
	}
}
Handle errors in event processing
Errors in your event handler do not stop the watch stream. Wrap handler logic in 
try...catch to prevent unhandled exceptions:
import { parseSSEStream } from "@cloudflare/sandbox";
import type { FileWatchSSEEvent } from "@cloudflare/sandbox";
const stream = await sandbox.watch("/workspace/src");
for await (const event of parseSSEStream<FileWatchSSEEvent>(stream)) {
	if (event.type === "event") {
		try {
			await handleFileChange(event.eventType, event.path);
		} catch (error) {
			console.error(
				`Failed to handle ${event.eventType} for ${event.path}:`,
				error,
			);
			// Continue processing events
		}
	}
	if (event.type === "error") {
		console.error("Watch error:", event.error);
	}
}
Ensure directories exist before watching
Watching a non-existent path returns an error. Verify the path exists before starting a watch:
const watchPath = "/workspace/src";
const result = await sandbox.exists(watchPath);
if (!result.exists) {
	await sandbox.mkdir(watchPath, { recursive: true });
}
const stream = await sandbox.watch(watchPath, {
	include: ["*.ts"],
});
Troubleshooting
High CPU usage
If watching large directories causes performance issues:
Use specific 
include patterns instead of watching everything
Exclude large directories like 
node_modules and 
dist
Watch specific subdirectories instead of the entire project
Use 
recursive: false for shallow monitoring
Path not found errors
All paths must exist and resolve to within 
/workspace. Relative paths are resolved from 
/workspace.
:::note[Container lifecycle]
File watchers are automatically stopped when the sandbox sleeps or shuts down. If the sandbox wakes up, you must re-establish watches in your application logic.
:::
Related resources
File Watching API reference — Complete API documentation and types
Manage files guide — File operations
Background processes guide — Long-running processes
Stream output guide — Real-time output handling

Work with Git
import { TypeScriptExample, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/commands/run-tests-from-a-git-repository/", title: "Run tests from a Git repository" }} />
This guide shows you how to clone repositories, manage branches, and automate Git operations in the sandbox.
Clone repositories
```
import { getSandbox } from '@cloudflare/sandbox';
const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
// Basic clone
await sandbox.gitCheckout('https://github.com/user/repo');
// Clone specific branch
await sandbox.gitCheckout('https://github.com/user/repo', {
branch: 'develop'
});
// Shallow clone (faster for large repos)
await sandbox.gitCheckout('https://github.com/user/large-repo', {
depth: 1
});
// Clone to specific directory
await sandbox.gitCheckout('https://github.com/user/my-app', {
targetDir: '/workspace/project'
});
</TypeScriptExample>
## Clone private repositories
Use a personal access token in the URL:
<TypeScriptExample>
const token = env.GITHUB_TOKEN;
const repoUrl = 
https://${token}@github.com/user/private-repo.git;
await sandbox.gitCheckout(repoUrl);
</TypeScriptExample>
:::note[More secure alternative]
Embedding a token in the URL passes the credential directly into the sandbox. For better access control, use an outbound handler that injects the real token at request time — the sandbox never holds the credential. Refer to [Handle outbound traffic](/sandbox/sdk/guides/outbound-traffic/).
:::
## Clone and build
Clone a repository and run build steps:
<TypeScriptExample>
await sandbox.gitCheckout('https://github.com/user/my-app');
const repoName = 'my-app';
// Install and build
await sandbox.exec(
cd ${repoName} && npm install);
await sandbox.exec(
cd ${repoName} && npm run build);
console.log('Build complete');
</TypeScriptExample>
## Work with branches
<TypeScriptExample>
await sandbox.gitCheckout('https://github.com/user/repo');
// Switch branches
await sandbox.exec('cd repo && git checkout feature-branch');
// Create new branch
await sandbox.exec('cd repo && git checkout -b new-feature');
</TypeScriptExample>
## Make changes and commit
<TypeScriptExample>
await sandbox.gitCheckout('https://github.com/user/repo');
// Modify a file
const readme = await sandbox.readFile('/workspace/repo/README.md');
await sandbox.writeFile('/workspace/repo/README.md', readme.content + '\n\n## New Section');
// Commit changes
await sandbox.exec('cd repo && git config user.name "Sandbox Bot"');
await sandbox.exec('cd repo && git config user.email "bot@example.com"');
await sandbox.exec('cd repo && git add README.md');
await sandbox.exec('cd repo && git commit -m "Update README"');
</TypeScriptExample>
## Best practices
- **Use shallow clones** - Faster for large repos with `depth: 1`
- **Store credentials securely** - Use environment variables for tokens
- **Clean up** - Delete unused repositories to save space
## Troubleshooting
### Authentication fails
Verify your token is set:
<TypeScriptExample>
if (!env.GITHUB_TOKEN) {
throw new Error('GITHUB_TOKEN not configured');
}
const repoUrl = 
https://${env.GITHUB_TOKEN}@github.com/user/private-repo.git;
await sandbox.gitCheckout(repoUrl);
</TypeScriptExample>
### Large repository timeout
Use shallow clone:
<TypeScriptExample>
await sandbox.gitCheckout('https://github.com/user/large-repo', {
depth: 1
});
</TypeScriptExample>
## Related resources
- [Files API reference](/sandbox/sdk/api/files/) - File operations after cloning
- [Execute commands guide](/sandbox/sdk/guides/execute-commands/) - Run git commands
- [Manage files guide](/sandbox/sdk/guides/manage-files/) - Work with cloned files

How-to guides
import { ResourcesBySelector, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes on Cloudflare" }} />
These guides show you how to solve specific problems and implement features with the Sandbox SDK. Each guide focuses on a particular task and provides practical, production-ready solutions.
<ResourcesBySelector directory="sandbox/sdk/guides/" types={["how-to"]} />
Related resources
Tutorials - Step-by-step learning paths
API reference - Complete method documentation

Manage files
import { TypeScriptExample, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/files/manage-files/", title: "Move files in and out of a sandbox" }} />
This guide shows you how to read, write, organize, and synchronize files in the sandbox filesystem.
Path conventions
File operations support both absolute and relative paths:
/workspace - Default working directory for application files
/tmp - Temporary files (may be cleared)
/home - User home directory
```
// Absolute paths
await sandbox.writeFile('/workspace/app.js', code);
// Relative paths (session-aware)
const session = await sandbox.createSession();
await session.exec('cd /workspace/my-project');
await session.writeFile('app.js', code);  // Writes to /workspace/my-project/app.js
await session.writeFile('src/index.js', code);  // Writes to /workspace/my-project/src/index.js
</TypeScriptExample>
## Write files
<TypeScriptExample>
import { getSandbox } from '@cloudflare/sandbox';
const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
// Write text file
await sandbox.writeFile('/workspace/app.js', 
console.log('Hello from sandbox!'););
// Write JSON
const config = { name: 'my-app', version: '1.0.0' };
await sandbox.writeFile('/workspace/config.json', JSON.stringify(config, null, 2));
// Write binary file (base64)
const buffer = await fetch(imageUrl).then(r => r.arrayBuffer());
const base64 = btoa(String.fromCharCode(...new Uint8Array(buffer)));
await sandbox.writeFile('/workspace/image.png', base64, { encoding: 'base64' });
</TypeScriptExample>
## Read files
<TypeScriptExample>
// Read text file
const file = await sandbox.readFile('/workspace/app.js');
console.log(file.content);
// Read and parse JSON
const configFile = await sandbox.readFile('/workspace/config.json');
const config = JSON.parse(configFile.content);
// Read binary file (v0.10.1 with 
rpc transport)
const imageFile = await sandbox.readFile('/workspace/image.png', { encoding: 'none' });
return new Response(imageFile.content, {
headers: { 'Content-Type': imageFile.mimeType }
});
</TypeScriptExample>
:::note
For more details on the `rpc` transport please see the [Transport](/sandbox/sdk/configuration/transport/) docs.
:::
## Organize files
<TypeScriptExample>
// Create directories
await sandbox.mkdir('/workspace/src', { recursive: true });
await sandbox.mkdir('/workspace/tests', { recursive: true });
// Rename file
await sandbox.renameFile('/workspace/draft.txt', '/workspace/final.txt');
// Move file
await sandbox.moveFile('/tmp/download.txt', '/workspace/data.txt');
// Delete file
await sandbox.deleteFile('/workspace/temp.txt');
</TypeScriptExample>
## Batch operations
Write multiple files in parallel:
<TypeScriptExample>
const files = {
'/workspace/src/app.js': 'console.log("app");',
'/workspace/src/utils.js': 'console.log("utils");',
'/workspace/README.md': '# My Project'
};
await Promise.all(
Object.entries(files).map(([path, content]) =>
sandbox.writeFile(path, content)
)
);
</TypeScriptExample>
## Check if file exists
<TypeScriptExample>
const result = await sandbox.exists('/workspace/config.json');
if (!result.exists) {
// Create default config
await sandbox.writeFile('/workspace/config.json', '{}');
}
// Check directory
const dirResult = await sandbox.exists('/workspace/data');
if (!dirResult.exists) {
await sandbox.mkdir('/workspace/data');
}
// Also available on sessions
const sessionResult = await session.exists('/workspace/temp.txt');
</TypeScriptExample>
## Best practices
- **Use `/workspace`** - Default working directory for app files
- **Use absolute paths** - Always use full paths like `/workspace/file.txt`
- **Batch operations** - Use `Promise.all()` for multiple independent file writes
- **Create parent directories** - Use `recursive: true` when creating nested paths
- **Handle errors** - Check for `FILE_NOT_FOUND` errors gracefully
## Troubleshooting
### Directory doesn't exist
Create parent directories first:
<TypeScriptExample>
// Create directory, then write file
await sandbox.mkdir('/workspace/data', { recursive: true });
await sandbox.writeFile('/workspace/data/file.txt', content);
</TypeScriptExample>
### Binary file encoding
Use `encoding: "none"` (with `rpc` transport) for binary files:
<TypeScriptExample>
// Write binary
await sandbox.writeFile('/workspace/image.png', readableStream);
// Read binary
const file = await sandbox.readFile('/workspace/image.png', {
encoding: 'none'
});
</TypeScriptExample>
For older SDK versions or `http` transport:
<TypeScriptExample>
// Write binary
await sandbox.writeFile('/workspace/image.png', base64data, { encoding: "base64" });
// Read binary
const file = await sandbox.readFile('/workspace/image.png', {
encoding: 'base64'
});
</TypeScriptExample>
### Base64 validation errors
When writing with `encoding: 'base64'`, content must contain only valid base64 characters:
<TypeScriptExample>
try {
// Invalid: contains invalid base64 characters
await sandbox.writeFile('/workspace/data.bin', 'invalid!@#$', {
encoding: 'base64'
});
} catch (error) {
if (error.code === 'VALIDATION_FAILED') {
// Content contains invalid base64 characters
console.error('Invalid base64 content');
}
}
</TypeScriptExample>
## Related resources
- [Files API reference](/sandbox/sdk/api/files/) - Complete method documentation
- [Execute commands guide](/sandbox/sdk/guides/execute-commands/) - Run file operations with commands
- [Git workflows guide](/sandbox/sdk/guides/git-workflows/) - Clone and manage repositories
- [Code Interpreter guide](/sandbox/sdk/guides/code-execution/) - Generate and execute code files

Mount buckets
import { TypeScriptExample, WranglerConfig, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/files/mount-an-r2-bucket/", title: "Mount an R2 bucket" }} />
Mount S3-compatible object storage buckets as local filesystem paths. Access object storage using standard file operations. For Cloudflare R2 in production, you can also mount by Worker R2 binding name so credentials stay in the Worker runtime.
:::caution[Mounting 
/workspace]
Mounting a bucket at 
/workspace or a subpath under it can be confusing in app or project setups. In production, the mount overlays that path instead of merging with files already in the image or template. If you want 
/workspace itself to persist over time, Backup and restore is often a better fit.
:::
:::note[S3-compatible providers]
The SDK works with any S3-compatible object storage provider. Examples include Cloudflare R2, Amazon S3, Google Cloud Storage, Backblaze B2, MinIO, and many others. The SDK automatically detects and optimizes for R2, S3, and GCS.
:::
Production prerequisites for R2 binding mounts
To mount an R2 bucket in production without passing credentials into the container, add an R2 binding and export 
ContainerProxy from your Worker entrypoint.
```toml
[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "my-r2-bucket"
```
```typescript
import { ContainerProxy } from "@cloudflare/sandbox";
export { ContainerProxy };
</TypeScriptExample>
When you omit `endpoint`, the first argument to `mountBucket()` must be the Worker R2 binding name, such as `MY_BUCKET`.
## When to mount buckets
Mount S3-compatible buckets when you need:
- **Persistent data** - Data survives sandbox destruction
- **Large datasets** - Process data without downloading
- **Shared storage** - Multiple sandboxes access the same data
- **Cost-effective persistence** - Cheaper than keeping sandboxes alive
## Mount an R2 bucket
<TypeScriptExample>
```typescript
import { getSandbox } from '@cloudflare/sandbox';
const sandbox = getSandbox(env.Sandbox, 'data-processor');
// Mount R2 bucket by Worker binding name
await sandbox.mountBucket('MY_BUCKET', '/data');
// Access bucket with standard filesystem operations
await sandbox.exec('ls', { args: ['/data'] });
await sandbox.writeFile('/data/results.json', JSON.stringify(results));
// Use from Python
await sandbox.exec('python', { args: ['-c', `
import pandas as pd
df = pd.read_csv('/data/input.csv')
df.describe().to_csv('/data/summary.csv')
`] });
In this example, 
MY_BUCKET is the binding name from 
wrangler.toml. It does not have to match the bucket's dashboard name, although many projects use matching names.
:::note[Mounting affects entire sandbox]
Mounted buckets are visible across all sessions since they share the filesystem. Mount once per sandbox.
:::
Credentials
R2 binding mounts do not require credentials. Remote endpoint mounts remain supported for Cloudflare R2 and other S3-compatible providers, and those flows can still use automatic credential detection or explicit credentials.
Automatic detection
When you include an 
endpoint, set credentials as Worker secrets and the SDK automatically detects them:
npx wrangler secret put R2_ACCESS_KEY_ID
npx wrangler secret put R2_SECRET_ACCESS_KEY
:::note[R2 credentials]
We also automatically detect 
AWS_ACCESS_KEY_ID and 
AWS_SECRET_ACCESS_KEY for compatibility with other S3-compatible providers.
:::
```typescript
// Credentials automatically detected from environment for remote endpoint mounts
await sandbox.mountBucket('my-r2-bucket', '/data', {
	endpoint: 'https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com'
});
```
Explicit credentials
Pass credentials directly when needed:
```typescript
await sandbox.mountBucket('my-r2-bucket', '/data', {
	endpoint: 'https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com',
	credentials: {
		accessKeyId: env.R2_ACCESS_KEY_ID,
		secretAccessKey: env.R2_SECRET_ACCESS_KEY
	}
});
```
Credential proxy
When you mount with explicit credentials, s3fs writes those credentials to a password file on the container's disk. A compromised container process can read and exfiltrate the credentials, or use them to access storage outside the intended bucket scope.
Set 
credentialProxy: true to keep credentials out of the container entirely. Instead of passing real credentials into the container, the Durable Object intercepts all outbound S3 requests at the network layer, re-signs them with the real credentials, and forwards them upstream. The container only ever holds dummy credentials that are useless outside the proxy.
This works with AWS SigV4 signing for S3-compatible endpoints (including R2) and HMAC signing for Google Cloud Storage. It is recommended to set 
credentialProxy: true for all endpoint mounts. The option defaults to 
false for backwards compatibility and will become the default in a future version of the Sandbox SDK.
```typescript
await sandbox.mountBucket('my-bucket', '/data', {
	endpoint: 'https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com',
	provider: 'r2',
	credentials: {
		accessKeyId: env.R2_ACCESS_KEY_ID,
		secretAccessKey: env.R2_SECRET_ACCESS_KEY
	},
	credentialProxy: true
});
```
:::caution[ContainerProxy export required]
Credential proxy mounts use egress interception and require 
ContainerProxy to be exported from your Worker entrypoint. Without this export, the proxy cannot intercept requests and the mount will fail.
import { ContainerProxy } from "@cloudflare/sandbox";
export { ContainerProxy };
:::
Mount bucket subdirectories
Mount a specific subdirectory within a bucket using the 
prefix option. Only contents under the prefix are visible at the mount point:
```typescript
// Mount only the /uploads/images/ subdirectory
await sandbox.mountBucket('MY_BUCKET', '/images', {
	prefix: '/uploads/images/'
});
// Files appear at mount point without the prefix
// Bound bucket: my-r2-bucket/uploads/images/photo.jpg
// Mounted path: /images/photo.jpg
await sandbox.exec('ls', { args: ['/images'] });
// Write to subdirectory
await sandbox.writeFile('/images/photo.jpg', imageData);
// Creates my-r2-bucket/uploads/images/photo.jpg
// Mount different prefixes to different paths
await sandbox.mountBucket('MY_BUCKET', '/training-data', {
prefix: '/ml/training/'
});
await sandbox.mountBucket('MY_BUCKET', '/test-data', {
prefix: '/ml/testing/'
});
</TypeScriptExample>
:::note[Prefix format]
The `prefix` must start with `/` (for example, `/data` or `/logs/2024/`).
:::
## Read-only mounts
Protect data by mounting buckets in read-only mode:
<TypeScriptExample>
```typescript
await sandbox.mountBucket('MY_BUCKET', '/data', {
	readOnly: true
});
// Reads work
await sandbox.exec('cat', { args: ['/data/dataset.csv'] });
// Writes fail
await sandbox.writeFile('/data/new-file.txt', 'data');  // Error: Read-only filesystem
Local development
You can also mount R2 buckets during local development with 
wrangler dev by passing the 
localBucket option. Production R2 binding mounts and local 
localBucket mounts both avoid explicit credentials, but they are different execution paths. Production uses credential-less egress interception and overlays the target path. Local development uses periodic synchronization with the R2 binding.
```typescript
await sandbox.mountBucket('MY_BUCKET', '/data', {
	localBucket: true
});
// Access files using standard operations
await sandbox.exec('ls', { args: ['/data'] });
await sandbox.writeFile('/data/results.json', JSON.stringify(results));
</TypeScriptExample>
:::note
You can use an environment variable to toggle `localBucket` between local development and production. Set an environment variable such as `LOCAL_DEV` in your Wrangler configuration using `vars` for local development, then reference it in your code:
```typescript
const mountOptions = env.LOCAL_DEV ? { localBucket: true } : {};
await sandbox.mountBucket('MY_BUCKET', '/data', mountOptions);
When 
localBucket is 
true, the SDK uses local R2 binding synchronization. When 
localBucket is 
false or omitted and 
endpoint is also omitted, the SDK uses the production R2 binding mount path. For more information on setting environment variables, refer to Environment variables in Wrangler configuration.
:::
The 
readOnly and 
prefix options work the same way in local mode:
```typescript
// Read-only local mount
await sandbox.mountBucket('MY_BUCKET', '/data', {
	localBucket: true,
	readOnly: true
});
// Mount a subdirectory
await sandbox.mountBucket('MY_BUCKET', '/images', {
localBucket: true,
prefix: '/uploads/images/'
});
</TypeScriptExample>
### Local development considerations
During local development, files are synchronized between R2 and the container using a periodic sync process rather than a direct filesystem mount. Keep the following in mind:
- **Synchronization window** - A brief delay exists between when a file is written and when it appears on the other side. For example, if you upload a file to R2 and then immediately read it from the mounted path in the container, the file may not yet be available. Allow a short window for synchronization to complete before reading recently written data.
- **High-frequency writes** - Rapid successive writes to the same file path may take slightly longer to fully propagate. For best results, avoid writing to the same file from both R2 and the container at the same time.
- **Bidirectional sync** - Changes made in the container are synced to R2, and changes made in R2 are synced to the container. Both directions follow the same periodic sync model.
:::note
These considerations apply to local development with `wrangler dev` only. In production, bucket mounts use a direct filesystem mount with no synchronization delay. Local sync-style behavior may not fully reflect how a production mount overlays the target path.
:::
## Unmount buckets
<TypeScriptExample>
```typescript
// Mount for processing
await sandbox.mountBucket('MY_BUCKET', '/data');
// Do work
await sandbox.exec('python process_data.py');
// Clean up
await sandbox.unmountBucket('/data');
:::note[Automatic cleanup]
Mounted buckets are automatically unmounted when the sandbox is destroyed. Manual unmounting is optional.
:::
Other providers
The SDK supports any S3-compatible object storage. Here are examples for common providers:
Amazon S3
```typescript
await sandbox.mountBucket('my-s3-bucket', '/data', {
	endpoint: 'https://s3.us-west-2.amazonaws.com',
	credentials: {
		accessKeyId: env.AWS_ACCESS_KEY_ID,
		secretAccessKey: env.AWS_SECRET_ACCESS_KEY
	}
});
```
Google Cloud Storage
```typescript
await sandbox.mountBucket('my-gcs-bucket', '/data', {
	endpoint: 'https://storage.googleapis.com',
	credentials: {
		accessKeyId: env.GCS_ACCESS_KEY_ID,
		secretAccessKey: env.GCS_SECRET_ACCESS_KEY
	}
});
```
:::note[GCS requires HMAC keys]
Generate HMAC keys in GCS console under Settings > Interoperability.
:::
Other S3-compatible providers
For providers like Backblaze B2, MinIO, Wasabi, or others, use the standard mount pattern:
```typescript
await sandbox.mountBucket('my-bucket', '/data', {
	endpoint: 'https://s3.us-west-000.backblazeb2.com',
	credentials: {
		accessKeyId: env.ACCESS_KEY_ID,
		secretAccessKey: env.SECRET_ACCESS_KEY
	}
});
```
For provider-specific configuration, see the s3fs-fuse wiki for supported providers and recommended flags.
Troubleshooting
R2 binding not found error
Error: 
R2 binding "MY_BUCKET" not found in Worker env
Solution: Ensure your Worker has an 
r2_buckets binding and that 
mountBucket() uses the binding name, not the bucket's dashboard name:
```toml
[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "my-r2-bucket"
```
Credential-less R2 mount fails immediately
Solution: Ensure your Worker entrypoint exports 
ContainerProxy. If you are using an older Wrangler version, you may also need the 
enable_ctx_exports compatibility flag.
Missing credentials error
Error: 
MissingCredentialsError: No credentials found
Solution: This error only applies when you mount a remote S3-compatible endpoint by setting 
endpoint. Set credentials as Worker secrets:
npx wrangler secret put R2_ACCESS_KEY_ID
npx wrangler secret put R2_SECRET_ACCESS_KEY
or
npx wrangler secret put AWS_ACCESS_KEY_ID
npx wrangler secret put AWS_SECRET_ACCESS_KEY
Mount failed error
Error: 
S3FSMountError: mount failed
Common causes:
Incorrect endpoint URL
Invalid credentials
Missing 
ContainerProxy export, or on older Wrangler versions missing 
enable_ctx_exports
Bucket does not exist
Network connectivity issues
Verify your binding or endpoint configuration:
```typescript
try {
	await sandbox.mountBucket('MY_BUCKET', '/data');
} catch (error) {
	console.error('Mount failed:', error.message);
	// Check binding name, ContainerProxy export, or remote endpoint configuration
}
```
Path already mounted error
Error: 
InvalidMountConfigError: Mount path already in use
Solution: Unmount first or use a different path:
```typescript
// Unmount existing
await sandbox.unmountBucket('/data');
// Or use different path
await sandbox.mountBucket('bucket2', '/storage', { endpoint: '...' });
</TypeScriptExample>
### Slow file access
File operations on mounted buckets are slower than local filesystem due to network latency.
**Solution**: Copy frequently accessed files locally:
<TypeScriptExample>
```typescript
// Copy to local filesystem
await sandbox.exec('cp', { args: ['/data/large-dataset.csv', '/workspace/dataset.csv'] });
// Work with local copy (faster)
await sandbox.exec('python', { args: ['process.py', '/workspace/dataset.csv'] });
// Save results back to bucket
await sandbox.exec('cp', { args: ['/workspace/results.json', '/data/results/output.json'] });
Best practices
Mount early - Mount buckets at sandbox initialization
Choose the right mount mode - Use R2 binding mounts when you want Worker-managed R2 access, or use 
endpoint for explicit R2, S3, GCS, and other S3-compatible providers
Secure credentials - Always use Worker secrets, never hardcode
Read-only when possible - Protect data with read-only mounts
Mount the narrowest path - Use prefixes to expose only the data a sandbox needs
Mount paths - Prefer 
/data, 
/storage, or 
/mnt/*; if you mount under 
/workspace, account for the mount overlaying that path in production
Handle errors - Wrap mount operations in 
try...catch blocks
Optimize access - Copy frequently accessed files locally
Related resources
Persistent storage tutorial - Complete R2 example
Backup and restore - Persist a project directory such as 
/workspace
Storage API reference - Full method documentation
Environment variables - Credential configuration for remote endpoint mounts
Wrangler configuration - Configure R2 bindings and compatibility flags
R2 documentation - Learn about Cloudflare R2
Outbound traffic - Learn how 
ContainerProxy and outbound interception work

Handle outbound traffic
import { TypeScriptExample, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/network/call-an-authenticated-api/", title: "Call an authenticated API from a sandbox" }} />
Outbound handlers let you intercept and modify HTTP traffic from a sandbox with trusted code.
Use them to:
Allow or deny specific origin destinations
Safely inject authorization headers or tokens
Transparently reroute traffic
Add custom policy on outbound traffic (such as denying specific HTTP requests)
Connect to Workers bindings like KV, R2, and Durable Objects
Block outbound traffic
Use 
enableInternet = false to block public internet access by default:
import { Sandbox } from "@cloudflare/sandbox";
export class MySandbox extends Sandbox {
	enableInternet = false;
}
When 
enableInternet is 
false, only traffic you explicitly allow later on this page through 
allowedHosts or outbound handlers can leave the sandbox. Only ports 
80, 
443, and DNS are available, and DNS queries use Cloudflare's DNS servers.
:::note
enableInternet takes effect when the sandbox starts. Changes to 
outbound handlers and related outbound policies can affect a live-running sandbox without restarting it.
:::
Block or allow traffic by host
You can filter outbound traffic with the 
allowedHosts and 
deniedHosts properties on the Sandbox class.
:::note
Export 
ContainerProxy from your Worker entrypoint for outbound interception to work.
:::
When 
allowedHosts is set, it becomes a deny-by-default allowlist. Any host or IP not in the list is denied, and only matching destinations can reach 
outbound or 
outboundByHost handlers.
allowedHosts and 
deniedHosts also support simple glob patterns where 
* matches any sequence of characters.
By default, a Sandbox allows internet access, and you can set 
deniedHosts to disallow specific hosts or IPs:
import { Sandbox, ContainerProxy } from "@cloudflare/sandbox";
export { ContainerProxy };
export class MySandbox extends Sandbox {
	deniedHosts = ["some-nefarious-website.com", "141.101.64.0/18"];
}
You can also disable internet access by default, but allow specific hosts and IPs:
import { Sandbox, ContainerProxy } from "@cloudflare/sandbox";
export { ContainerProxy };
export class MySandbox extends Sandbox {
	// default internet access to off unless overridden by 'allowedHosts' or outbound proxy
	enableInternet = false;
	// overrides enableInternet = false
	allowedHosts = ["allowed.com"];
}
Define outbound handlers
Outbound handlers are programmable egress proxies that run on the same machine as the sandbox. They have access to all Workers bindings.
Use 
outbound to intercept all outbound HTTP and HTTPS traffic:
import { Sandbox, ContainerProxy } from "@cloudflare/sandbox";
export { ContainerProxy };
export class MySandbox extends Sandbox {}
MySandbox.outbound = async (
	request: Request,
	env: Env,
	ctx: OutboundHandlerContext,
) => {
	if (request.method !== "GET") {
		console.log(`Blocked ${request.method} to ${request.url}`);
		return new Response("Method Not Allowed", { status: 405 });
	}
	return fetch(request);
};
:::note
HTTP requests to the outbound handler remain secure because they run on the same machine as the sandbox. You can upgrade requests to HTTPS from the Worker itself to prevent plain-text traffic from reaching the internet.
:::
Use 
outboundByHost to map specific domain names or IP addresses to handler functions:
import { Sandbox, ContainerProxy } from "@cloudflare/sandbox";
export { ContainerProxy };
export class MySandbox extends Sandbox {}
MySandbox.outboundByHost = {
	"my.worker": async (
		request: Request,
		env: Env,
		ctx: OutboundHandlerContext,
	) => {
		// Run arbitrary Workers logic from this hostname
		return await someWorkersFunction(request.body);
	},
};
Calls to 
http://my.worker from the sandbox invoke the handler, which runs inside the Workers runtime, outside the sandbox.
deniedHosts and 
allowedHosts are evaluated before any outbound handler. If you use 
allowedHosts, include the hostname there for either 
outbound or 
outboundByHost to run. 
outboundByHost handlers take precedence over catch-all 
outbound handlers.
Securely inject credentials
Because outbound handlers run in the Workers runtime — outside the sandbox — they can hold secrets that the sandbox itself never sees. The sandbox makes a plain HTTP request, and the handler attaches the credential before forwarding it to the upstream service.
export class MySandbox extends Sandbox {}
MySandbox.outboundByHost = {
	"github.com": (request: Request, env: Env, ctx: OutboundHandlerContext) => {
		const requestWithAuth = new Request(request);
		requestWithAuth.headers.set("x-auth-token", env.SECRET);
		return fetch(requestWithAuth);
	},
};
This is especially useful for agentic workloads where you cannot fully trust the code running inside the sandbox. With this pattern:
No token is exposed to the sandbox. The secret lives in the Worker's environment and is never passed into the sandbox.
No token rotation inside the sandbox. Rotate the secret in your Worker's environment and every request picks it up immediately.
Per-host and per-instance rules. Combine 
outboundByHost with 
ctx.containerId to scope credentials or permissions to a specific sandbox instance.
Here, 
ctx.containerId looks up a per-instance key from KV:
export class MySandbox extends Sandbox {}
MySandbox.outboundByHost = {
	"my-internal-vcs.dev": async (
		request: Request,
		env: Env,
		ctx: OutboundHandlerContext,
	) => {
		const authKey = await env.KEYS.get(ctx.containerId);
		const requestWithAuth = new Request(request);
		requestWithAuth.headers.set("x-auth-token", authKey);
		return fetch(requestWithAuth);
	},
};
HTTPS traffic
Sandboxes intercept HTTPS traffic only when your class sets 
interceptHttps to 
true. It defaults to 
false, and then 
allowedHosts, 
deniedHosts, and outbound handlers apply to HTTP only. HTTPS requests reach every host while 
enableInternet is 
true, and fail while it is 
false.
import { Sandbox, ContainerProxy } from "@cloudflare/sandbox";
export { ContainerProxy };
export class MySandbox extends Sandbox {
	interceptHttps = true;
	deniedHosts = ["some-nefarious-website.com"];
}
When HTTPS interception is active, an ephemeral CA file is created at 
/etc/cloudflare/certs/cloudflare-containers-ca.crt once the sandbox starts.
The Sandbox runtime makes a best effort to trust this CA automatically regardless of distro. On startup, it checks common system CA bundle locations across major Linux families and configures common CA environment variables so runtimes like Node.js, 
curl, Python 
requests, and Git trust the certificate automatically.
:::note
HTTP communication to the outbound handler is encrypted by the networking stack. For traffic that stays within the Cloudflare Developer Platform, plain HTTP is secure.
:::
Non-HTTP traffic
Outbound handlers only intercept HTTP and HTTPS traffic. Traffic on ports other than 
80 and 
443 is never routed through 
outbound or 
outboundByHost.
If you set 
enableInternet = false, that traffic is denied. DNS queries are the one exception, but they only go to Cloudflare's DNS servers. That prevents using arbitrary DNS destinations for data exfiltration.
Change policies at runtime
Use 
outboundHandlers to define named handlers, then assign them to specific hosts at runtime using 
setOutboundByHost(). You can also apply a handler globally with 
setOutboundHandler().
You can also manage runtime policy with 
setOutboundByHosts(), 
setAllowedHosts(), 
setDeniedHosts(), 
allowHost(), 
denyHost(), 
removeAllowedHost(), and 
removeDeniedHost().
This lets a trusted Worker hold credentials without exposing them to an untrusted sandbox:
import { Sandbox, ContainerProxy } from "@cloudflare/sandbox";
export { ContainerProxy };
export class MySandbox extends Sandbox {}
MySandbox.outboundHandlers = {
	authenticatedGithub: async (
		request: Request,
		env: Env,
		ctx: OutboundHandlerContext,
	) => {
		const githubToken = env.GITHUB_TOKEN;
		return authenticateGitHttpsRequest(request, githubToken, ctx.containerId);
	},
};
Apply handlers to hosts programmatically from your Worker:
import { Sandbox, ContainerProxy, getSandbox } from "@cloudflare/sandbox";
export { ContainerProxy };
export default {
	async fetch(request: Request, env: Env) {
		const sandbox = getSandbox(env.Sandbox, "agent-session");
		// Give the sandbox access to github.com during setup
		await sandbox.setOutboundByHost("github.com", "authenticatedGithub");
		await sandbox.exec("node setup.js");
		// Remove access once setup is complete
		await sandbox.removeOutboundByHost("github.com");
	},
};
Handler precedence
Requests are evaluated in this order:
deniedHosts is checked first. Matching hosts or IPs are denied immediately.
allowedHosts is checked next. When it is set, any host or IP not in the list is denied. Matching hosts continue to outbound handlers, or egress to the public internet if no handler is set.
Instance-level rules set with 
setOutboundByHost() are checked before class-level 
outboundByHost rules.
Per-host handlers always take precedence over catch-all handlers, so 
outboundByHost runs before 
outbound.
Instance-level handlers set with 
setOutboundHandler() are checked before the class-level 
outbound handler.
If no handler matches, the request can still egress to the public internet when it matched 
allowedHosts or 
enableInternet = true. Otherwise, it is denied.
Local development
wrangler dev supports outbound interception. A sidecar process is spawned inside the sandbox's network namespace. It applies 
TPROXY rules to route matching traffic to the local Workerd instance, mirroring production behavior.
Related resources
Connect to Workers bindings — Access KV, R2, Durable Objects, and other bindings from a sandbox
Handle outbound traffic (Containers) — Container SDK API for outbound handlers
Sandbox options — Configure sandbox behavior
Environment variables — Configure secrets and environment variables

Configure preview URLs on a custom domain
import { WranglerConfig, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/previews/serve-previews-on-their-own-hostnames/", title: "Serve previews on their own hostnames" }} />
Set up wildcard DNS, routes, and TLS so 
exposePort() preview URLs work on your domain. To deploy the Worker and sandbox image, refer to Deploy a Sandbox application.
:::note[Only required for preview URLs]
Custom domain setup is only needed if you use 
exposePort() to expose services from sandboxes. If your application does not use 
exposePort(), you can deploy to 
.workers.dev without this configuration.
For public URLs without custom-domain setup, 
sandbox.tunnels is an alternative: quick tunnels for development, named tunnels for stable hostnames in production.
:::
Preview URLs need wildcard DNS because each exposed port gets a unique subdomain: 
https://8080-abc123.yourdomain.com.
The 
.workers.dev domain does not support wildcard subdomains, so preview URLs that must be reachable on a public hostname outside local development need a custom domain.
:::caution[Subdomain depth matters for TLS]
If your Worker runs on a subdomain (for example, 
sandbox.yourdomain.com), preview URLs become second-level wildcards like 
*.sandbox.yourdomain.com. Cloudflare's Universal SSL only covers first-level wildcards (
*.yourdomain.com), so you need a certificate covering 
*.sandbox.yourdomain.com. Without it, preview URLs will fail with TLS handshake errors.
You have three options:
Run the Worker on the apex domain (
yourdomain.com) so preview URLs stay at the first level (
*.yourdomain.com), which Universal SSL covers automatically. This is the simplest option.
Use Advanced Certificate Manager ($10/month) to provision a certificate for 
*.sandbox.yourdomain.com through the Cloudflare dashboard.
Upload a custom certificate from a provider like Let's Encrypt (free). Generate a wildcard certificate for 
*.sandbox.yourdomain.com using the DNS-01 challenge, then upload it via the Cloudflare dashboard under SSL/TLS > Edge Certificates > Custom Certificates. You will need to renew it before expiry.
:::
Prerequisites
Active Cloudflare zone with a domain
Worker that uses 
exposePort()
Wrangler CLI installed
Sandbox app already deployable (Worker + image)
Setup
Create a wildcard DNS record
In the Cloudflare dashboard, go to your domain and create an A record:
Type: A
Name: 
* (wildcard)
IPv4 address: 
192.0.2.0
Proxy status: Proxied (orange cloud)
This routes all subdomains through Cloudflare's proxy. The IP address 
192.0.2.0 is a documentation address (RFC 5737) that Cloudflare recognizes when proxied.
Configure Worker routes
Add a wildcard route to your Wrangler configuration:
```jsonc
{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-sandbox-app",
	"main": "src/index.ts",
	"upload_source_maps": true,
	"compatibility_date": "$today",
	"routes": [
		{
			"pattern": "*.yourdomain.com/*",
			"zone_name": "yourdomain.com"
		}
	]
}
```
Replace 
yourdomain.com with your actual domain. This routes all subdomain requests to your Worker and enables Cloudflare to provision SSL certificates automatically.
Apply the route
Redeploy the Worker so the route configuration takes effect:
npx wrangler deploy
If this deploy also changes your sandbox image or package, follow Deploy a Sandbox application for rollout and package/image pairing. For route-only changes you can still use a normal deploy. Use 
--containers-rollout=none only when you intentionally skip container image and instance updates.
Verify
Test that preview URLs work:
// Extract hostname from request
const { hostname } = new URL(request.url);
const sandbox = getSandbox(env.Sandbox, "test-sandbox");
await sandbox.startProcess("python -m http.server 8080");
const exposed = await sandbox.exposePort(8080, { hostname });
console.log(exposed.url);
// https://8080-test-sandbox.yourdomain.com
Visit the URL in your browser to confirm your service is accessible.
Troubleshooting
CustomDomainRequiredError: Verify your Worker is not deployed only to 
.workers.dev and that the wildcard DNS record and route are configured correctly.
SSL/TLS errors: Wait a few minutes for certificate provisioning. Verify the DNS record is proxied and SSL/TLS mode is set to "Full" or "Full (strict)" in your dashboard. If your Worker is on a subdomain (for example, 
sandbox.yourdomain.com), Universal SSL will not cover the second-level wildcard 
*.sandbox.yourdomain.com. Refer to the TLS caution at the top of this page for options.
Preview URL not resolving: Confirm the wildcard DNS record exists and is proxied. Wait 30–60 seconds for DNS propagation.
Port not accessible: Ensure your service binds to 
0.0.0.0 (not 
localhost) and that 
proxyToSandbox() is called first in your Worker's fetch handler.
For detailed troubleshooting, see the Workers routing documentation.
Related
Deploy a Sandbox application - Deploy Worker and image
Preview URLs - How preview URLs work
Expose services - Patterns for exposing ports
Tunnels API - Zero-config 
*.trycloudflare.com URLs for development
Workers routing - Advanced routing configuration
Cloudflare DNS - DNS management

Proxy requests to external APIs (outdated)
:::caution[Outdated guide]
This guide is outdated. For the current guidance, refer to Handle outbound traffic.
:::

Stream output
import { TypeScriptExample, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/commands/stream-command-output/", title: "Stream command output" }} />
This guide shows you how to handle real-time output from commands, processes, and code execution.
When to use streaming
Use streaming when you need:
Real-time feedback - Show progress as it happens
Long-running operations - Builds, tests, installations that take time
Interactive applications - Chat bots, code execution, live demos
Large output - Process output incrementally instead of all at once
User experience - Prevent users from waiting with no feedback
Use non-streaming (
exec()) for:
Quick operations - Commands that complete in seconds
Small output - When output fits easily in memory
Post-processing - When you need complete output before processing
Stream command execution
Use 
execStream() to get real-time output:
```
import { getSandbox, parseSSEStream, type ExecEvent } from '@cloudflare/sandbox';
const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
const stream = await sandbox.execStream('npm run build');
for await (const event of parseSSEStream(stream)) {
switch (event.type) {
case 'stdout':
console.log(event.data);
break;
case 'stderr':
  console.error(event.data);
  break;
case 'complete':
  console.log('Exit code:', event.exitCode);
  break;
case 'error':
  console.error('Failed:', event.error);
  break;
}
}
</TypeScriptExample>
## Stream to client
Return streaming output to users via Server-Sent Events:
<TypeScriptExample>
import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';
export default {
async fetch(request: Request, env: Env): Promise {
const sandbox = getSandbox(env.Sandbox, 'builder');
const stream = await sandbox.execStream('npm run build');
return new Response(stream, {
  headers: {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache'
  }
});
}
};
</TypeScriptExample>
Client-side consumption:
<TypeScriptExample>
// Browser JavaScript
const eventSource = new EventSource('/build');
eventSource.addEventListener('stdout', (event) => {
const data = JSON.parse(event.data);
console.log(data.data);
});
eventSource.addEventListener('complete', (event) => {
const data = JSON.parse(event.data);
console.log('Exit code:', data.exitCode);
eventSource.close();
});
</TypeScriptExample>
## Stream process logs
Monitor background process output:
<TypeScriptExample>
import { parseSSEStream, type LogEvent } from '@cloudflare/sandbox';
const process = await sandbox.startProcess('node server.js');
const logStream = await sandbox.streamProcessLogs(process.id);
for await (const log of parseSSEStream(logStream)) {
console.log(log.data);
if (log.data.includes('Server listening')) {
console.log('Server is ready');
break;
}
}
</TypeScriptExample>
## Handle errors
Check exit codes and handle stream errors:
<TypeScriptExample>
const stream = await sandbox.execStream('npm run build');
for await (const event of parseSSEStream(stream)) {
switch (event.type) {
case 'stdout':
console.log(event.data);
break;
case 'error':
  throw new Error(`Build failed: ${event.error}`);
case 'complete':
  if (event.exitCode !== 0) {
    throw new Error(`Build failed with exit code ${event.exitCode}`);
  }
  break;
}
}
</TypeScriptExample>
## Best practices
- **Always consume streams** - Don't let streams hang unconsumed
- **Handle all event types** - Process stdout, stderr, complete, and error events
- **Check exit codes** - Non-zero exit codes indicate failure
- **Provide feedback** - Show progress to users for long operations
## Related resources
- [Commands API reference](/sandbox/sdk/api/commands/) - Complete streaming API
- [Execute commands guide](/sandbox/sdk/guides/execute-commands/) - Command execution patterns
- [Background processes guide](/sandbox/sdk/guides/background-processes/) - Process log streaming
- [Code Interpreter guide](/sandbox/sdk/guides/code-execution/) - Stream code execution output

WebSocket connections
import { TypeScriptExample, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
This guide shows you how to work with WebSocket servers running in your sandboxes.
Choose your approach
Expose via preview URL - Get a public URL for external clients to connect to. Best for public chat rooms, multiplayer games, or real-time dashboards.
Connect with wsConnect() - Your Worker establishes the WebSocket connection. Best for custom routing logic, authentication gates, or when your Worker needs real-time data from sandbox services.
Connect to WebSocket echo server
Create the echo server:
Bun.serve({
	port: 8080,
	hostname: "0.0.0.0",
	fetch(req, server) {
		if (server.upgrade(req)) {
			return;
		}
		return new Response("WebSocket echo server");
	},
	websocket: {
		message(ws, message) {
			ws.send(`Echo: ${message}`);
		},
		open(ws) {
			console.log("Client connected");
		},
		close(ws) {
			console.log("Client disconnected");
		},
	},
});
console.log("WebSocket server listening on port 8080");
Extend the Dockerfile:
FROM docker.io/cloudflare/sandbox:0.12.14
# Copy echo server into the container
COPY echo-server.ts /workspace/echo-server.ts
# Create custom startup script
COPY startup.sh /container-server/startup.sh
RUN chmod +x /container-server/startup.sh
Create startup script:
#!/bin/bash
# Start your WebSocket server in the background
bun /workspace/echo-server.ts &
# Start SDK's control plane (needed for the SDK to work)
exec bun dist/index.js
Connect from your Worker:
```ts
import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from "@cloudflare/sandbox";
export default {
async fetch(request: Request, env: Env): Promise {
if (request.headers.get('Upgrade')?.toLowerCase() === 'websocket') {
const sandbox = getSandbox(env.Sandbox, 'echo-service');
return await sandbox.wsConnect(request, 8080);
}
return new Response('WebSocket endpoint');
}
};
</TypeScriptExample>
**Client connects:**
```javascript
const ws = new WebSocket('wss://your-worker.com');
ws.onmessage = (event) => console.log(event.data);
ws.send('Hello!'); // Receives: "Echo: Hello!"
Expose WebSocket service via preview URL
Get a public URL for your WebSocket server:
```ts
import { getSandbox, proxyToSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';
export default {
async fetch(request: Request, env: Env): Promise {
// Auto-route all requests via proxyToSandbox first
const proxyResponse = await proxyToSandbox(request, env);
if (proxyResponse) return proxyResponse;
// Extract hostname from request
const { hostname } = new URL(request.url);
const sandbox = getSandbox(env.Sandbox, 'echo-service');
// Expose the port to get preview URL
const { url } = await sandbox.exposePort(8080, { hostname });
// Return URL to clients
if (request.url.includes('/ws-url')) {
  return Response.json({ url: url.replace('https', 'wss') });
}
return new Response('Not found', { status: 404 });
}
};
</TypeScriptExample>
:::note[Alternative: quick tunnels]
Quick tunnels also handle WebSocket upgrades and do not require a custom domain, so they work on `.workers.dev`. Swap `sandbox.exposePort(8080, { hostname })` for `sandbox.tunnels.get(8080)` to get a `*.trycloudflare.com` URL.
:::
**Client connects to preview URL:**
```javascript
// Get the preview URL
const response = await fetch('https://your-worker.com/ws-url');
const { url } = await response.json();
// Connect
const ws = new WebSocket(url);
ws.onmessage = (event) => console.log(event.data);
ws.send('Hello!'); // Receives: "Echo: Hello!"
Connect from Worker to get real-time data
Your Worker can connect to a WebSocket service to get real-time data, even when the incoming request isn't a WebSocket:
```ts
import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';
let initialized = false;
export default {
async fetch(request: Request, env: Env): Promise {
 // Get or create a sandbox instance
const sandbox = getSandbox(env.Sandbox, 'data-processor');
// Check for WebSocket upgrade
const upgrade = request.headers.get('Upgrade')?.toLowerCase();
if (upgrade === 'websocket') {
  // Initialize server on first connection
  if (!initialized) {
    await sandbox.writeFile(
      '/workspace/server.js',
      `Bun.serve({
        port: 8080,
        fetch(req, server) {
          server.upgrade(req);
        },
        websocket: {
          message(ws, msg) {
            ws.send(\`Echo: \${msg}\`);
          }
        }
      });`
    );
    await sandbox.startProcess(
      'bun /workspace/server.js'
    );
    initialized = true;
  }
  // Connect to WebSocket server
  return await sandbox.wsConnect(request, 8080);
}
return new Response('Processed real-time data');
}
};
</TypeScriptExample>
This pattern is useful when you need streaming data from sandbox services but want to return HTTP responses to clients.
## Troubleshooting
### Upgrade failed
Verify request has WebSocket headers:
<TypeScriptExample>
```ts
console.log(request.headers.get('Upgrade'));    // 'websocket'
console.log(request.headers.get('Connection')); // 'Upgrade'
Local development
Expose ports in Dockerfile for 
wrangler dev:
FROM docker.io/cloudflare/sandbox:0.12.14
COPY echo-server.ts /workspace/echo-server.ts
COPY startup.sh /container-server/startup.sh
RUN chmod +x /container-server/startup.sh
# Required for local development
EXPOSE 8080
:::note
Port exposure in Dockerfile is only required for local development. In production, all ports are automatically accessible.
:::
Related resources
Ports API reference - Complete API documentation
Preview URLs concept - How preview URLs work
Tunnels API - Zero-config 
*.trycloudflare.com URLs for WebSocket services in development
Background processes guide - Managing long-running services

Connect to Workers bindings
import { TypeScriptExample, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
Sandboxes can access Workers bindings — KV, R2, D1, Durable Objects, and others — through outbound handlers. An outbound handler intercepts HTTP requests from the sandbox and runs inside the Workers runtime, where all of your configured bindings are available.
The sandbox makes a plain HTTP request to a virtual hostname (for example, 
http://my.kv/some-key), and the outbound handler resolves it using the bound resource. No SDK or client library is required inside the sandbox.
Use bindings in outbound handlers
Define an 
outboundByHost handler for each virtual hostname. The 
env argument gives you access to every binding declared in your Wrangler configuration.
export class MySandbox extends Sandbox {}
MySandbox.outboundByHost = {
	"my.kv": async (request: Request, env: Env, ctx: OutboundHandlerContext) => {
		const url = new URL(request.url);
		const key = url.pathname.slice(1);
		const value = await env.KV.get(key);
		return new Response(value ?? "", { status: value ? 200 : 404 });
	},
	"my.r2": async (request: Request, env: Env, ctx: OutboundHandlerContext) => {
		const url = new URL(request.url);
		// Scope access to this sandbox's ID
		const path = `${ctx.containerId}${url.pathname}`;
		const object = await env.R2.get(path);
		return new Response(object?.body ?? null, { status: object ? 200 : 404 });
	},
};
The sandbox calls 
http://my.kv/some-key and the handler resolves it using the KV binding. A call to 
http://my.r2/file.png reads from R2, scoped to the current sandbox instance.
:::note
You can use 
ctx.containerId to apply different rules per sandbox instance — for example, to look up per-instance configuration from KV.
:::
Access Durable Object state
The 
ctx argument exposes 
containerId, which lets you interact with the sandbox's own Durable Object from an outbound handler.
export class MySandbox extends Sandbox {}
MySandbox.outboundByHost = {
	"get-state.do": async (
		request: Request,
		env: Env,
		ctx: { containerId: string },
	) => {
		const id = env.MY_SANDBOX.idFromString(ctx.containerId);
		const stub = env.MY_SANDBOX.get(id);
		// Assumes getStateForKey is defined on your DO
		return stub.getStateForKey(request.body);
	},
};
Related resources
Handle outbound traffic — Block, allow, and intercept all outbound HTTP from a sandbox
Sandbox options — Configure sandbox behavior
Environment variables — Configure secrets and environment variables

Sandbox SDK 0.x API map
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:
0.12
Kind
Replacement
Notes
allowedHosts, 
deniedHosts, 
outbound, 
outboundByHost, 
outboundHandlers, 
outboundProxies, 
outboundProxy
Pattern
A 
WorkerEntrypoint that applies the rules in the 0.12 order
Handlers take 
(request, env, params). Refer to Apply the rules in an entrypoint.
outboundByHost handlers that read Workers bindings
Pattern
A 
WorkerEntrypoint for each hostname
Refer to Reach Workers bindings from the container.
interceptHttps
Native
container.interceptOutboundHttps("*", fetcher) for every sandbox
Add the certificate to the system bundle, and set 
NODE_EXTRA_CA_CERTS and 
REQUESTS_CA_BUNDLE. 0.12 checked HTTPS only with 
interceptHttps = true. Refer to What changes for requests.
setAllowedHosts(), 
setDeniedHosts(), 
allowHost(), 
denyHost(), 
removeAllowedHost(), 
removeDeniedHost(), 
setOutboundHandler(), 
setOutboundByHost(), 
setOutboundByHosts(), 
removeOutboundByHost()
Pattern
Methods that update the 
OUTBOUND_CONFIGURATION key and register the entrypoint again
Rules that 0.12 stored keep applying. Refer to Replace the runtime setters.
ContainerProxy
Removed
Export your own entrypoint
Remove it from the exports of your Worker.
gitCheckout()
Pattern
exec() of 
git clone --filter=blob:none in 
/workspace
Refer to Replace gitCheckout(). For private repositories, refer to Clone a private repository.
Bucket mounts
For the steps, refer to Move bucket mounts. These APIs mount object storage in the container:
0.12
Kind
Replacement
Notes
mountBucket() with an S3 endpoint
Package
S3Mount.mount(), with 
S3Gateway exported from your Worker
Credentials stay in the Worker. Refer to Mount the bucket.
mountBucket() with an R2 binding
Package
S3Mount.mount() with the R2 S3 endpoint
Needs an R2 API token for the bucket. 1.0 cannot mount through a binding.
prefix, 
readOnly, 
s3fsOptions
Package
keyPrefix, 
access, 
s3fsOptions
keyPrefix has no leading 
/, 
access is required, and 
s3fsOptions is an object.
credentials, 
R2_* and 
AWS_* variables
Package
source.credentials
Not read from the environment.
credentialProxy, 
provider
Removed
Not needed
S3Gateway signs every request. 
S3Mount always sets 
nomixupload, which 0.12 added only for R2.
localBucket
Package
S3Mount under 
wrangler dev with a local S3-compatible server
Needs Wrangler 4.137.0 or later. Refer to Replace localBucket.
unmountBucket()
Package
S3Mount.unmount()
Throws 
S3_MOUNT_BUSY while a process uses the path.
BucketMountError, 
BucketUnmountError, 
InvalidMountConfigError, 
MissingCredentialsError, 
S3FSMountError
Package
SandboxS3MountError
An invalid request throws 
TypeError.
Mounts next to outbound rules
Pattern
Mount before 
interceptAllOutboundHttp()
A mount registered after the catch-all intercept fails. Refer to If you moved outbound rules.
Backups
For the steps, refer to Move backups. These APIs save and restore directories:
0.12
Kind
Replacement
Notes
createBackup(), 
restoreBackup()
Package
DirectoryBackup 
backup() and 
restore()
Your Durable Object stores the record. For the whole filesystem, use 
container.snapshotContainer().
name, 
gitignore
Package
The 
DirectoryBackup options with the same names
gitignore does not need 
git in the image.
excludes
Package
exclude
.gitignore syntax. A pattern that starts with 
**/ matches at any depth, as 0.12 patterns did.
ttl
Pattern
An expiry time stored in the bucket next to the backup
0.12 refused expired restores and kept the objects.
multipart, 
localBucket, 
compression
Removed
Not needed
Every backup goes through the R2 binding in parts.
BACKUP_BUCKET
Native
An R2 binding
Pass its name as the 
binding of 
DirectoryBackup.
BACKUP_BUCKET_NAME, 
BACKUP_BUCKET_ENDPOINT, R2 access keys
Removed
The R2 binding
The container never holds bucket credentials.
BackupNotFoundError
Package
SandboxBackupError with the code 
BACKUP_NOT_FOUND
BackupExpiredError
Pattern
The error that your expiry check throws
InvalidBackupConfigError
Removed
TypeError
BackupCreateError, 
BackupRestoreError
Package
SandboxFileError or 
SandboxBackupError
Refer to DirectoryBackup errors.
Backups made by 0.12
Pattern
unsquashfs on 
backups/<id>/data.sqsh, then 
backup()
Refer to Convert backups that 0.12 created.
Code interpreter and subpath packages
These APIs came from the code interpreter and the subpath exports of the package:
0.12
Kind
Replacement
Notes
runCode(), 
createCodeContext(), 
listCodeContexts(), 
deleteCodeContext(), 
CodeInterpreter
Pattern
An IPython kernel for each context, or a Dynamic Worker for JavaScript
Refer to Replace the code interpreter.
runCodeStream(), 
onStdout, 
onStderr, 
onResult
Pattern
A command with 
python3 - and its 
stdout
Refer to Replace streaming output.
@cloudflare/sandbox/opencode, 
createOpencode(), 
createOpencodeServer(), 
OpencodeOptions, 
OpencodeResult, 
OpencodeServer, 
OpencodeStartupError
Pattern
opencode serve and an OpenCode SDK client
Refer to Start an OpenCode server.
proxyToOpencode(), 
proxyToOpencodeServer()
Pattern
fetch() in your Durable Object, which forwards to the server port
Refer to Start an OpenCode server.
@cloudflare/sandbox/openai, 
Shell, 
Editor, 
CommandResult, 
FileOperationResult
Pattern
Your own 
Shell and 
Editor
ShellResult and 
ApplyPatchResult from 
@openai/agents replace the result types. Refer to Give OpenAI agents a shell and an editor.
@cloudflare/sandbox/bridge, 
bridge(), 
resolveWorkspacePath(), 
shellQuote(), 
BridgeConfig, 
BridgeEnv, 
WorkerHandlers
Pattern
Your own Worker routes
Refer to Replace the bridge.
WarmPool, 
WarmPoolConfig, 
PoolStats
Removed
Start each sandbox when a request needs it
Refer to Remove WarmPool.
Images
0.12 published container images for the 
Sandbox class to build on:
0.12
Kind
Replacement
Notes
cloudflare/sandbox, 
-python, 
-opencode, and 
-musl images
Removed
Your own 
linux/amd64 image
Copy 
sandbox-shim into it if you use 
Files, 
S3Mount, or 
DirectoryBackup. Refer to Requirements.
docker:dind-rootless with 
USER root
Pattern
docker:dind with 
--ip-forward=false
Refer to Run Docker inside the sandbox.
Errors and clients
These APIs report failures and talk to the container:
0.12
Kind
Replacement
Notes
ContainerUnavailableError, 
OperationInterruptedError, 
RPCTransportError, 
SessionTerminatedError
Removed
Native errors from 
container
Not wrapped.
ProcessExitedBeforeReadyError, 
ProcessReadyTimeoutError
Pattern
The results of your readiness check
Refer to Preview a web application.
isPlatformTransientError(), 
isDurableObjectCodeUpdateReset()
Removed
error.retryable and 
error.overloaded
Retry idempotent calls with a new stub when 
retryable is 
true, and never when 
overloaded is 
true. The package does not retry. Refer to Error handling.
SandboxClient, 
BackupClient, 
CommandClient, 
FileClient, 
GitClient, 
InterpreterClient, 
PortClient, 
ProcessClient, 
UtilityClient
Removed
container and 
Files
Call them from your Durable Object.
SANDBOX_LOG_LEVEL, 
SANDBOX_LOG_FORMAT
Removed
Your own logs
The package does not log. Log from your Worker and read the logs in Workers Logs.
Types
These 0.12 types describe the options and results of the methods in the earlier sections. Each type goes where its method goes:
0.12
Kind
Replacement
Notes
SandboxOptions, 
SandboxTransport, 
ISandbox, 
ContainerStub
Removed
Your class
Refer to Class, identity, and lifetime.
BaseExecOptions, 
ExecOptions, 
StreamOptions, 
ExecResult, 
ExecEvent, 
ExecuteRequest, 
CommandExecuteResponse, 
CommandsResponse
Native
ContainerExecOptions, 
ExecProcess, 
ExecOutput
wrangler types generates them.
PtyOptions
Native
ContainerExecPtyOptions
Pass it as 
pty to 
container.exec(). The shell goes in the command.
SessionOptions, 
SessionRequest, 
CreateSessionRequest, 
CreateSessionResponse, 
DeleteSessionRequest, 
DeleteSessionResponse
Removed
cwd and 
env on each call
ProcessOptions, 
ProcessStatus, 
ProcessStartResult, 
ProcessListResult, 
ProcessInfoResult, 
ProcessKillResult, 
ProcessLogsResult, 
ProcessCleanupResult, 
StartProcessRequest, 
WaitForLogResult, 
WaitForPortOptions
Pattern
The types of your process methods
Refer to Move background processes.
ReadFileRequest, 
WriteFileRequest, 
FileOperationRequest, 
MkdirRequest, 
ListFilesOptions
Package
FileOperationOptions, 
MkdirOptions, 
RemoveOptions, 
FileContent
FileMetadata, 
FileChunk, 
FileStreamEvent
Removed
The 
Response from 
files.readFile()
WatchOptions, 
FileWatchSSEEvent, 
CheckChangesOptions, 
CheckChangesResult
Pattern
The events that your 
inotifywait reader returns
Refer to Replace file watching.
TunnelOptions, 
TunnelInfo, 
QuickTunnelInfo, 
NamedTunnelInfo
Pattern
The types of your tunnel methods
Refer to Move tunnels.
GitCheckoutRequest, 
GitCheckoutResult
Pattern
The arguments and output of your 
git clone command
Refer to Replace gitCheckout().
MountBucketOptions, 
RemoteMountBucketOptions, 
LocalMountBucketOptions, 
BucketCredentials, 
BucketProvider
Package
S3MountRequest
BackupOptions, 
DirectoryBackup, 
RestoreBackupResult
Package
DirectoryBackupOptions, 
DirectoryBackupRecord, 
DirectoryRestoreOptions
DirectoryBackupRecord adds 
size, 
name, 
sha256, and 
format, and drops 
localBucket. 
restore() returns nothing. In 1.0, 
DirectoryBackup is the class that saves and restores backups.
CodeContext, 
CreateContextOptions, 
RunCodeOptions, 
ExecutionCallbacks, 
ExecutionResult
Pattern
The 
CodeContext and 
Execution types of your kernel
Refer to Replace the code interpreter.
ContainerUnavailableContext, 
ContainerUnavailableReason, 
OperationInterruptedContext, 
OperationInterruptedReason, 
RPCTransportContext, 
RPCTransportErrorKind
Removed
Not needed
Their errors are removed.
SandboxClientOptions, 
RequestConfig, 
ResponseHandler, 
BaseApiResponse, 
ErrorResponse, 
PingResponse
Removed
Not needed
The clients are removed.

Move background processes
import { Steps } from "~/components";
In Sandbox SDK 0.12, 
startProcess() returns a 
Process object, and the container keeps a table of processes that later requests query. In 1.0, your Durable Object keeps a directory in the container for each process. Each 
Process method becomes a Durable Object method that takes the process ID.
Before you start
Your 1.0 class replaces the 0.12 
Sandbox class, and has the 
container getter, the 
ensureRunning() method, and the 
ENV and 
INACTIVITY_TIMEOUT_MS constants from Replace the Sandbox class.
This page replaces 
startProcess(), the 
Process methods, 
listProcesses(), 
getProcess(), 
getProcessLogs(), 
streamProcessLogs(), 
killProcess(), 
killAllProcesses(), 
cleanupCompletedProcesses(), and the process callbacks. It does not cover commands that finish while the request is open. For those, refer to Change command calls.
Add the process methods
Add the scripts and methods from Run background processes to your class, including the alarm handler, and 
follow() and 
waitForLog() from Follow a background process.
A Durable Object has one alarm. If your class already has an 
alarm() handler, such as the one from Move every sandbox in one deploy, merge the process checks into it rather than adding a second.
Change 
startProcess() to start the container with 
ensureRunning(), and to run each process with the working directory and environment that 0.12 gave it:
export class MySandbox extends DurableObject<Env> {
	// ...
	async startProcess(id: string, argv: string[]): Promise<boolean> {
		await this.ensureRunning();
		// mkdir fails when another process already uses the ID.
		const dir = `${ROOT}/${id}`;
		await run(this.container, ["mkdir", "-p", ROOT]);
		const created = await run(this.container, ["mkdir", dir]);
		if (created.exitCode !== 0) {
			return false;
		}
		// Ignoring the output lets the process outlive this request.
		const command = ["sh", "-c", RUN, "sh", dir, ...argv];
		await this.container.exec(command, {
			cwd: "/workspace",
			env: ENV,
			stdout: "ignore",
			stderr: "ignore",
		});
		// exec() returns before the process records its ID. Wait for it, so
		// a request that follows the output right away finds it running.
		for (let i = 0; i < 50; i++) {
			if ((await this.status(id))?.state !== "starting") break;
			await scheduler.wait(100);
		}
		await this.ctx.storage.put(`process:${id}`, argv);
		await this.ctx.storage.setAlarm(Date.now() + 60_000);
		return true;
	}
}
0.12 ran each process in 
/workspace, with the variables from 
envVars. 
exec() starts in 
/, even when the image sets 
WORKDIR. It does not inherit the variables that 
start() sets, except 
PATH.
Remove 
INACTIVITY_TIMEOUT_MS from the scripts that you added in step 1. Your class file already defines it, so the constructor and the alarm handler keep the inactivity timeout of your class.
On this page, 
sandbox is the stub that 
getByName() returns.
Start processes
0.12 ran each command string in 
bash. To keep a string, run it with 
["bash", "-c", command]:
const process = await sandbox.startProcess("npm run dev", {
	processId: "dev",
});
const started = await sandbox.startProcess("dev", [
	"bash",
	"-c",
	"npm run dev",
]);
Each process needs an ID. Where 0.12 generated one, such as 
proc_1790379992394_6snsuw, use 
crypto.randomUUID(). The ID becomes a directory name, so use only characters that are safe in a path.
startProcess() returns 
false when a process already uses the ID. 0.12 replaced the record instead, and the first process kept running without one. An ended process keeps its directory, so 
startProcess() also returns 
false for its ID. To start that ID again, delete the directory first, as Stop processes describes.
python3 -m http.server, which 0.12 ran as a preview server, exits on startup in a 1.0 container. For the cause and a replacement, refer to The hostname is longer than a DNS label.
Remove the 
timeout option, which did not stop a background process in 0.12. To limit how long a process runs, start it with the 
timeout command, such as 
["timeout", "300", "npm", "test"]. The command exits with code 
124 when the time passes, or 
137 with 
--kill-after when the process ignores 
SIGTERM.
For the 
sessionId option, refer to Replace sessions.
Check and list processes
Replace 
getProcess() and 
Process.getStatus() with 
status(), which returns 
undefined for an ID that no process uses. Each 0.12 status maps to a 1.0 state:
0.12 status
1.0 state
starting
starting
running
running, with 
pid
completed
exited, with 
exitCode 
0
failed
exited, with another 
exitCode
killed
exited, with 
exitCode 
143 after 
SIGTERM or 
137 after 
SIGKILL
error
startProcess() throws
—
lost, when the process ended without recording an exit code
To replace 
listProcesses(), add a method that lists the process directories:
export class MySandbox extends DurableObject<Env> {
	// ...
	async listProcesses(): Promise<{ id: string; status: Status }[]> {
		if (!this.container.running) {
			return [];
		}
		const { stdout } = await run(this.container, ["ls", ROOT]);
		const processes = [];
		for (const id of stdout.split("\n").filter((line) => line !== "")) {
			const status = await this.status(id);
			if (status) {
				processes.push({ id, status });
			}
		}
		return processes;
	}
}
The directories stay until you delete them, as ended processes stayed in the 0.12 table. The alarm deletes the 
process: key of an ended process within a minute, so list the directories to find ended processes.
Read logs
Replace 
getProcessLogs() and 
Process.getLogs() with a 
logs() call for each stream:
const { stdout, stderr } = await sandbox.getProcessLogs("dev");
const stdout = await sandbox.logs("dev", "stdout");
const stderr = await sandbox.logs("dev", "stderr");
Replace 
streamProcessLogs() with 
follow(). It returns a 
Response that follows one stream until the process exits, then sends an 
exit event with the exit code.
0.12 sent events without a name, each with a 
LogEvent object in its 
data field. 
follow() names each event 
stdout, 
stderr, or 
exit. The 
data field of an output event holds a JSON-encoded chunk of output, and the 
data field of the 
exit event holds 
{ "exitCode": <CODE> }. Replace 
parseSSEStream() with a listener for each event name, or read the 
event line of each event and 
JSON.parse() its 
data field.
Wait for output or exit
Replace 
Process.waitForLog() with 
waitForLog(). It returns a state, where 0.12 threw an error:
const { line } = await process.waitForLog("ready.", 30_000);
const result = await sandbox.waitForLog(
	"dev",
	literal("ready."),
	30_000,
);
if (result?.state !== "matched") {
	throw new Error(`The server did not start: ${result?.state}`);
}
The state is 
timed-out where 0.12 threw 
ProcessReadyTimeoutError, and 
exited where it threw 
ProcessExitedBeforeReadyError.
The pattern is a 
grep -E extended regular expression. 0.12 matched a string pattern as written, so pass each string pattern through a function that escapes it:
// Escapes a 0.12 string pattern, so that it matches as written.
function literal(text: string): string {
	return text.replace(/[\\^$.|?*+()[\]{}]/g, "\\$&");
}
Without it, the pattern 
[ok] matches any line that contains 
o or 
k. Pass a 0.12 
RegExp as its 
source, and replace 
\d with 
[0-9], which 
grep requires.
To replace 
Process.waitForExit(), add a method that checks the status until the process ends:
export class MySandbox extends DurableObject<Env> {
	// ...
	async waitForExit(id: string, timeoutMs: number) {
		const deadline = Date.now() + timeoutMs;
		let status = await this.status(id);
		while (
			(status?.state === "running" || status?.state === "starting") &&
			Date.now() < deadline
		) {
			await scheduler.wait(500);
			status = await this.status(id);
		}
		return status;
	}
}
When 
timeoutMs passes first, the method returns the state 
running or 
starting.
Replace 
Process.waitForPort() with requests to the port, as in Preview a web application.
Stop processes
Replace 
Process.kill() and 
killProcess() with 
stop():
await sandbox.killProcess("dev");
await sandbox.stop("dev");
stop() sends 
SIGTERM to the process group, which reaches the processes that the command started. 0.12 sent 
SIGKILL 5 seconds later to any process still running, and ignored the 
signal argument. To stop a process that ignores 
SIGTERM, change 
TERM to 
KILL in 
stop().
Replace 
killAllProcesses() with a 
stop() call for each running process that 
listProcesses() returns. Remove 
cleanupCompletedProcesses() and the 
autoCleanup option, which did nothing in 0.12. To delete the directory of an ended process, run 
rm -rf on it.
Replace callbacks
The alarm from Run background processes checks each process every minute, and keeps the container running while any process runs. Each 0.12 callback moves to your own code:
0.12
1.0
onStart
Your code after 
startProcess() returns 
true.
onOutput
follow(), or 
logs() for the output so far.
onExit
The 
process.ended branch of the alarm, within a minute of the exit. For the exit at once, call 
waitForExit().
onError
A 
startProcess() call that throws or returns 
false.
Start processes again after the switch
1.0 does not see processes that 0.12 started. 
status() returns 
undefined for their IDs, and 
listProcesses() leaves them out. The 0.12 process table ends with its container. Start each process that your application needs after the switch, such as in the method that first calls 
ensureRunning().
Check the processes
After you deploy the switch, start a process with the ID of a 0.12 process, such as 
dev. 
startProcess() returns 
true, and 
status("dev") reports it:
{ "state": "running", "pid": 142 }
logs("dev", "stdout") returns the output from 
/workspace, with the variables from 
ENV. After 
stop("dev"), 
listProcesses() returns the exit code:
[{ "id": "dev", "status": { "state": "exited", "exitCode": 143 } }]
Related resources
Run background processes
Change command calls
Sandbox lifetime
Durable Object alarms

Move backups
import { PackageManagers, Steps, WranglerConfig } from "~/components";
Replace 0.12 
createBackup() and 
restoreBackup() with Durable Object methods of the same names, built on 
DirectoryBackup. Your Worker calls them with the same options, and backups keep the 0.12 time to live. 
DirectoryBackup saves the directory to the same 
BACKUP_BUCKET binding as a compressed archive, and restores it as ordinary files. 0.12 saved a SquashFS image and mounted it over the directory. Backups that 0.12 created convert to 1.0 backups the first time you restore them.
To save the whole filesystem instead of one directory, use a Container snapshot. For more information, refer to Save and restore a sandbox with snapshots.
Before you start
Your 1.0 class replaces the 0.12 
Sandbox class. On this page it is 
MySandbox, with the 
container getter and the 
ensureRunning() and 
startContainer() methods from Replace the Sandbox class.
This page replaces 
createBackup(), 
restoreBackup(), their options, and the backup errors. 
DirectoryBackup reaches R2 through 
this.ctx.exports, which is 
undefined before compatibility date 
2025-11-17, unless you add the 
enable_ctx_exports compatibility flag.
Replace the backup calls
Install the package, if your Worker does not use it yet:
Copy the helper binary into your image, if the 
Dockerfile does not copy it yet:
COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim
Use the 
cloudflare/sandbox tag that matches the installed package version.
Keep the R2 binding named 
BACKUP_BUCKET, and point it at the bucket that 0.12 wrote to. With presigned uploads, that is the bucket in 
BACKUP_BUCKET_NAME:
{
	"r2_buckets": [
		{
			"binding": "BACKUP_BUCKET",
			"bucket_name": "my-sandbox-backups",
		},
	],
}
After you delete the 0.12 class, remove 
BACKUP_BUCKET_NAME and 
BACKUP_BUCKET_ENDPOINT from your variables, and 
R2_ACCESS_KEY_ID and 
R2_SECRET_ACCESS_KEY from your secrets unless a bucket mount uses them. The container never receives bucket credentials for backups in 1.0.
Add these declarations to the top level of 
src/index.ts:
import {
	DirectoryBackup,
	type DirectoryBackupRecord,
} from "@cloudflare/sandbox";
// Gives the Durable Object this.ctx.exports.DirectoryBackupGateway,
// which moves each backup between the container and the bucket
export { DirectoryBackupGateway } from "@cloudflare/sandbox";
// 0.12 kept a backup for three days unless you set ttl.
const DEFAULT_TTL_SECONDS = 3 * 24 * 60 * 60;
// The record your code stores in place of the 0.12 backup object.
type Backup = DirectoryBackupRecord & { expiresAt: number };
// Restores read the expiry time from this object, because a caller
// can change the expiresAt field of a record.
const metaKey = (id: string) => `backups/${id}.meta.json`;
// Like 0.12, refuse a backup that expires within a minute.
const EXPIRY_MARGIN_MS = 60 * 1000;
Add a 
DirectoryBackup field to 
MySandbox:
export class MySandbox extends DurableObject<Env> {
	// ...
	private readonly backups = new DirectoryBackup(
		this.container,
		this.ctx.exports.DirectoryBackupGateway,
		{ binding: "BACKUP_BUCKET", prefix: "backups/" },
	);
}
this.ctx.container stays the same object for as long as the Durable Object runs, so one 
DirectoryBackup object serves every container that the Durable Object starts.
If 
startContainer() registers a catch-all with 
interceptAllOutboundHttp(), as Move outbound rules sets up, call 
await this.backups.intercept() in the 
try block of 
startContainer(), before the catch-all. Otherwise the catch-all receives backup traffic from the container, and backups and restores fail with 
BACKUP_TRANSFER. A container that was already running with the catch-all needs a restart. Refer to 
intercept().
Replace 
createBackup(). In 0.12, your Worker called it on the sandbox:
const sandbox = getSandbox(env.Sandbox, "ada");
const backup = await sandbox.createBackup({
	dir: "/workspace/project",
	excludes: ["node_modules"],
	ttl: 24 * 60 * 60,
});
In 1.0, add a method with the same name and options to 
MySandbox:
export class MySandbox extends DurableObject<Env> {
	// ...
	async createBackup(options: {
		dir: string;
		name?: string;
		excludes?: string[];
		gitignore?: boolean;
		ttl?: number;
	}): Promise<Backup> {
		await this.ensureRunning();
		const { excludes, ttl = DEFAULT_TTL_SECONDS, ...rest } = options;
		const backup = await this.backups.backup({
			...rest,
			// 0.12 matched each pattern at any depth in the directory.
			exclude: excludes?.map((pattern) => `**/${pattern}`),
		});
		const expiresAt = Date.now() + ttl * 1000;
		await this.env.BACKUP_BUCKET.put(
			metaKey(backup.id),
			JSON.stringify({ expiresAt }),
		);
		return { ...backup, expiresAt };
	}
}
Your Worker calls it as before, on the stub that 
getByName() returns. It returns a record with the ID, directory, size, SHA-256, and expiry time of the backup. Store it where your code stored the 0.12 backup object. A record lets a caller restore that backup, so keep records out of reach of the code in the sandbox.
createBackup() also writes the expiry time to 
backups/<ID>.meta.json in the bucket, as 0.12 wrote it to 
meta.json. The 
expiresAt field of the record is for display only.
Replace 
restoreBackup():
export class MySandbox extends DurableObject<Env> {
	// ...
	async restoreBackup(backup: DirectoryBackupRecord) {
		const meta = await this.env.BACKUP_BUCKET.get(metaKey(backup.id));
		if (!meta) {
			throw new Error(`Backup ${backup.id} was not found`);
		}
		const { expiresAt } = await meta.json<{ expiresAt: number }>();
		if (Date.now() + EXPIRY_MARGIN_MS > expiresAt) {
			throw new Error(`Backup ${backup.id} has expired`);
		}
		await this.ensureRunning();
		await this.backups.restore(backup);
		return { success: true, dir: backup.dir, id: backup.id };
	}
}
restoreBackup() reads the expiry time from the bucket, not from the record, so a caller cannot restore an expired backup by changing 
expiresAt. A record from another sandbox restores too, as in 0.12, and 
restore() checks the object against the SHA-256 in the record.
restore() replaces the directory with the files in the backup, so files that the backup left out, such as 
node_modules, are gone after a restore. In 0.12, the restored directory was a mount that ended with the container. In 1.0, the files stay in the container filesystem.
A process whose working directory is inside the directory keeps the old, deleted directory after 
restore(). A server started with 
cwd: "/workspace/project" is one such process. Restart the process after the restore, or have it open files by absolute path. In 0.12, the restore mounted over the path, so such a process saw the restored files.
Deploy your Worker, then back up and restore a directory through the existing routes of your Worker. 
createBackup() returns a record like this one:
{
	"id": "52046bdb-afb2-4f38-a14c-70d48a45a56f",
	"dir": "/workspace/project",
	"size": 445,
	"sha256": "31ffdbb8a126e88fce0ff3b273a7db8aae1c933ba446118cf2319d8e015ebf91",
	"format": "tar+zstd/1",
	"expiresAt": 1790465279938
}
restoreBackup() with that record returns 
{"success":true,"dir":"/workspace/project","id":"52046bdb-afb2-4f38-a14c-70d48a45a56f"}, and a backup whose stored expiry time has passed throws 
Backup <ID> has expired, even when the record has a later 
expiresAt.
Replace options, configuration, and errors
Each 0.12 name has one of these replacements:
0.12
1.0
dir
dir. 0.12 accepted only directories under 
/workspace, 
/home, 
/tmp, 
/var/tmp, and 
/app. 
DirectoryBackup accepts any absolute path, so check the directory in your code when a request chooses it.
name
name, stored in the record and in the custom metadata of the object
ttl
The expiry time in 
backups/<ID>.meta.json. As in 0.12, an expired backup stays in the bucket until you delete it with 
this.backups.delete(backup). Delete its 
.meta.json object at the same time.
excludes
exclude, in 
.gitignore syntax. 
createBackup() starts each pattern with 
**/, because a 
.gitignore pattern with a 
/ in the middle, such as 
dist/cache, matches only from the top of the directory.
gitignore
gitignore. It applies the 
.gitignore files inside the directory and 
.git/info/exclude, and the image does not need 
git.
localBucket, 
multipart, 
compression
Remove them. Every backup goes through the R2 binding in parts.
BackupNotFoundError
The error that your 
restoreBackup() throws when the 
.meta.json object is missing, or 
SandboxBackupError with the code 
BACKUP_NOT_FOUND when the backup object is missing
BackupExpiredError
The error that your 
restoreBackup() throws
InvalidBackupConfigError
TypeError
BackupCreateError, 
BackupRestoreError
SandboxFileError for a Linux error, such as a directory that does not exist, or 
SandboxBackupError with the code 
BACKUP_TRANSFER or 
BACKUP_INTEGRITY
For every error, refer to DirectoryBackup errors. For what a backup keeps, refer to What a backup contains.
Convert backups that 0.12 created
0.12 stored each backup as 
backups/<ID>/data.sqsh and 
backups/<ID>/meta.json in the bucket, with presigned uploads and with 
localBucket: true alike. These R2 objects stay in the bucket after you deploy 1.0, and the 0.12 backup objects that your code stored stay where they are. To keep a backup, convert it the first time your code restores it: extract the SquashFS image into the directory, then back up the directory with 
DirectoryBackup.
Add 
squashfs-tools to your image:
RUN apt-get update && apt-get install -y --no-install-recommends squashfs-tools && rm -rf /var/lib/apt/lists/*
Add a method to 
MySandbox that converts a 0.12 backup object:
// 0.12 restored only backups with a UUID, into one of these directories.
const BACKUP_ID =
	/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
const BACKUP_ROOTS = ["/workspace", "/home", "/tmp", "/var/tmp", "/app"];
function checkOldBackup(old: { id: string; dir: string }) {
	const segments = old.dir.split("/").slice(1);
	const inRoot = BACKUP_ROOTS.some(
		(root) => old.dir === root || old.dir.startsWith(`${root}/`),
	);
	if (
		!BACKUP_ID.test(old.id) ||
		!inRoot ||
		segments.some((part) => part === "" || part === "." || part === "..") ||
		old.dir.includes("\0")
	) {
		throw new TypeError(`Invalid 0.12 backup ${old.id} for ${old.dir}`);
	}
}
export class MySandbox extends DurableObject<Env> {
	// ...
	async convert(old: { id: string; dir: string }): Promise<Backup> {
		checkOldBackup(old);
		const meta = await this.env.BACKUP_BUCKET.get(`backups/${old.id}/meta.json`);
		const image = await this.env.BACKUP_BUCKET.get(`backups/${old.id}/data.sqsh`);
		if (!meta || !image) {
			throw new Error(`Backup ${old.id} was not found`);
		}
		const { createdAt, ttl } = await meta.json<{ createdAt: string; ttl: number }>();
		const expiresAt = Date.parse(createdAt) + ttl * 1000;
		if (Date.now() + EXPIRY_MARGIN_MS > expiresAt) {
			await image.body.cancel();
			throw new Error(`Backup ${old.id} has expired`);
		}
		await this.ensureRunning();
		// Refuses a path through a symbolic link. unsquashfs needs the whole
		// image on disk, so it goes to /var/tmp first. The files replace the
		// directory only after they are all extracted.
		const script =
			'[ "$(realpath -m -- "$2")" = "$2" ] || exit 2;' +
			' mkdir -p -- "$(dirname -- "$2")" && rm -rf -- "$2.convert" &&' +
			' cat > "$1" && unsquashfs -no-progress -d "$2.convert" "$1" > /dev/null &&' +
			' rm -rf -- "$2" && mv -- "$2.convert" "$2";' +
			' code=$?; rm -rf -- "$1" "$2.convert"; exit $code';
		const process = await this.container.exec(
			["sh", "-c", script, "sh", `/var/tmp/${old.id}.sqsh`, old.dir],
			{ stdin: image.body },
		);
		const output = await process.output();
		if (output.exitCode !== 0) {
			throw new Error(new TextDecoder().decode(output.stderr));
		}
		const backup = await this.backups.backup({ dir: old.dir });
		await this.env.BACKUP_BUCKET.put(
			metaKey(backup.id),
			JSON.stringify({ expiresAt }),
		);
		return { ...backup, expiresAt };
	}
}
convert() deletes and replaces 
old.dir, so it checks the backup first, as 0.12 did before a restore. The ID must be a UUID, and the directory must be an absolute path under one of the directories that 0.12 accepted, with no empty, 
., or 
.. segments. Code in the sandbox can replace a directory with a symbolic link, and 
rm -rf follows a link in the path, so the script exits with code 
2 when the path resolves somewhere else. Take 
old from the 0.12 backup object that your code stored, not from a request.
The converted backup keeps the expiry time that 0.12 gave the original, in its own 
.meta.json object. The container needs free disk space for the image, the extracted files, and the files already in the directory, all at once. On a 
lite instance, 
squashfs-tools 4.7 and later, as in Alpine 3.23, fail with 
FATAL ERROR: Requested memory size too large. For those versions, add 
-mem 64M to the 
unsquashfs command. Debian 13 installs version 4.6.1, which extracts on 
lite with its default settings.
Where your code calls 
restoreBackup() with an object that 0.12 created, call 
convert() instead. A 0.12 object has no 
format field. 
convert() leaves the files in the directory, so it also does the restore. Store the record that it returns in place of the 0.12 object.
After you store the new record, delete the two 0.12 objects:
await this.env.BACKUP_BUCKET.delete([
	`backups/${old.id}/data.sqsh`,
	`backups/${old.id}/meta.json`,
]);
A converted directory keeps its files, empty directories, symbolic links, hard links, and permissions. Modification times keep whole seconds only, because SquashFS does not store fractions of a second. If 
unsquashfs fails, the directory keeps its files, and calling 
convert() again retries the conversion.
Related resources
DirectoryBackup API
Back up a directory to R2
Save and restore a sandbox with snapshots

Move bucket mounts
import { Steps } from "~/components";
Move your 0.12 bucket mounts to 
S3Mount, which mounts the same bucket prefix without bucket credentials in the container. 
S3Gateway in your Worker signs each storage request. In 0.12, 
mountBucket() put the credentials in the container, or mounted through an R2 binding.
Before you start
Your 1.0 class replaces the 0.12 
Sandbox class, and has the 
container getter, the 
ensureRunning() and 
startContainer() methods, and the 
ENV constant from Replace the Sandbox class. Its image has 
sandbox-shim, which 
S3Mount uses. 
S3Mount reaches 
S3Gateway through 
this.ctx.exports, which needs compatibility date 
2025-11-17 or later, or the 
enable_ctx_exports flag.
This page replaces 
mountBucket(), 
unmountBucket(), their options, and their errors. To build the same mount in a new project, refer to Mount an R2 bucket.
Mount the bucket
Add FUSE and 
s3fs to your 
Dockerfile:
RUN apt-get update \
	&& apt-get install -y --no-install-recommends \
		ca-certificates fuse3 git python3 s3fs \
	&& rm -rf /var/lib/apt/lists/*
Export 
S3Gateway from the main module of your Worker:
import {
	S3Mount,
	SandboxS3MountError,
} from "@cloudflare/sandbox";
// S3Mount sends each storage request to this entrypoint.
export { S3Gateway } from "@cloudflare/sandbox";
Then add the endpoint and name of the bucket as variables, and its credentials as secrets, as in steps 3 and 4 of Mount an R2 bucket. 0.12 read 
AWS_* and 
R2_* variables from the environment. 
S3Mount uses only the credentials that you pass to it.
1.0 cannot mount a bucket through an R2 binding. If your 0.12 code called 
mountBucket() with a binding name and no 
endpoint, create an R2 API token with the Object Read & Write permission for that bucket.
Replace 
mountBucket() with a method that mounts the prefix for the sandbox:
const sandbox = getSandbox(env.Sandbox, job);
await sandbox.mountBucket(env.S3_BUCKET, "/data", {
	endpoint: env.S3_ENDPOINT,
	prefix: `/jobs/${job}/`,
});
export class MySandbox extends DurableObject<Env> {
	// ...
	// One S3Mount serves every container of this Durable Object.
	private readonly mounts = new S3Mount(
		this.container,
		this.ctx.exports.S3Gateway,
	);
	private async mountData(): Promise<void> {
		// The name that your Worker passed to getByName(),
		// or to getSandbox() in 0.12
		const job = this.ctx.id.name;
		if (!job) {
			throw new Error("Open the sandbox with getByName()");
		}
		await this.mounts.mount({
			mountPath: "/data",
			source: {
				type: "s3",
				endpoint: this.env.S3_ENDPOINT,
				region: "auto",
				bucket: this.env.S3_BUCKET,
				credentials: {
					type: "static",
					accessKeyId: this.env.S3_ACCESS_KEY_ID,
					secretAccessKey: this.env.S3_SECRET_ACCESS_KEY,
				},
			},
			keyPrefix: `jobs/${job}`,
			access: "read-write",
		});
	}
}
The options change as follows:
0.12
1.0
The 
bucket argument
source.bucket
endpoint
source.endpoint, and 
region, which is 
auto for R2
prefix: "/jobs/ada/"
keyPrefix: "jobs/ada". It cannot start with 
/, and 
S3Mount adds the trailing 
/
readOnly: true
access: "read-only". 
access is required
s3fsOptions: ["name=value"]
s3fsOptions: { name: "value" }. 
S3Mount always sets 
nomixupload, which 0.12 added only for R2, and rejects it here
credentials
source.credentials, with 
type: "static"
provider, 
credentialProxy
Remove them. 
S3Gateway signs every request
Mount the prefix in each method that uses it:
export class MySandbox extends DurableObject<Env> {
	// ...
	async listFiles(): Promise<string> {
		await this.ensureRunning();
		await this.mountData();
		const ls = await this.container.exec(["ls", "-la"], {
			cwd: "/data",
			env: ENV,
		});
		const output = await ls.output();
		return new TextDecoder().decode(output.stdout);
	}
}
A mount lasts until the container stops, in 0.12 and in 1.0. Calling 
mount() again with the same request reuses the mount. A request with other settings for a mounted path throws 
SandboxS3MountError with code 
S3_MOUNT_CONFLICT, where 0.12 threw 
InvalidMountConfigError.
Replace 
unmountBucket(), and check errors by their 
code:
await sandbox.unmountBucket("/data");
export class MySandbox extends DurableObject<Env> {
	// ...
	async unmountData(): Promise<string> {
		try {
			await this.mounts.unmount("/data");
			return "unmounted";
		} catch (error) {
			if (SandboxS3MountError.is(error)) {
				return error.code;
			}
			throw error;
		}
	}
}
S3_MOUNT_BUSY means that a process still uses the path. Requests to the path stay denied. Stop the process and call 
unmount() again. The 0.12 errors map as follows:
0.12
1.0
InvalidMountConfigError
TypeError for an invalid request, such as a 
keyPrefix that starts with 
/, and 
S3_MOUNT_CONFLICT for a path in use
MissingCredentialsError
None. 
source.credentials is required
S3FSMountError, 
BucketMountError
S3_MOUNT_FAILED
BucketUnmountError
S3_MOUNT_BUSY when a process uses the path
If you moved outbound rules
Each mount registers an intercept for its own hostname. That intercept receives requests only if the mount runs before the 
interceptAllOutboundHttp() call from Move outbound rules. A mount after that call fails with 
cannot verify the new FUSE connection, because your 
Outbound entrypoint receives the storage requests. Registering the catch-all again later does not affect a mount that came first.
Mount the prefix in the 
try block of 
startContainer(), before 
intercept():
export class MySandbox extends DurableObject<Env> {
	// ...
	private async startContainer(): Promise<void> {
		const newContainer = !this.container.running;
		if (newContainer) {
			this.container.start({
				image: this.container.images.sandbox,
				instance: "standard-1",
				env: ENV,
				enableInternet: ENABLE_INTERNET,
			});
		}
		try {
			if (newContainer) {
				// Replaces onStart().
				await this.ctx.storage.put("startedAt", Date.now());
			}
			// Mount before the catch-all intercept.
			await this.mountData();
			await this.intercept();
			await this.trust();
			await this.container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS);
		} catch (error) {
			// The next request starts a new container.
			await this.container.destroy();
			throw error;
		}
	}
}
Remove the 
mountData() calls from the other methods. A path that you mount after 
intercept() does not work, so mount every path that the sandbox needs here. To mount a path later, open a new sandbox. A restarted Durable Object runs 
startContainer() again, and 
mount() reuses a mount that already matches.
Each mount uses one of the 64 intercept targets of the container, and 
unmount() does not free it. Move outbound rules uses two. Give each job its own sandbox name instead of mounting a new prefix for each job in one container.
Replace localBucket
0.12 mounted with 
localBucket: true under 
wrangler dev by copying files between the container and an R2 binding. 
S3Mount works under 
wrangler dev with an S3-compatible server on your machine instead. Refer to Develop locally.
Mounts at the switch
A 0.12 mount ends with the 0.12 container, and the objects stay in the bucket. After the switch, the mount path does not exist in the new container until 
mountData() runs. Files that 0.12 wrote under 
prefix: "/jobs/ada/" appear at the same paths under 
keyPrefix: "jobs/ada".
If your 0.12 class also had outbound rules, the stored rules can include handlers named 
r2EgressMount and 
s3CredentialProxyMount for mounts that were active at the switch. The entrypoint from Move outbound rules skips them.
Check the mount
After you deploy the switch, call 
listFiles() in a sandbox that mounted its prefix in 0.12. It lists the files that 0.12 wrote:
total 9
drwxrwxrwx 1 root root 4096 Jan  1  1970 .
drwxr-xr-x 1 2346 2346  140 Sep 27 20:20 ..
-rw-r--r-- 1 root root   20 Sep 27 20:11 hello.txt
drwxr-xr-x 1 root root 4096 Sep 27 20:11 sub
this.mounts.inspect("/data") reports the state of the mount. A working mount returns an 
attachment status of 
managed, a 
fuse status of 
connected, and a 
gateway status of 
reachable with an 
upstream status of 
usable.
Related resources
Mount an R2 bucket
S3Mount API
R2 API tokens
Move outbound rules

Changes in Sandbox SDK 1.0
import { SandboxSdkVersions } from "~/components/react/sandbox/SandboxSdkVersions";
In Sandbox SDK 0.x, the 
Sandbox class from the package is your Durable Object. It starts the container, keeps it running, and sends each call to a server inside the container. In 1.0, you write the Durable Object class, and it calls the container directly through 
this.ctx.container.
In 0.x, the 
Sandbox class from the package starts the container, keeps it running, and manages previews and backups. The container runs the SDK server and bash sessions from the 
cloudflare/sandbox image. In 1.0, your own Durable Object does the same jobs. The container runs your image and your commands, plus the 
sandbox-shim helper when you use 
Files.
this.ctx.container does what the 0.x SDK server did. It runs commands, connects to ports, intercepts outbound requests, and saves snapshots. The package keeps only small helpers, such as the 
Files class.
Decisions that depend on your application stay in your code: how long a sandbox runs, what it can reach, and what happens when a call fails. For example, a cancelled command may already have changed files, and only your application knows whether running it again is safe.
Where each 0.x feature goes
Each 0.x feature moves to one of three places, depending on which part of 0.x did its work:
The 
Sandbox class handles lifetime, preview URLs, tunnels, backups, and process tracking. In 1.0, these become code in your Durable Object class, which keeps any records it needs in its own storage.
The SDK server runs commands, sessions, and file calls. In 1.0, these become 
exec() calls, or calls to the 
Files class, which runs the 
sandbox-shim helper through 
exec().
Wrangler configuration and class properties set the image, Internet access, and outbound rules. In 1.0, these become options to 
start() and outbound handlers that your class registers.
Some 0.x features have no equivalent. For each 0.x API and its replacement, refer to the API map.
Decisions your code makes
A container has no Internet access unless 
start() passes 
enableInternet: true. To allow one destination, your class registers an outbound handler for its hostname. The handler can add a credential that the container never sees. For more information, refer to Sandbox security.
exec() takes an array of arguments and starts that process without a shell. Text passed as an argument cannot start a second command. A shell runs only when you start one, such as 
["sh", "-c", "npm ci && npm test"]. Each call also sets its own 
cwd and 
env. No session carries them from one call to the next.
Your class decides how long a sandbox runs by setting the inactivity timeout after 
start(), and again in the constructor when a restarted Durable Object finds the container running. A deploy does not replace running containers. A new image applies only to containers that start after the deploy. The same holds for code that your class runs only when it starts a container, such as the calls that register outbound handlers. A handler that is already registered runs the code of the new version, with the props it was registered with. For more information, refer to Sandbox lifetime.
Your image provides every tool that your commands use. The 0.x image includes Python, Git, 
curl, 
wget, 
jq, 
unzip, and 
ps. 
cloudflare/debian-trixie and 
node:24-trixie-slim, which these pages use, include none of them. 
Files, 
S3Mount, and 
DirectoryBackup also need the 
sandbox-shim helper in the image. For the 
COPY line, refer to 
@cloudflare/sandbox requirements.
The package writes nothing to Durable Object storage. A preview token, a process record, or a snapshot ID exists only if your class stores it. The keys that 0.x wrote stay in storage. The package ignores them, and your class can read them, as the pages that move preview URLs, tunnels, and outbound rules do.
The package also retries nothing and sets no time limits. To stop a command that runs too long, run it under GNU coreutils 
timeout, as Replace timeouts describes.
Related resources
Migrate from Sandbox SDK 0.x
API map
Sandbox lifetime
Sandbox security

Replace the code interpreter
import { PackageManagers, Steps, WranglerConfig } from "~/components";
In Sandbox SDK 0.12, 
runCode() ran Python, JavaScript, and TypeScript in an interpreter process for each code context, and variables stayed defined between calls. 1.0 has no interpreter. This page runs Python in an IPython kernel that your Durable Object starts, with the results that 0.12 returned, and runs JavaScript in a Dynamic Worker.
Before you start
Your 1.0 class replaces the 0.12 
Sandbox class, and has the 
container getter, the 
ensureRunning() and 
startContainer() methods, and the 
ENV constant from Replace the Sandbox class. To keep variables between calls, 
src/index.ts also needs the scripts and functions from step 1 of Run a server in the background.
A 
runCode() call without a 
context used a default context for its language, so plain calls in one sandbox shared variables:
const sandbox = getSandbox(env.Sandbox, "ada");
await sandbox.runCode("sales = [120, 95]");
const execution = await sandbox.runCode("sum(sales)");
If your code relies on this, or on contexts that you create, follow Keep Python variables between calls. If the code in each call stands alone, start a new 
python3 process for each call, as in Run Python code. The other 0.12 methods have their own sections:
0.12
Section
runCode() with 
language: "javascript" or 
"typescript"
Run JavaScript in a Dynamic Worker
runCodeStream(), 
onStdout, 
onStderr, 
onResult
Replace streaming output
Keep Python variables between calls
A kernel is a Python process that runs the code of each call with IPython, and keeps its variables until it exits. Your Durable Object starts one kernel for each context, on its own port.
Add IPython and the packages the code imports to your 
Dockerfile, and copy in the kernel script:
FROM node:24-trixie-slim
RUN apt-get update \
	&& apt-get install -y --no-install-recommends \
		ca-certificates git python3 \
		python3-ipython python3-matplotlib \
		python3-numpy python3-pandas \
	&& rm -rf /var/lib/apt/lists/*
COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim
WORKDIR /workspace
COPY kernel.py /opt/kernel.py
CMD ["sleep", "infinity"]
The 0.12 
python image included IPython, matplotlib, NumPy, and pandas. Debian packages install them without 
pip.
Create 
kernel.py next to your 
Dockerfile:
import base64
import io
import json
import os
import signal
import sys
import traceback
from http.server import BaseHTTPRequestHandler
from socketserver import TCPServer
os.environ["MPLBACKEND"] = "Agg"
from IPython.core.interactiveshell import InteractiveShell
from IPython.utils.capture import capture_output
PORT = int(sys.argv[1])
FORMATS = {
    "text/plain": "text",
    "text/html": "html",
    "text/markdown": "markdown",
    "text/latex": "latex",
    "image/png": "png",
    "image/jpeg": "jpeg",
    "image/svg+xml": "svg",
    "application/json": "json",
    "application/javascript": "javascript",
}
shell = InteractiveShell.instance(colors="NoColor")
# Return values and errors in the response, not in stdout.
shell.displayhook.write_output_prompt = lambda: None
shell.displayhook.write_format_data = lambda *a, **k: None
shell.showtraceback = lambda *a, **k: None
shell.showsyntaxerror = lambda *a, **k: None
running = False
def interrupt(signum, frame):
    # Stop a running cell. An idle kernel ignores the signal.
    if running:
        raise KeyboardInterrupt
def formats(data):
    return {
        FORMATS[kind]: value
        for kind, value in data.items()
        if kind in FORMATS
    }
def figures():
    if "matplotlib.pyplot" not in sys.modules:
        return []
    import matplotlib.pyplot as plt
    images = []
    for number in plt.get_fignums():
        buffer = io.BytesIO()
        plt.figure(number).savefig(
            buffer, format="png", bbox_inches="tight"
        )
        png = base64.b64encode(buffer.getvalue()).decode()
        images.append({"png": png})
    plt.close("all")
    return images
def describe(error):
    if error is None:
        return None
    if isinstance(error, SyntaxError):
        lines = traceback.format_exception_only(error)
    else:
        # Skip the frame of the kernel itself.
        lines = traceback.format_exception(
            type(error), error, error.__traceback__.tb_next
        )
    return {
        "name": type(error).__name__,
        "message": str(error),
        "traceback": lines,
    }
def run(code):
    global running
    running = True
    try:
        with capture_output(display=True) as captured:
            cell = shell.run_cell(code, store_history=True)
    finally:
        running = False
    results = [formats(output.data) for output in captured.outputs]
    results += figures()
    if isinstance(cell.result, (dict, list)):
        results.append({"json": cell.result})
    elif cell.result is not None:
        data, _ = shell.display_formatter.format(cell.result)
        results.append(formats(data))
    stdout, stderr = captured.stdout, captured.stderr
    return {
        "logs": {
            "stdout": [stdout] if stdout else [],
            "stderr": [stderr] if stderr else [],
        },
        "results": results,
        "error": describe(
            cell.error_before_exec or cell.error_in_exec
        ),
        "executionCount": cell.execution_count,
    }
class Kernel(BaseHTTPRequestHandler):
    def do_GET(self):
        self.reply(b"ready")
    def do_POST(self):
        length = int(self.headers["Content-Length"])
        code = self.rfile.read(length).decode()
        result = json.dumps(run(code), default=repr)
        self.reply(result.encode())
    def reply(self, body):
        self.send_response(200)
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)
    def log_message(self, *args):
        pass
signal.signal(signal.SIGINT, interrupt)
# HTTPServer looks up the container hostname, which is too
# long to resolve.
TCPServer.allow_reuse_address = True
TCPServer(("0.0.0.0", PORT), Kernel).serve_forever()
The kernel runs the body of each 
POST request as an IPython cell, and returns what 0.12 returned: standard output and standard error, one result for each value that the cell displays, a PNG for each open matplotlib figure, the value of the last expression, and the error. It handles one request at a time.
Add the result and context types before your class:
type Execution = {
	logs: { stdout: string[]; stderr: string[] };
	// One object for each value, keyed by format.
	results: Record<string, string | object>[];
	error: {
		name: string;
		message: string;
		traceback: string[];
	} | null;
	executionCount: number;
};
type CodeContext = {
	id: string;
	port: number;
	cwd: string;
	env?: Record<string, string>;
};
const DEFAULT_CONTEXT: CodeContext = {
	id: "default",
	port: 8800,
	cwd: "/workspace",
};
// Each kernel runs as a server in its own directory.
const kernelDir = (context: CodeContext) =>
	`${SERVERS}/kernel-${context.port}`;
Add methods to your class that start a kernel and interrupt it:
export class MySandbox extends DurableObject<Env> {
	// ...
	// Ports of the kernels that answered in this container.
	private kernels = new Set<number>();
	private async startKernel(
		context: CodeContext,
	): Promise<Fetcher> {
		if (this.kernels.has(context.port)) {
			return this.container.getTcpPort(context.port);
		}
		await startServer(
			this.container,
			kernelDir(context),
			["python3", "/opt/kernel.py", String(context.port)],
			{ cwd: context.cwd, env: { ...ENV, ...context.env } },
		);
		const kernel = await waitForServer(
			this.container,
			kernelDir(context),
			context.port,
			30_000,
		);
		this.kernels.add(context.port);
		return kernel;
	}
	private async interruptKernel(context: CodeContext): Promise<void> {
		const kill = await this.container.exec([
			"sh",
			"-c",
			`${CURRENT}\ncurrent "$1" && kill -INT "$pid"`,
			"sh",
			kernelDir(context),
		]);
		await kill.exitCode;
	}
}
Call 
this.kernels.clear() in 
startContainer(), inside 
if (newContainer), because a new container has no kernels. If your Durable Object restarts while the container runs, 
startServer() finds the kernel that already runs, and the kernel keeps its variables. If a kernel exits, 
waitForServer() throws with the end of its log.
Add a method that runs the calls to one context one at a time, and a 
runCode() method:
export class MySandbox extends DurableObject<Env> {
	// ...
	// The last call queued for each context.
	private queues = new Map<string, Promise<unknown>>();
	private inContext<T>(id: string, operation: () => Promise<T>): Promise<T> {
		const previous = this.queues.get(id) ?? Promise.resolve();
		const result = previous.then(operation);
		this.queues.set(id, result.catch(() => {}));
		return result;
	}
	async runCode(
		code: string,
		options: { context?: string; timeout?: number } = {},
	): Promise<Execution> {
		const id = options.context ?? DEFAULT_CONTEXT.id;
		return this.inContext(id, async () => {
			await this.ensureRunning();
			const context = await this.getContext(id);
			const kernel = await this.startKernel(context);
			try {
				const response = await kernel.fetch("http://kernel/", {
					method: "POST",
					body: code,
					signal: AbortSignal.timeout(options.timeout ?? 60_000),
				});
				return await response.json<Execution>();
			} catch (error) {
				if ((error as Error).name === "TimeoutError") {
					// Stop the cell, and keep the kernel variables.
					await this.interruptKernel(context);
				} else {
					// The kernel exited. The next call starts a new one.
					this.kernels.delete(context.port);
				}
				throw error;
			}
		});
	}
}
Calls to one context wait for each other, as they did in 0.12. Calls to different contexts run at the same time. Because only one call to a context runs at a time, the time limit starts when the call reaches the kernel, not while it waits for an earlier call, and the interrupt reaches the cell of the call that timed out. The queue also keeps two first calls from starting the same kernel twice.
0.12 had no default timeout, and a cell that timed out kept running. Here, a call that runs longer than 
timeout throws a 
TimeoutError, and the kernel stops the cell with 
KeyboardInterrupt. Variables that earlier calls defined stay. If the kernel exits, for example because the code runs out of memory, the call throws and the next call starts a kernel without variables.
Add methods that replace 
createCodeContext(), 
listCodeContexts(), and 
deleteCodeContext():
export class MySandbox extends DurableObject<Env> {
	// ...
	private async getContext(id: string): Promise<CodeContext> {
		if (id === DEFAULT_CONTEXT.id) {
			return DEFAULT_CONTEXT;
		}
		const context = await this.ctx.storage.get<CodeContext>(
			`context:${id}`,
		);
		if (!context) {
			throw new Error(`No code context ${id}`);
		}
		return context;
	}
	async createCodeContext(
		options: { cwd?: string; env?: Record<string, string> } = {},
	): Promise<CodeContext> {
		// Take the lowest port that no stored context uses.
		const stored = await this.ctx.storage.list<CodeContext>({
			prefix: "context:",
		});
		const used = new Set([...stored.values()].map((c) => c.port));
		let port = DEFAULT_CONTEXT.port + 1;
		while (used.has(port)) {
			port++;
		}
		const context: CodeContext = {
			id: crypto.randomUUID(),
			port,
			cwd: options.cwd ?? "/workspace",
			env: options.env,
		};
		await this.ctx.storage.put(`context:${context.id}`, context);
		return context;
	}
	async listCodeContexts(): Promise<CodeContext[]> {
		const contexts = await this.ctx.storage.list<CodeContext>({
			prefix: "context:",
		});
		return [DEFAULT_CONTEXT, ...contexts.values()];
	}
	async deleteCodeContext(id: string): Promise<void> {
		// Wait for the calls already queued for the context.
		return this.inContext(id, async () => {
			const context = await this.getContext(id);
			if (this.container.running) {
				await stopServer(this.container, kernelDir(context));
				this.kernels.delete(context.port);
			}
			await this.ctx.storage.delete(`context:${id}`);
		});
	}
}
createCodeContext() gives each new context the lowest port after 
8800 that no stored context uses, so a new context can take the port of a deleted one.
The contexts share one container, so code in one context can read the files of the others and reach their ports. Give each user their own sandbox name.
Replace each call. Pass the 
id of the context, and 
env for 
envVars:
const sandbox = getSandbox(env.Sandbox, "ada");
const context = await sandbox.createCodeContext({
	language: "python",
	envVars: { REGION: "east" },
});
const execution = await sandbox.runCode(
	"import os; os.environ['REGION']",
	{ context, timeout: 30_000 },
);
const sandbox = env.Sandbox.getByName("ada");
const context = await sandbox.createCodeContext({
	env: { REGION: "east" },
});
const execution = await sandbox.runCode(
	"import os; os.environ['REGION']",
	{ context: context.id, timeout: 30_000 },
);
Then change the code that reads the result:
0.12
1.0
results[i].text, 
html, 
png, 
jpeg, 
svg, 
latex, 
markdown, 
javascript, 
json
The same keys. 0.12 returned each format as its own result, such as one 
html result and one 
text result for a pandas DataFrame. The kernel returns one result with both keys.
results[i].formats()
Object.keys(results[i]).
results[i].chart, 
results[i].data
Not returned. The 0.12 Python interpreter did not set them.
logs.stdout, 
logs.stderr
The same, with one string for each call. 0.12 also wrote the value of the last line to 
stdout, such as 
Out[0]: 215. The kernel returns that value only in 
results.
error.name, 
error.message, 
error.traceback
The same. 
error is 
null when the code succeeds, not 
undefined.
executionCount
The same.
Deploy, and send two calls to one sandbox. In this example, a Worker route at 
/sandboxes/<name>/code passes the request body to 
runCode():
WORKER="https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev"
curl "$WORKER/sandboxes/ada/code" --data-binary 'sales = [120, 95]'
curl "$WORKER/sandboxes/ada/code" --data-binary 'sum(sales)'
The second call reads the variable that the first call defined:
{
	"logs": { "stdout": [], "stderr": [] },
	"results": [{ "text": "215" }],
	"error": null,
	"executionCount": 2
}
Variables that 0.12 contexts held stay in the 0.12 container. After the switch, run your setup code again, and create your contexts again, because 0.12 context IDs are not in the storage of your Durable Object.
Run JavaScript in a Dynamic Worker
Run JavaScript in a Dynamic Worker that your Worker loads, so JavaScript needs no container.
Add a Worker Loader binding to your Wrangler configuration:
{
	"worker_loaders": [
		{
			"binding": "LOADER",
		},
	],
}
Create 
src/sandbox.ts with the 
runJavaScript() function from Build an AI code interpreter.
Replace each 
runCode() call for JavaScript:
const execution = await sandbox.runCode(
	"[2, 3, 5, 7].reduce((a, b) => a + b)",
	{ language: "javascript" },
);
import { runJavaScript } from "./sandbox";
const output = await runJavaScript(
	env,
	"return [2, 3, 5, 7].reduce((a, b) => a + b);",
);
output is 
{ "result": 17, "logs": [] }, and 
logs holds the 
console.log() output. The code runs as the body of an async function, so it must 
return its result. 0.12 returned the value of the last expression instead. The code has no network access. For the limits that 
runJavaScript() sets, refer to Build an AI code interpreter.
Each call loads a new Dynamic Worker, so variables do not carry over. Put the values that the code needs into the code. 0.12 compiled TypeScript before running it. To run TypeScript, compile it first with 
@cloudflare/worker-bundler.
Replace streaming output
The kernel returns the output of a cell when the cell finishes, so 
runCodeStream(), 
onStdout, 
onStderr, and 
onResult have no 1.0 version. To send output while code runs, run the code as a command with 
python3 -, pass it on standard input, and return 
stdout from the process, as in Move commands. A command does not keep variables.
Related resources
Run Python code
Build an AI code interpreter
Dynamic Workers
Stream command output
Durable Object Container API

Change command calls
Replace 0.12 command calls with 
exec() on the container. In Sandbox SDK 0.12, 
exec() runs each command string in a long-lived 
bash session that starts in 
/workspace. In 1.0, each call starts one process, and nothing carries over from one call to the next.
Before you start
Your 1.0 class replaces the 0.12 
Sandbox class, and has the 
container getter, the 
ensureRunning() method, and the 
ENV constant from Replace the Sandbox class. Call 
ensureRunning() at the start of each method that runs a command.
This page replaces 
exec(), 
execStream(), 
createSession(), 
getSession(), 
deleteSession(), and the 
timeout and 
commandTimeoutMs options. For file calls, refer to Change file calls. For 
startProcess(), refer to Move background processes.
Run commands
Pass the command as an array of arguments, with the working directory and variables that 0.12 gave it:
const result = await sandbox.exec("npm test");
if (!result.success) {
	console.error(result.stderr);
}
const process = await this.container.exec(["npm", "test"], {
	cwd: "/workspace",
	env: ENV,
});
const result = await process.output();
if (result.exitCode !== 0) {
	console.error(new TextDecoder().decode(result.stderr));
}
exec() starts in 
/, even when the image sets 
WORKDIR. It does not inherit the variables that 
start() sets, except 
PATH. 
output() waits for the process to exit, and returns its output as bytes. As in 0.12, a non-zero exit code does not throw.
exec() runs the command without a shell. For pipes, redirects, and variables, run the 0.12 string with 
bash:
const process = await this.container.exec(
	["bash", "-c", "npm test 2>&1 | tee /tmp/test.log"],
	{ cwd: "/workspace", env: ENV },
);
When the executable does not exist, 
exec() throws an error such as 
Command `npm` was not found in the container. 0.12 
bash returned exit code 
127 instead. A command that runs through 
bash -c still returns 
127.
Stream output
To replace 
execStream(), or 
exec() with 
stream: true and 
onOutput, return 
stdout from the process as a response body:
const stream = await sandbox.execStream("npm test");
return new Response(stream, {
	headers: { "Content-Type": "text/event-stream" },
});
const process = await this.container.exec(["npm", "test"], {
	cwd: "/workspace",
	env: ENV,
	stderr: "combined",
});
return new Response(process.stdout, {
	headers: { "Content-Type": "text/event-stream" },
});
stderr: "combined" sends standard error in the same stream. When the command writes to both streams at nearly the same time, lines can arrive out of order. To keep the order, redirect in a shell instead, such as 
["sh", "-c", "npm test 2>&1"]. Keep 
Content-Type: text/event-stream. With other content types, the response can arrive all at once when the process exits.
0.12 sent JSON events that 
parseSSEStream() decoded. The 1.0 body holds the output of the command. Read it with 
fetch() and a stream reader instead of 
EventSource. To send each line as a server-sent event, refer to Stream command output.
Replace sessions
A 0.12 session kept a working directory and variables across calls. Keep them in an object, and pass it to each call:
const build = await sandbox.createSession({
	cwd: "/workspace/app",
	env: { CI: "1" },
});
await build.exec("npm ci");
await build.exec("npm test");
const build = { cwd: "/workspace/app", env: { ...ENV, CI: "1" } };
const install = await this.container.exec(["npm", "ci"], build);
await install.exitCode;
const test = await this.container.exec(["npm", "test"], build);
const result = await test.output();
exec() resolves when the process starts, so wait for 
exitCode before the next step.
In 0.12, a 
cd or 
export in one 
exec() call carried into the next call, including in the default session. In 1.0, it lasts until its command exits. Run steps that depend on each other in one command, such as 
["bash", "-c", "cd app && npm ci && npm test"].
ExecutionSession methods map like the top-level methods. Remove 
deleteSession(), which has nothing to delete. 0.12 accepted an 
isolation option and ignored it, so sessions in one sandbox always shared processes and files. To keep the work of two sessions apart, give each one its own sandbox name.
Replace timeouts
Start the command with GNU coreutils 
timeout, which stops the command and the processes it started that stay in its process group:
const result = await sandbox.exec("npm test", { timeout: 60_000 });
const process = await this.container.exec(
	["timeout", "--kill-after=5", "60", "bash", "-c", "npm test"],
	{ cwd: "/workspace", env: ENV },
);
const result = await process.output();
// 124 or 137 means the command ran longer than 60 seconds
const timedOut = result.exitCode === 124 || result.exitCode === 137;
0.12 threw 
CommandError with the message 
Command timeout after 60000ms, and the command kept running. In 1.0, a command that times out stops, so it cannot change files after the error.
To cancel a command from your code instead, pass an 
AbortSignal. For how to clear its timer, refer to 
exec().
Check the commands
Run a command with and without the options, from a method on your class:
const command = [
	"sh",
	"-c",
	'echo "pwd=$(pwd) NODE_ENV=${NODE_ENV:-unset}"',
];
const bare = await this.container.exec(command);
const withOptions = await this.container.exec(command, {
	cwd: "/workspace",
	env: ENV,
});
The output of 
bare shows the defaults, and the output of 
withOptions shows what 0.12 gave each command:
pwd=/ NODE_ENV=unset
pwd=/workspace NODE_ENV=test
Related resources
exec()
Stream command output
Change file calls
Move background processes

Change file calls
In Sandbox SDK 0.12, the SDK server in the container handled file calls. It created missing directories, returned binary files as base64, and hid dotfiles. In 1.0, 
Files runs a small helper in the container for each call, and does only what the call asks.
Before you start
Your 1.0 class replaces the 0.12 
Sandbox class, and has the 
container getter and the 
ensureRunning() method from Replace the Sandbox class. 
Files needs the 
sandbox-shim helper in your image, which the 
Dockerfile on that page copies.
Import 
Files, and create one as a field of your class. 
this.ctx.container stays the same object for as long as the Durable Object runs, so one 
Files object serves every container that the Durable Object starts. Call 
ensureRunning() before each file call:
import { Files, SandboxFileError } from "@cloudflare/sandbox";
export class MySandbox extends DurableObject<Env> {
	private readonly files = new Files(this.container);
	// ...
}
This page replaces 
readFile(), 
readFileStream(), 
writeFile(), 
exists(), 
listFiles(), 
mkdir(), 
deleteFile(), 
renameFile(), 
moveFile(), 
watch(), and 
checkChanges(). For commands, refer to Change command calls.
Change each file call
These calls keep their meaning, under a new name or with a different result:
0.12
1.0
readFile(path), then 
.content of a text file
await (await this.files.readFile(path)).text()
readFileStream(path), then 
streamFile() or 
collectFile()
(await this.files.readFile(path)).body, which carries the bytes of the file. 0.12 returned server-sent events, which those helpers decoded.
exists(path)
this.files.stat(path), catching 
SandboxFileError with code 
ENOENT
mkdir(path, { recursive })
this.files.mkdir(path, { recursive })
deleteFile(path)
this.files.remove(path)
renameFile(), 
moveFile()
this.files.rename(source, destination)
0.12 resolved a relative path against the working directory of the session, 
/workspace by default. 
Files throws 
TypeError: cwd is required when path is relative, so pass the directory in the 
cwd option:
const text = await (
	await this.files.readFile("app/package.json", { cwd: "/workspace" })
).text();
Write into a new directory
0.12 created missing parent directories. Create them with 
mkdir() first:
await sandbox.writeFile("/workspace/app/src/index.js", code);
await this.files.mkdir("/workspace/app/src", { recursive: true });
await this.files.writeFile("/workspace/app/src/index.js", code);
Without 
mkdir(), 
writeFile() rejects with 
SandboxFileError code 
ENOENT. Where 0.12 took base64 with 
encoding: "base64", pass bytes. 
writeFile() also accepts a string, a 
Blob, or a stream.
0.12 wrote a stream to a temporary file and renamed it into place. 
writeFile() writes into the file directly, so a reader can see it partly written. To keep the 0.12 behavior, write to a temporary path and call 
rename(), as in 
writeFile.
Read binary files
0.12 returned a binary file as a base64 string, with 
encoding: "base64". 
readFile() returns a 
Response, so read the bytes directly:
const file = await sandbox.readFile("/workspace/logo.png");
const bytes = Uint8Array.from(atob(file.content), (c) =>
	c.charCodeAt(0),
);
const response = await this.files.readFile("/workspace/logo.png");
const bytes = new Uint8Array(await response.arrayBuffer());
The response has no 
Content-Type header, where 0.12 returned a 
mimeType. For the size, call 
stat().
List files
0.12 left out dotfiles unless you passed 
includeHidden: true, and returned the size and modification time of each file. 
readDirectory() returns every entry, with only its 
name and 
type:
const result = await sandbox.listFiles("/workspace/app");
for (const file of result.files) {
	console.log(file.name, file.size);
}
const entries = await this.files.readDirectory("/workspace/app");
for (const entry of entries) {
	if (entry.name.startsWith(".")) {
		continue;
	}
	const stat = await this.files.stat(`/workspace/app/${entry.name}`);
	console.log(entry.name, Number(stat.size));
}
stat() returns the size as a 
bigint, which 
JSON.stringify() cannot serialize. Convert it with 
Number(). Each 
Files call starts one helper process in the container. For a recursive listing, use the walk in 
readDirectory.
Handle errors
A failed call throws 
SandboxFileError, whose 
code is the Linux error name. Each 0.12 error class becomes a code:
0.12
code
FileNotFoundError
ENOENT
FileExistsError
EEXIST
PermissionDeniedError
EACCES
FileSystemError
The code of the failure, such as 
EISDIR or 
ENOTDIR
SandboxFileError is not a class, so check it with 
SandboxFileError.is():
try {
	await this.files.stat("/workspace/package.json");
} catch (cause) {
	if (SandboxFileError.is(cause) && cause.code === "ENOENT") {
		// The file does not exist.
	} else {
		throw cause;
	}
}
Two calls behave differently from 0.12:
deleteFile() refused a directory. 
remove() removes one with 
recursive: true, and rejects with 
EISDIR without it.
renameFile() and 
moveFile() ran 
mv. When the destination was an existing directory, 
mv moved the source into it. 
rename() follows Linux 
rename rules instead: it replaces the destination, and rejects with 
ENOTEMPTY when the destination is a directory that holds files. Pass the full new path, such as 
/workspace/archive/report.txt.
mv also copied across filesystems. 
rename() rejects with 
EXDEV, so copy the source, check the result, and then remove the source:
const copy = await this.container.exec(["cp", "-a", "--", source, destination]);
const { exitCode, stderr } = await copy.output();
if (exitCode !== 0) {
	throw new Error(new TextDecoder().decode(stderr));
}
await this.files.remove(source, { recursive: true });
Replace file watching
To replace 
watch(), run 
inotifywait in the container, and stream its output while the request is open. Add 
inotify-tools to the 
apt-get install line in your 
Dockerfile, then return the output of the watcher:
// Stop watching after 10 minutes.
const watcher = await this.container.exec([
	"timeout",
	"--kill-after=5",
	"600",
	"inotifywait",
	"-m",
	"-r",
	"-e",
	"create,modify,delete,move",
	"--format",
	"%e %w%f",
	"/workspace",
]);
return new Response(watcher.stdout, {
	headers: { "Content-Type": "text/event-stream" },
});
Each line holds an event and a path, such as 
MODIFY /workspace/src/index.ts. The 
text/event-stream type keeps the response streaming, as in Stream output. The lines are not server-sent events, so read them with 
fetch() and a stream reader.
timeout stops the watcher after 10 minutes, and the stream ends. If the client disconnects first, the watcher exits the next time it writes an event.
Pass 
inotifywait an absolute path, where 0.12 resolved a relative path against 
/workspace. The 0.12 
include and 
exclude options took lists of glob patterns. 
inotifywait takes one regular expression for each, such as 
--exclude '(\.log|/node_modules/.*)$', and uses only the last 
--exclude.
checkChanges() has no replacement. The watcher reports only changes made while it runs, so read the files a client needs again when it reconnects.
Check the file calls
Write a file into a directory that does not exist yet, without 
mkdir(). The call rejects with 
SandboxFileError code 
ENOENT, and the message 
writeFile '/workspace/new/deep/a.txt': No such file or directory (os error 2).
After 
mkdir() with 
recursive: true, the write succeeds. Call 
readDirectory() on a directory that holds a dotfile. The result includes the dotfile:
[
	{ "name": ".hidden", "type": "file" },
	{ "name": "shown", "type": "file" }
]
Related resources
Files reference
Move files in and out of a sandbox
Change command calls

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.
Containers that use the Durable Object scheduling policy start faster. In an independent benchmark that starts 100 sandboxes at once, the median time from creating a sandbox to running a command in it fell from 4.0 seconds to 648 milliseconds. For the measurements, refer to Cloudflare Containers, rebuilt to scale agent sandboxes. 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.14 and the 
docker.io/cloudflare/sandbox:0.12.14 image first.
Plan for a one-way switch
:::caution
You cannot undo the deploy that moves your class to 
scheduling_policy: "durable_object". After that deploy, 0.x code cannot start containers for the class, even after 
wrangler rollback.
:::
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.14 and your image to 
docker.io/cloudflare/sandbox:0.12.14. 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.
Related resources
Changes in Sandbox SDK 1.0
API map
@cloudflare/sandbox reference
Durable Object Container API

Move sandboxes side by side
import { PackageManagers, Steps, WranglerConfig } from "~/components";
Run a Sandbox SDK 1.0 class next to your 0.12 class in the same Worker, and move each sandbox the first time a request reaches it. Commands and connections in sandboxes that have not moved keep running. When no sandbox needs the 0.12 class, delete it.
Before you start
Your application runs 
@cloudflare/sandbox 0.12.10, with a class and binding named 
Sandbox.
Your 1.0 class is written under a new name, such as 
SandboxV1. Choose a name you want to keep, because renaming a class later is another class migration. For the class, refer to Replace the Sandbox class.
You have a staging copy of the Worker with its own Wrangler configuration file, a different Worker 
name, and a different 
name for each container.
The code on this page copies 
/workspace from the 0.12 container into the 1.0 container as one archive. A stopped 0.12 container has no files to copy. The archive travels base64-encoded in one RPC message, which is limited to 32 MiB. For larger workspaces, save a 0.12 backup and convert it as Move backups describes.
Keep the 0.12 exports, variables, and secrets that other migration pages tell you to remove, such as 
ContainerProxy, 
SANDBOX_TRANSPORT, and 
R2_ACCESS_KEY_ID, until you delete the 0.12 class. The 0.12 class still reads them.
Add the 1.0 class
Install version 1 of the package, and keep 0.12 under the alias 
sandbox-0x:
Your package manager can save a version range. In 
package.json, set 
sandbox-0x to 
npm:@cloudflare/sandbox@0.12.10, so the 0.12 code stays on that version. In your 0.12 code, change each import from 
@cloudflare/sandbox to 
sandbox-0x.
Give the 0.12 class a method that reports whether its container runs, and one that returns the storage that your 1.0 code reads. If your code exports the class from the package, replace that export with a subclass:
import { getSandbox, Sandbox as SandboxBase } from "sandbox-0x";
// Preview tokens, named tunnels, and outbound rules set at runtime.
const STORAGE_0X = [
	"portTokens",
	"tunnels",
	"tunnels:meta",
	"OUTBOUND_CONFIGURATION",
];
export class Sandbox extends SandboxBase<Env> {
	// A 0.12 container keeps its files only while it runs.
	isRunning(): boolean {
		return this.ctx.container?.running ?? false;
	}
	exportStorage(): Promise<Map<string, unknown>> {
		return this.ctx.storage.get(STORAGE_0X);
	}
}
If you already have a subclass, add the constant and the methods to it.
Create a 
Dockerfile.v1 for the 1.0 class. Keep your 0.12 
Dockerfile until you delete the 0.12 class:
FROM node:24-trixie-slim
COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim
WORKDIR /workspace
CMD ["sleep", "infinity"]
The copy step needs 
tar, 
gzip, and 
base64, which this image includes. Add the tools your commands use. When another migration page adds a line to your 
Dockerfile, such as the 
cloudflared copy on Move tunnels, add it to 
Dockerfile.v1.
Add the 1.0 class to the Wrangler configuration, with its own container, binding, and migration. Leave the 
Sandbox entries as they are. Replace 
my-worker-sandbox-v1 with a name that your account does not use yet:
{
	"containers": [
		{
			"class_name": "Sandbox",
			"image": "./Dockerfile",
			// Your other 0.12 settings, unchanged.
		},
		{
			"class_name": "SandboxV1",
			"name": "my-worker-sandbox-v1",
			"scheduling_policy": "durable_object",
			"images": {
				"sandbox": {
					"dockerfile": "./Dockerfile.v1",
				},
			},
		},
	],
	"durable_objects": {
		"bindings": [
			{ "class_name": "Sandbox", "name": "Sandbox" },
			{ "class_name": "SandboxV1", "name": "SandboxV1" },
		],
	},
	"migrations": [
		{ "new_sqlite_classes": ["Sandbox"], "tag": "v1" },
		{ "new_sqlite_classes": ["SandboxV1"], "tag": "v2" },
	],
}
If your Worker declares its classes with 
exports in the Wrangler configuration, add an entry there instead of a migration:
{
	"exports": {
		"Sandbox": { "type": "durable-object", "storage": "sqlite" },
		"SandboxV1": { "type": "durable-object", "storage": "sqlite" },
	},
}
Add methods to the 1.0 class that move one sandbox. The copy runs once for each name, and stores 
moved so that later requests skip it:
export class SandboxV1 extends DurableObject<Env> {
	// ...
	private moving: Promise<void> | null = null;
	async moveFrom0x(name: string): Promise<void> {
		// Requests that arrive during the copy wait for the same copy.
		this.moving ??= this.copyFrom0x(name).finally(() => {
			this.moving = null;
		});
		await this.moving;
	}
	private async copyFrom0x(name: string): Promise<void> {
		if (await this.ctx.storage.get("moved")) {
			return;
		}
		const stub0x = this.env.Sandbox.getByName(name);
		const stored = await stub0x.exportStorage();
		await this.ctx.storage.put(Object.fromEntries(stored));
		if (await stub0x.isRunning()) {
			const legacy = getSandbox(this.env.Sandbox, name);
			// Stop the background processes, so no file changes during the copy.
			await legacy.killAllProcesses();
			const path = "/tmp/workspace.tar.gz";
			const packed = await legacy.exec(`tar -czf ${path} -C /workspace .`);
			if (!packed.success) {
				throw new Error(packed.stderr);
			}
			const archive = await legacy.readFile(path, {
				encoding: "base64",
			});
			await this.ensureRunning();
			const extract = await this.container.exec(
				["sh", "-c", "base64 -d | tar -xzf - -C /workspace"],
				{ stdin: new Blob([archive.content]).stream() },
			);
			const result = await extract.output();
			if (result.exitCode !== 0) {
				const stderr = new TextDecoder().decode(result.stderr);
				throw new Error(stderr);
			}
			// destroy() would delete named tunnels and DNS records.
			await legacy.stop();
			await this.ctx.storage.put("moved", true);
			return;
		}
		await this.ctx.storage.put("moved", true);
	}
}
ensureRunning() and 
container are the helpers from your 1.0 class that start the container and return 
this.ctx.container. The method copies the 0.12 storage first, so preview URLs, named tunnels, and outbound rules move even when the 0.12 container has stopped. If the copy or 
stop() fails, the method throws before it stores 
moved, and the next request runs the move again.
The copy holds the files as they are when 
tar runs. 
killAllProcesses() stops the processes that 0.12 
startProcess() started. A command that another request runs through 0.12 can still write files, so send no other requests to the 0.12 class for the sandbox while it moves. Requests that go through 
sandboxFor() in the next step wait for the move.
0.12 
stop() keeps the storage of the 0.12 class, and the tunnels and DNS records in your account. 0.12 
destroy() deletes the preview tokens, the tunnel entries, and each named tunnel with its DNS record. Processes end with the 0.12 container, so start the ones your application needs in the 1.0 container, as Move background processes describes. To start the same commands, read them from 
legacy.listProcesses() before 
killAllProcesses().
Send every request through the move. Add this function to your Worker, and replace each 
getSandbox(env.Sandbox, name) call with 
await sandboxFor(env, name):
async function sandboxFor(env: Env, name: string) {
	const sandbox = env.SandboxV1.getByName(name);
	await sandbox.moveFrom0x(name);
	return sandbox;
}
New sandboxes start on the 1.0 class, because no 0.12 container runs for their names.
Pass the name that 0.12 used. If your Worker passed 
normalizeId: true to 
getSandbox(), lowercase the name before you call 
sandboxFor(), so that both classes use the 0.12 Durable Object of the sandbox.
Generate types, and deploy:
The deploy reports no changes to the 0.12 container application. Running 0.12 containers keep their files and processes.
Check the move
Send a request for a sandbox whose 0.12 container runs and has files in 
/workspace. The first request copies the files and returns a result from the 1.0 container. A second request for the same name skips the copy and returns faster. Send a request for a new name, which starts only a 1.0 container.
Delete the 0.12 class
Move the remaining sandboxes. Your Worker cannot list Durable Objects, so use the records of your application to send one request for each sandbox that has not moved.
Remove the 0.12 code. Delete the 0.12 class, 
STORAGE_0X, the 
sandbox-0x import, and the 
moving field, 
moveFrom0x(), and 
copyFrom0x() from the 1.0 class. Call 
env.SandboxV1.getByName(name) where your code called 
sandboxFor(). Also remove the 0.12 exports, variables, and secrets that you kept, such as 
ContainerProxy, 
SANDBOX_TRANSPORT, and 
R2_ACCESS_KEY_ID.
Remove the 
Sandbox container and binding from the Wrangler configuration, and add a migration that deletes the class:
:::caution
Deleting the class deletes its Durable Objects and their storage, including any 0.12 backup handles. You cannot undo it. With 
migrations, Wrangler refuses a rollback past this deploy. With 
exports, a rollback deploys, and every call to the old class fails with 
Durable Object Namespace was deleted.
:::
{
	"migrations": [
		{ "new_sqlite_classes": ["Sandbox"], "tag": "v1" },
		{ "new_sqlite_classes": ["SandboxV1"], "tag": "v2" },
		{ "deleted_classes": ["Sandbox"], "tag": "v3" },
	],
}
If your Worker uses 
exports in the Wrangler configuration, mark the class as deleted instead:
{
	"exports": {
		"Sandbox": { "type": "durable-object", "state": "deleted" },
		"SandboxV1": { "type": "durable-object", "storage": "sqlite" },
	},
}
Remove the alias, generate types, and deploy:
Deleting the class does not delete its container application. Wrangler named that application from your Worker and class names, such as 
my-worker-sandbox. List the applications to find it:
Delete the old application. Replace 
<OLD_APPLICATION_ID> with its ID from the list:
The old application runs its containers, and bills for them, until you delete it.
Related resources
Plan the move to Sandbox SDK 1.0
Replace the Sandbox class
Durable Objects migrations
Durable Object Container API

Move other 0.x features
import { PackageManagers, Steps, WranglerConfig } from "~/components";
This page replaces or removes the Sandbox SDK 0.12 features that have no class in 1.0. Each section stands alone. Follow only the sections for the features that your application uses.
Before you start
Your 1.0 class replaces the 0.12 
Sandbox class, and has the 
container getter, the 
ensureRunning() and 
startContainer() methods, and the 
ENV constant from Replace the Sandbox class. A class that you reach through 
this.ctx.exports needs compatibility date 
2025-11-17 or later, or the 
enable_ctx_exports flag.
Each 0.12 feature has one section:
0.12 feature
Section
Docker in a 
docker:dind-rootless image
Run Docker inside the sandbox
outboundByHost handlers that read bindings
Reach Workers bindings from the container
@cloudflare/sandbox/opencode
Start an OpenCode server
@cloudflare/sandbox/openai
Give OpenAI agents a shell and an editor
@cloudflare/sandbox/bridge
Replace the bridge
WarmPool
Remove WarmPool
Run Docker inside the sandbox
The 0.x Docker setup starts from 
docker:dind-rootless, switches to 
USER root, and copies in the musl build of the 0.x server. On a 1.0 container, its Docker daemon exits with 
failed to set IP forwarding '/proc/sys/net/ipv4/ip_forward' = '1': open /proc/sys/net/ipv4/ip_forward: read-only file system.
Replace your 
Dockerfile:
FROM docker:dind
COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim
ENTRYPOINT ["sh", "-c", "dockerd-entrypoint.sh dockerd --iptables=false --ip6tables=false --ip-forward=false > /var/log/dockerd.log 2>&1 & exec sleep infinity"]
The Docker daemon runs as 
root, with iptables and IP forwarding turned off. It logs to 
/var/log, because the 
docker:dind entrypoint mounts an empty 
/tmp. 
sleep infinity keeps the container running. Keep the 
COPY line only if your class uses 
Files, 
S3Mount, or 
DirectoryBackup. 
sandbox-shim is statically linked, so it runs on the Alpine-based 
docker:dind image.
Keep 
enableInternet: true in 
start(), so that Docker can pull images. 0.12 allowed Internet access by default.
Wait for Docker, and run containers with 
--network=host:
const sandbox = getSandbox(env.Sandbox, "docker-sandbox");
const run = await sandbox.exec(
	"docker run --rm --network=host alpine:3.22 " +
		"echo Hello from Docker",
);
export class MySandbox extends DurableObject<Env> {
	// ...
	private async waitForDocker(): Promise<void> {
		const wait = await this.container.exec([
			"timeout",
			"30",
			"sh",
			"-c",
			"until docker version > /dev/null 2>&1; do sleep 0.2; done",
		]);
		if ((await wait.exitCode) !== 0) {
			throw new Error("Docker did not start within 30 seconds");
		}
	}
	async runImage(): Promise<string> {
		await this.ensureRunning();
		// The Docker daemon starts after the container, so wait for it
		await this.waitForDocker();
		const run = await this.container.exec(
			[
				"docker",
				"run",
				"--rm",
				"--network=host",
				"alpine:3.22",
				"echo",
				"Hello from Docker",
			],
			{ env: ENV },
		);
		const result = await run.output();
		return new TextDecoder().decode(result.stdout);
	}
}
Without 
--network=host, 
docker run fails with 
failed to disable IPv6 on container's interface eth0. A 
docker build step that uses the network, such as a package install, also needs 
docker build --network=host. An inner container started this way shares the network access of the sandbox.
Call 
runImage() from your Worker. It returns 
Hello from Docker. The first call also pulls 
alpine:3.22, and Docker writes its progress to 
stderr.
For more information, refer to Docker-in-Docker in the Containers FAQ.
Reach Workers bindings from the container
In 0.12, an 
outboundByHost handler answered requests to a hostname such as 
my.kv, and read Workers bindings from its 
env argument. In 1.0, a 
WorkerEntrypoint answers them, and your Durable Object registers it for that hostname.
Replace each handler with a 
WorkerEntrypoint, and export it from the main module of your Worker:
MySandbox.outboundByHost = {
	"my.kv": async (request: Request, env: Env) => {
		const key = new URL(request.url).pathname.slice(1);
		const value = await env.KV.get(key);
		return new Response(value ?? "", {
			status: value ? 200 : 404,
		});
	},
};
import { WorkerEntrypoint } from "cloudflare:workers";
type KvProps = { containerId: string };
export class KvGateway extends WorkerEntrypoint<Env, KvProps> {
	async fetch(request: Request): Promise<Response> {
		const key = new URL(request.url).pathname.slice(1);
		const value = await this.env.KV.get(key);
		return new Response(value ?? "", {
			status: value === null ? 404 : 200,
		});
	}
}
this.env has the same bindings as the 
env argument. Where a 0.12 handler read 
ctx.containerId, read 
this.ctx.props.containerId.
Register the entrypoint in the 
try block of 
startContainer():
export class MySandbox extends DurableObject<Env> {
	// ...
	private async startContainer(): Promise<void> {
		const newContainer = !this.container.running;
		if (newContainer) {
			this.container.start({
				image: this.container.images.sandbox,
				instance: "standard-1",
				env: ENV,
				// 0.12 allowed Internet access by default.
				enableInternet: true,
			});
		}
		try {
			if (newContainer) {
				// Replaces onStart().
				await this.ctx.storage.put("startedAt", Date.now());
			}
			await this.container.interceptOutboundHttp(
				"my.kv",
				this.ctx.exports.KvGateway({
					props: { containerId: this.ctx.id.toString() },
				}),
			);
			await this.container.setInactivityTimeout(
				INACTIVITY_TIMEOUT_MS,
			);
		} catch (error) {
			// The next request starts a new container.
			await this.container.destroy();
			throw error;
		}
	}
}
this.ctx.id.toString() is the value that 0.12 passed as 
containerId, so keys and paths built from it stay the same. The intercept also works with 
enableInternet: false. Register one entrypoint for each hostname.
If your class also uses the 
Outbound entrypoint from Move outbound rules, add the handler to its 
HANDLERS map instead. A hostname intercept that you register after 
interceptAllOutboundHttp() receives no requests.
Request the hostname from the container. After you store 
hello from KV under the key 
greeting, this command prints the value:
node -e 'fetch("http://my.kv/greeting").then(async (r) => console.log(r.status, await r.text()))'
200 hello from KV
Start an OpenCode server
In 0.12, 
createOpencode() started 
opencode serve in the sandbox, and returned an OpenCode SDK client that reached it through the sandbox. In 1.0, your Durable Object starts the server and creates the client, with a 
fetch function that connects to the server port.
Install OpenCode in your 
Dockerfile, as in Run OpenCode in a sandbox:
RUN npm install --global --ignore-scripts opencode-linux-x64-baseline@1.19.4 \
	&& ln -s /usr/local/lib/node_modules/opencode-linux-x64-baseline/bin/opencode /usr/local/bin/opencode
The 0.12 
opencode image included OpenCode. Start the container with the 
standard-1 instance type or larger, as 
startContainer() does. On 
lite, the server did not answer requests within 30 seconds.
Install the OpenCode SDK in your Worker project:
Replace 
createOpencode() with a method that starts the server once for each container. It uses the scripts and functions from step 1 of Run a server in the background:
const sandbox = getSandbox(env.Sandbox, "my-agent");
const { client } = await createOpencode(sandbox, {
	directory: "/workspace",
	config: OPENCODE_CONFIG,
});
const session = await client.session.create({ title: "Fix tests" });
import {
	createOpencodeClient,
	type OpencodeClient,
} from "@opencode-ai/sdk/v2/client";
const OPENCODE_PORT = 4096;
const OPENCODE_DIR = `${SERVERS}/opencode`;
// Your OpenCode configuration, without apiKey values.
const OPENCODE_CONFIG = {};
const OPENCODE = [
	"opencode",
	"serve",
	"--port",
	String(OPENCODE_PORT),
	"--hostname",
	"0.0.0.0",
];
export class MySandbox extends DurableObject<Env> {
	// ...
	private opencodeReady = false;
	private async openCode(): Promise<OpencodeClient> {
		await this.ensureRunning();
		if (!this.opencodeReady) {
			await startServer(this.container, OPENCODE_DIR, OPENCODE, {
				cwd: "/workspace",
				env: {
					...ENV,
					OPENCODE_CONFIG_CONTENT:
						JSON.stringify(OPENCODE_CONFIG),
					ANTHROPIC_API_KEY: this.env.ANTHROPIC_API_KEY,
				},
			});
			await waitForServer(
				this.container,
				OPENCODE_DIR,
				OPENCODE_PORT,
				30_000,
			);
			this.opencodeReady = true;
		}
		const port = this.container.getTcpPort(OPENCODE_PORT);
		return createOpencodeClient({
			baseUrl: "http://opencode",
			fetch: (request) => port.fetch(request),
		});
	}
	async createSession(title: string): Promise<string> {
		const client = await this.openCode();
		const session = await client.session.create({ title });
		if (!session.data) {
			throw new Error("OpenCode did not create the session");
		}
		return session.data.id;
	}
}
Remove 
apiKey from your OpenCode configuration, and store each key as a secret. Like 0.12, the method passes the configuration as 
OPENCODE_CONFIG_CONTENT and the key in a provider variable such as 
ANTHROPIC_API_KEY. The container can read the key. To keep model credentials in your Worker, refer to Run OpenCode in a sandbox.
Set 
this.opencodeReady = false in 
startContainer(), inside 
if (newContainer), because a new container has no server. If your Durable Object restarts while the container runs, 
startServer() finds the server that already runs. Use the client in methods of your class, such as 
createSession().
Serve the OpenCode web UI from the 
fetch() handler of your Durable Object:
export class MySandbox extends DurableObject<Env> {
	// ...
	async fetch(request: Request): Promise<Response> {
		const url = new URL(request.url);
		const accept = request.headers.get("Accept") ?? "";
		const page =
			accept.includes("text/html") || url.pathname === "/";
		// The UI calls the server at the origin in ?url=.
		if (
			request.method === "GET" &&
			page &&
			!url.searchParams.has("url")
		) {
			url.searchParams.set("url", url.origin);
			return Response.redirect(url.toString(), 302);
		}
		await this.openCode();
		// The container port accepts only http: URLs.
		url.protocol = "http:";
		return this.container
			.getTcpPort(OPENCODE_PORT)
			.fetch(new Request(url, request));
	}
}
This replaces 
proxyToOpencode(), which made the same redirect. The UI loads its files from 
/, so serve it at the root of a hostname and forward every path to your Durable Object, for example with 
env.Sandbox.getByName("my-agent").fetch(request). The UI can run commands in the sandbox, so authenticate these requests in your Worker.
Call 
createSession("Fix tests") from your Worker. It returns the new session ID, such as 
ses_f1822cedcffe1CpcMlwM9eQSGZ. Open your Worker URL in a browser. It redirects to 
/?url= and loads OpenCode.
Give OpenAI agents a shell and an editor
In 0.12, 
Shell and 
Editor from 
@cloudflare/sandbox/openai ran the commands and file edits of an OpenAI agent in a sandbox, while the agent ran in your Worker. In 1.0, you write both classes over 
container.exec() and 
Files, and run the agent in your Durable Object, where the container is.
Add a 
Shell that runs each command with 
bash in 
/workspace:
import { Files } from "@cloudflare/sandbox";
import {
	Agent,
	applyDiff,
	applyPatchTool,
	run,
	shellTool,
	type ApplyPatchOperation,
	type ApplyPatchResult,
	type Editor,
	type Shell,
	type ShellAction,
	type ShellResult,
} from "@openai/agents";
class SandboxShell implements Shell {
	constructor(private readonly container: Container) {}
	async run(action: ShellAction): Promise<ShellResult> {
		const timeoutMs = action.timeoutMs ?? 60_000;
		const seconds = String(Math.ceil(timeoutMs / 1000));
		const limit = ["timeout", "--kill-after=5", seconds];
		const output: ShellResult["output"] = [];
		const decoder = new TextDecoder();
		for (const command of action.commands) {
			const process = await this.container.exec(
				[...limit, "bash", "-c", command],
				{ cwd: "/workspace", env: ENV },
			);
			const result = await process.output();
			const timedOut = result.exitCode === 124 || result.exitCode === 137;
			output.push({
				stdout: decoder.decode(result.stdout),
				stderr: decoder.decode(result.stderr),
				outcome: timedOut
					? { type: "timeout" }
					: { type: "exit", exitCode: result.exitCode },
			});
			// 0.12 also skipped the rest after a timeout.
			if (timedOut) {
				break;
			}
		}
		return {
			output,
			providerData: { working_directory: "/workspace" },
		};
	}
}
timeout stops the command and the processes it started that stay in its process group. The command exits with code 
124, or 
137 if 
timeout also sends 
SIGKILL. 0.12 set no time limit when the action had no 
timeoutMs, and this class sets 60 seconds.
Add an 
Editor that applies the patches from the agent with 
Files:
type Operation<T> = Extract<ApplyPatchOperation, { type: T }>;
class SandboxEditor implements Editor {
	constructor(private readonly files: Files) {}
	// Reads each path as relative to /workspace, as 0.12 did, and throws
	// when `..` leaves /workspace.
	private path(path: string): string {
		const root = "/workspace";
		const inRoot = path === root || path.startsWith(`${root}/`);
		const relative = inRoot ? path.slice(root.length) : path;
		const segments: string[] = [];
		for (const segment of relative.split("/")) {
			if (segment === "..") {
				if (segments.pop() === undefined) {
					throw new Error(`Operation outside workspace: ${path}`);
				}
			} else if (segment !== "" && segment !== ".") {
				segments.push(segment);
			}
		}
		return [root, ...segments].join("/");
	}
	async createFile(
		operation: Operation<"create_file">,
	): Promise<ApplyPatchResult> {
		const path = this.path(operation.path);
		const parent = path.slice(0, path.lastIndexOf("/"));
		await this.files.mkdir(parent, { recursive: true });
		const content = applyDiff("", operation.diff, "create");
		await this.files.writeFile(path, content);
		return {
			status: "completed",
			output: `Created ${operation.path}`,
		};
	}
	async updateFile(
		operation: Operation<"update_file">,
	): Promise<ApplyPatchResult> {
		const path = this.path(operation.path);
		const file = await this.files.readFile(path);
		const current = await file.text();
		const content = applyDiff(current, operation.diff);
		await this.files.writeFile(path, content);
		return {
			status: "completed",
			output: `Updated ${operation.path}`,
		};
	}
	async deleteFile(
		operation: Operation<"delete_file">,
	): Promise<ApplyPatchResult> {
		await this.files.remove(this.path(operation.path));
		return {
			status: "completed",
			output: `Deleted ${operation.path}`,
		};
	}
}
path() reads 
/etc/passwd as 
/workspace/etc/passwd, and throws for 
../etc/passwd, as 0.12 did. It checks the path only. A symbolic link in 
/workspace can still point outside it. For more information, refer to Accept paths from callers.
A failed 
Files call throws 
SandboxFileError. Both 0.12 classes kept a 
results list, and the 0.12 
Editor added a 
failed result to it before it threw the error again. If your code read the list, record results in each method.
Run the agent in a method of your class:
const sandbox = getSandbox(env.Sandbox, `session-${sessionId}`);
const agent = new Agent({
	name: "Sandbox agent",
	instructions: INSTRUCTIONS,
	tools: [
		shellTool({ shell: new Shell(sandbox) }),
		applyPatchTool({
			editor: new Editor(sandbox, "/workspace"),
		}),
	],
});
const result = await run(agent, input);
export class MySandbox extends DurableObject<Env> {
	// ...
	private readonly files = new Files(this.container);
	async runAgent(input: string): Promise<string | undefined> {
		await this.ensureRunning();
		const shell = new SandboxShell(this.container);
		const editor = new SandboxEditor(this.files);
		const agent = new Agent({
			name: "Sandbox agent",
			instructions: INSTRUCTIONS,
			tools: [shellTool({ shell }), applyPatchTool({ editor })],
		});
		const result = await run(agent, input);
		return result.finalOutput;
	}
}
Your Worker calls 
runAgent() on the stub that 
getByName() returns. The Agents SDK reads 
OPENAI_API_KEY from the environment, as it did in your Worker.
If your class already has the 
files field from Change file calls, keep one of the two.
Check both classes without a model by calling them directly. 
shell.run({ commands: ["pwd", "sleep 10"], timeoutMs: 2000 }) returns the working directory, then a timeout:
{
	"output": [
		{
			"stdout": "/workspace\n",
			"stderr": "",
			"outcome": { "type": "exit", "exitCode": 0 }
		},
		{
			"stdout": "",
			"stderr": "",
			"outcome": { "type": "timeout" }
		}
	],
	"providerData": { "working_directory": "/workspace" }
}
editor.createFile({ type: "create_file", path: "notes/todo.md", diff: "+first\n+second\n" }) returns 
{ "status": "completed", "output": "Created notes/todo.md" }. 
/workspace/notes/todo.md then contains the lines 
first and 
second.
Replace the bridge
The 0.12 bridge, 
bridge() from 
@cloudflare/sandbox/bridge, served an HTTP API over 
Sandbox calls for clients outside Workers, and checked a 
SANDBOX_API_KEY bearer token. 1.0 has no bridge. Add a Worker route for each call that your client makes, and have the route call a method of your Durable Object. Check the token in your Worker, as the bridge did.
Clients written for the bridge API, such as 
CloudflareSandboxClient in the OpenAI Agents SDK for Python, work only with a 0.x bridge Worker. Keep that Worker on 0.x until your client calls your own routes.
Remove WarmPool
Start each sandbox when a request needs it, and remove 
WarmPool. The pool kept 0.x sandboxes started ahead of time, because a 0.x start took seconds. With the Durable Object scheduling policy, the median time from creating a sandbox to running a command in it was 648 milliseconds in an independent benchmark, so a pool saves little time.
Remove the 
WarmPool export from the main module of your Worker, and its binding from 
durable_objects in the Wrangler configuration.
Delete the class in the same way your Worker added it. If your Worker uses 
migrations, add a migration:
{
	"migrations": [
		{ "new_sqlite_classes": ["Sandbox"], "tag": "v1" },
		{ "new_sqlite_classes": ["WarmPool"], "tag": "v2" },
		{ "deleted_classes": ["WarmPool"], "tag": "v3" },
	],
}
If your Worker uses 
exports, mark the class as deleted instead:
{
	"exports": {
		"WarmPool": {
			"type": "durable-object",
			"state": "deleted",
		},
	},
}
Remove the 
WARM_POOL_TARGET, 
WARM_POOL_REFRESH_INTERVAL, 
WARM_POOL_MAX_INSTANCES, and 
WARM_POOL_SCALE_BATCH_SIZE variables. 
bridge() filled the pool from its 
scheduled() handler, so remove the cron trigger too if nothing else uses it.
The sandboxes that the pool started are 0.12 sandboxes, so Plan the move covers them like any other.
If your application still needs those last milliseconds, call 
start() for the sandbox that a user is about to use, for example when they open a session. Do not keep a pool of started sandboxes. Each one is billed while it waits, and your code must assign it to a session.
Related resources
Docker-in-Docker in the Containers FAQ
Durable Object Container API
Move outbound rules
Run OpenCode in a sandbox
Files API

Move outbound rules
import { Steps } from "~/components";
In Sandbox SDK 0.12, 
ContainerProxy applies the outbound fields of your 
Sandbox class to each request that the container sends. In 1.0, your Durable Object registers your own 
WorkerEntrypoint for HTTP and HTTPS requests from the container, and the entrypoint applies the same rules in the same order.
Before you start
Your 1.0 class replaces the 0.12 
Sandbox class, and has the 
container getter, the 
ensureRunning() and 
startContainer() methods, and the 
ENV and 
INACTIVITY_TIMEOUT_MS constants from Replace the Sandbox class. The entrypoint uses 
this.ctx.exports, which needs compatibility date 
2025-11-17 or later, or the 
enable_ctx_exports flag. 0.12 outbound rules needed it too.
This page replaces 
enableInternet, 
interceptHttps, 
allowedHosts, 
deniedHosts, 
outbound, 
outboundByHost, 
outboundHandlers, their aliases 
outboundProxy and 
outboundProxies, the runtime setters such as 
allowHost() and 
setOutboundByHost(), and 
gitCheckout(). Remove 
ContainerProxy from your imports and from the exports of your Worker. For the handlers that 0.12 added for bucket mounts, refer to Move bucket mounts.
Apply the rules in an entrypoint
Copy the outbound fields of your 0.12 class into constants, and give each handler a name:
type Handler = { method: string; params?: unknown };
type OutboundHandler = (
	request: Request,
	env: Env,
	params: unknown,
) => Response | Promise<Response>;
// The outbound fields of your 0.12 class.
const ENABLE_INTERNET = false;
const ALLOWED_HOSTS: string[] | undefined = [
	"github.com",
	"registry.npmjs.org",
	"api.example.com",
];
const DENIED_HOSTS: string[] | undefined = undefined;
const OUTBOUND_BY_HOST: Record<string, Handler> = {
	"api.example.com": { method: "withToken" },
};
const OUTBOUND: Handler | undefined = undefined;
// Your 0.12 handlers, by name.
const HANDLERS: Record<string, OutboundHandler> = {
	withToken: (request, env) => {
		const headers = new Headers(request.headers);
		headers.set("Authorization", `Bearer ${env.API_TOKEN}`);
		return fetch(new Request(request, { headers }));
	},
};
If your 0.12 class did not set 
enableInternet, set 
ENABLE_INTERNET to 
true, the 0.12 default. For a field that your class did not set, use 
{} for 
OUTBOUND_BY_HOST and 
undefined for the other constants.
Put every function from 
outboundHandlers, 
outboundByHost, and 
outbound in 
HANDLERS, and refer to them by name in 
OUTBOUND_BY_HOST and 
OUTBOUND. A 0.12 handler takes 
(request, env, ctx). Change it to take 
(request, env, params), and read 
params where it read 
ctx.params.
Add 
WorkerEntrypoint to your 
cloudflare:workers import, and add the entrypoint, which checks each request in the order that 0.12 used:
import { WorkerEntrypoint } from "cloudflare:workers";
// The shape that 0.12 stored under OUTBOUND_CONFIGURATION.
type StoredRules = {
	outboundByHostOverrides?: Record<string, Handler>;
	outboundHandlerOverride?: Handler;
	allowedHosts?: string[];
	deniedHosts?: string[];
};
// "*" matches any run of characters, as in 0.12.
function matches(pattern: string, hostname: string): boolean {
	const escaped = pattern
		.split("*")
		.map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"));
	return new RegExp(`^${escaped.join(".*")}$`).test(hostname);
}
function lookup(
	handlers: Record<string, Handler> | undefined,
	hostname: string,
): Handler | undefined {
	return (
		handlers?.[hostname] ??
		Object.entries(handlers ?? {}).find(([pattern]) =>
			matches(pattern, hostname),
		)?.[1]
	);
}
export class Outbound extends WorkerEntrypoint<Env, StoredRules> {
	async fetch(request: Request): Promise<Response> {
		const rules = this.ctx.props;
		const allowed = rules.allowedHosts ?? ALLOWED_HOSTS;
		const denied = rules.deniedHosts ?? DENIED_HOSTS;
		const url = new URL(request.url);
		const hostname = url.hostname.replace(/\.+$/, "");
		const listed = (patterns: string[]) =>
			patterns.some((pattern) => matches(pattern, hostname));
		const blocked = new Response("Origin is disallowed", {
			status: 520,
		});
		if (denied && listed(denied)) {
			return blocked;
		}
		if (allowed && !listed(allowed)) {
			return blocked;
		}
		const handler = [
			lookup(rules.outboundByHostOverrides, hostname),
			lookup(OUTBOUND_BY_HOST, hostname),
			rules.outboundHandlerOverride,
			OUTBOUND,
		].find((handler) => handler && HANDLERS[handler.method]);
		if (handler) {
			const run = HANDLERS[handler.method];
			return run(request, this.env, handler.params);
		}
		if (allowed || ENABLE_INTERNET) {
			return fetch(request);
		}
		return blocked;
	}
}
The entrypoint blocks denied hostnames, then hostnames outside the allowed list. Next, it runs the first handler that matches, in this order: a hostname handler that the sandbox set at runtime, a hostname handler from your class, the catch-all handler set at runtime, and the catch-all handler of your class. With no handler, it sends the request to the Internet if you set an allowed list or allow the Internet. A blocked request gets status 
520 with the body 
Origin is disallowed, as in 0.12.
The props carry the rules that the sandbox set at runtime, in the shape 0.12 stored them. Like 0.12, the entrypoint skips a handler whose name is not in 
HANDLERS, such as the handlers that 0.12 stored for bucket mounts.
Add the certificate variables to 
ENV, and register the entrypoint in 
startContainer():
const RULES = "OUTBOUND_CONFIGURATION";
const CA = "/etc/cloudflare/certs/cloudflare-containers-ca.crt";
const BUNDLE = "/etc/ssl/certs/ca-certificates.crt";
const ENV = {
	NODE_ENV: "test",
	NODE_EXTRA_CA_CERTS: CA,
	REQUESTS_CA_BUNDLE: BUNDLE,
};
// Keep a copy of the system bundle, wait up to 10 seconds for the
// certificate, then write the bundle from the copy and the certificate.
const SYSTEM = "/etc/ssl/certs/ca-certificates.system.crt";
const CA_WAIT = `until [ -s ${CA} ]; do sleep 0.1; done`;
const CA_READY = `timeout 10 sh -c '${CA_WAIT}'`;
const TRUST = [
	"sh",
	"-c",
	`[ -e ${SYSTEM} ] || { cp ${BUNDLE} ${SYSTEM}.tmp && mv ${SYSTEM}.tmp ${SYSTEM}; }
	${CA_READY} && cat ${SYSTEM} ${CA} >${BUNDLE}.tmp && mv ${BUNDLE}.tmp ${BUNDLE}`,
];
export class MySandbox extends DurableObject<Env> {
	// ...
	private rules(): StoredRules {
		return this.ctx.storage.kv.get<StoredRules>(RULES) ?? {};
	}
	private async intercept(): Promise<void> {
		const props = this.rules();
		const outbound = this.ctx.exports.Outbound({ props });
		await this.container.interceptAllOutboundHttp(outbound);
		await this.container.interceptOutboundHttps("*", outbound);
	}
	private async trust(): Promise<void> {
		const trust = await this.container.exec(TRUST);
		if ((await trust.exitCode) !== 0) {
			throw new Error("The container did not trust the intercept CA");
		}
	}
	private async startContainer(): Promise<void> {
		const newContainer = !this.container.running;
		if (newContainer) {
			this.container.start({
				image: this.container.images.sandbox,
				instance: "standard-1",
				env: ENV,
				enableInternet: ENABLE_INTERNET,
			});
		}
		try {
			if (newContainer) {
				// Replaces onStart().
				await this.ctx.storage.put("startedAt", Date.now());
			}
			await this.intercept();
			await this.trust();
			await this.container.setInactivityTimeout(
				INACTIVITY_TIMEOUT_MS,
			);
		} catch (error) {
			// The next request starts a new container.
			await this.container.destroy();
			throw error;
		}
	}
}
// ... stands for the constructor, the 
container getter, and your other methods. 
rules() reads the key where 0.12 stored the rules that each sandbox set at runtime, so those rules keep applying after the switch. If you move sandboxes side by side, 
copyFrom0x() copies the key into the 1.0 class.
The intercepts send every request on port 
80, and every HTTPS request on port 
443, to the entrypoint. 
enableInternet keeps the 0.12 value and still decides connections on other ports. An intercept lasts until the container stops. 
startContainer() registers it for each new container, and again when a restarted Durable Object finds the container running. Registering it again replaces the earlier registration, so a container whose setup a deploy interrupted still gets its intercepts before the next command.
Register other intercepts, such as bucket mounts, before 
intercept(). A hostname intercept that you register after 
intercept() never receives requests, because the 
Outbound entrypoint receives them. For more information, refer to If you moved outbound rules.
If your class uses 
DirectoryBackup from Move backups, call 
this.backups.intercept() in the 
try block, before your 
intercept(). Otherwise every backup and restore fails with 
BACKUP_TRANSFER, because your 
Outbound entrypoint receives backup requests from the container. Call it only in 
startContainer(), not on every request.
The HTTPS intercept signs responses with a certificate that the container does not trust by default. As in 0.12, the 
TRUST command adds the certificate to the system bundle, which curl and Git read. 
ENV sets 
NODE_EXTRA_CA_CERTS and 
REQUESTS_CA_BUNDLE for Node.js and Python 
requests, which do not read the bundle by default. Keep your other 
ENV values, and pass 
ENV to each 
exec() call. The image needs the 
ca-certificates package, which provides the bundle.
The certificate appears once the HTTPS intercept is registered. 
TRUST waits up to 10 seconds for it. 0.12 waited up to 5 seconds. If the certificate does not appear, or the append fails, 
trust() throws, and 
startContainer() stops the container. Each container gets a new certificate. A snapshot saves the bundle with the certificate of the container it came from, so appending to the bundle would keep certificates from earlier containers. 
TRUST therefore keeps a copy of the system bundle as it was before any certificate was added, and writes the bundle again from that copy and the current certificate. Running it again for the same container writes the same bundle.
Replace the runtime setters
Add methods that update the stored rules, and register the entrypoint again with them:
export class MySandbox extends DurableObject<Env> {
	// ...
	private async updateRules(change: StoredRules): Promise<void> {
		this.ctx.storage.kv.put(RULES, { ...this.rules(), ...change });
		if (this.container.running) {
			await this.intercept();
		}
	}
	async allowHost(hostname: string): Promise<void> {
		const hosts = this.rules().allowedHosts ?? ALLOWED_HOSTS ?? [];
		await this.updateRules({ allowedHosts: [...hosts, hostname] });
	}
	async setOutboundByHost(
		hostname: string,
		method: string,
		params?: unknown,
	): Promise<void> {
		const hosts = { ...this.rules().outboundByHostOverrides };
		hosts[hostname] = { method, params };
		await this.updateRules({ outboundByHostOverrides: hosts });
	}
}
Registering the entrypoint again replaces the rules of a running container, and open connections pick up the new rules without being dropped. Write the other setters the same way. Each one passes a new value to 
updateRules():
0.12
Value to pass
setAllowedHosts(hosts), 
setDeniedHosts(hosts)
allowedHosts or 
deniedHosts, set to 
hosts
denyHost(), 
removeAllowedHost(), 
removeDeniedHost()
deniedHosts or 
allowedHosts, with the hostname added or removed
setOutboundByHosts(), 
removeOutboundByHost()
outboundByHostOverrides, with the hostnames added or removed
setOutboundHandler(method, params)
outboundHandlerOverride, set to 
{ method, params }
Like 0.12, each list that a sandbox sets replaces the class list for that sandbox.
What changes for requests
0.12 checked HTTPS requests only when your class set 
interceptHttps = true. Without it, HTTPS requests to allowed hostnames failed when 
enableInternet was 
false, and HTTPS requests to denied hostnames succeeded when it was 
true. The entrypoint checks every HTTPS request, so commands that relied on either behavior now follow your rules.
In 0.12, handlers that your class declared as static fields, such as 
static outboundByHost = { … }, never ran when TypeScript compiled class fields as definitions. That is the default for target ES2022 and later. The field skipped the setter that registers the handlers, so requests to those hostnames went to the Internet or got 
520. In 1.0, the handlers run.
HTTPS requests to an IP address, such as 
https://203.0.113.10/, fail while 
* is intercepted and 
enableInternet is 
false. Use a hostname.
Replace gitCheckout()
In 0.12, 
gitCheckout() clones a repository into 
/workspace:
const repo = "https://github.com/octocat/Hello-World";
await sandbox.gitCheckout(repo, { depth: 1 });
In 1.0, run 
git clone in a Durable Object method:
export class MySandbox extends DurableObject<Env> {
	// ...
	async clone(url: string, dir: string): Promise<void> {
		await this.ensureRunning();
		const git = ["git", "clone", "--filter=blob:none", "--depth", "1"];
		const clone = await this.container.exec(
			["timeout", "-k", "5", "600", ...git, "--", url, dir],
			{ cwd: "/workspace", env: ENV },
		);
		const output = await clone.output();
		if (output.exitCode !== 0) {
			throw new Error(new TextDecoder().decode(output.stderr));
		}
	}
}
0.12 cloned with 
--filter=blob:none into 
/workspace/<repository name>, and stopped the clone after 600 seconds. Pass 
--branch for the 
branch option. To read the branch that 0.12 returned, run 
git branch --show-current with 
cwd set to the clone. The image needs Git, and your rules must allow the hostname of the Git server, such as 
github.com. To clone a private repository without giving the sandbox a token, refer to Clone a private repository.
Check the rules
After you deploy the switch, run these commands in a sandbox whose image has 
curl and Git. A hostname that your rules block returns the 0.12 response:
curl -s -w ' %{http_code}\n' https://example.com/
Origin is disallowed 520
An allowed hostname works over HTTPS without a certificate option on the command:
git ls-remote https://github.com/octocat/Hello-World HEAD
7fd1a60b01f91b314f59955a4e4d4e80d8edf11d	HEAD
In a sandbox that called 
allowHost() in 0.12, requests to that hostname still succeed after the switch.
Related resources
Durable Object container API
Handle outbound traffic
Call an authenticated API from a sandbox
Clone a private repository
Move bucket mounts

Plan the move to Sandbox SDK 1.0
import { PackageManagers, Steps } from "~/components";
This page compares the two ways to move sandboxes from Sandbox SDK 0.12 to 1.0, and then moves every sandbox in one deploy. You cannot undo the deploy that switches your sandboxes to 1.0.
Before you start
Your application runs 
@cloudflare/sandbox 0.12.14.
Your 1.0 class is written. For the class, refer to Replace the Sandbox class.
You have a staging copy of the Worker with its own Wrangler configuration file. Set a different Worker 
name and a different 
name for each container in that file, because the 
--name option of 
wrangler deploy does not rename container applications.
Choose a path
You can move in one of two ways:
Path
What happens
Suits
In place
One deploy moves every sandbox to 1.0. Commands that run in 0.12 containers end, and files in those containers do not carry over.
Sandboxes that are short-lived or cheap to create again
Side by side
A 1.0 class runs next to the 0.12 class in the same Worker. Your code moves each sandbox, and you delete the 0.12 class when none remain.
Long-lived sandboxes that users return to
Neither path can split traffic with a gradual deployment. Wrangler rejects a deployment that mixes the two versions with this error:
All Worker Versions in a multi-version deployment must declare identical Durable Object-managed Container applications.
Rehearse your path on the staging Worker, with sandboxes running in it, before you follow it in production. The rest of this page moves in place. For the other path, refer to Move sandboxes side by side.
What the switch does to live sandboxes
The switch happens when the deploy that moves your class to 
scheduling_policy: "durable_object" goes live. Each part of a 0.12 sandbox changes as follows:
Part
At the switch
Running containers
Keep running in the old container application. For a short time after the deploy, your Durable Object still reports 
running as 
true, and 
exec() and 
getTcpPort() reach the 0.12 container. After that, 
running is 
false, and your code starts a 1.0 container.
Files
Stay in the old containers. New containers start without them.
Running commands
End shortly after. A command that returns its result when it finishes fails with HTTP 500. Streamed output stops with HTTP 200 and no error.
WebSockets
Stop delivering data. Clients receive no close frame.
Pending alarms
Call your 1.0 
alarm() handler once for each sandbox that was active.
schedule() callbacks
Never run.
0.12 storage keys
Stay in Durable Object storage. The pages that move preview URLs, tunnels, and outbound rules read 
portTokens, 
tunnels, 
tunnels:meta, and 
OUTBOUND_CONFIGURATION.
Move every sandbox in one deploy
Make your 
alarm() handler check its own state before it acts. 0.12 keeps an alarm set while a container runs, and after the switch that alarm calls your handler. If the handler throws, the platform retries it with backoff. In this example, the handler returns unless its 
nextCheckpoint time has passed:
export class MySandbox extends DurableObject<Env> {
	// ...
	async alarm(): Promise<void> {
		// A 0.12 alarm can call this handler once after the switch.
		const due = await this.ctx.storage.get<number>("nextCheckpoint");
		if (due === undefined || due > Date.now()) {
			return;
		}
		await this.checkpoint();
	}
}
If your class has no 
alarm() handler, each pending alarm fails once with an internal error in your logs and then clears.
Replace 
schedule() calls. 0.12 stores scheduled callbacks in a table that 1.0 does not read. Set the next run with 
this.ctx.storage.setAlarm() from your class, and do the work in 
alarm(). A Durable Object has one alarm, so this is the handler from step 1. To replace several schedules, store the time of each, set the alarm to the earliest, and run every task that is due in 
alarm(). For more information, refer to Alarms.
Prepare clients for sockets that go silent. Open terminals and preview WebSockets stop receiving data at the switch, and the browser does not see them close. Have your client reconnect when a socket receives nothing for a set time, or tell users to reload after the deploy.
Save the files that users need. Once a 0.12 container stops, its files are gone, and the short time after the deploy when 1.0 code still reaches it is no way to copy them. Before you deploy, save the files with 0.12 
createBackup(). After the switch, restore them as Move backups describes.
Rehearse on the staging Worker first. With sandboxes running there and a client connected, upload and deploy the 1.0 version to the staging Worker as steps 6 and 7 describe. Check that requests from your application work after the switch.
Upload the 1.0 version:
The upload builds the 1.0 image and creates the new container application. The version that serves traffic does not change. Note the version ID that Wrangler prints.
Deploy the version when no long commands run.
:::caution
You cannot undo this deploy. After it, a 
wrangler rollback to a 0.12 version either fails or deploys 0.12 code that cannot start containers. If something breaks, fix it and deploy again.
:::
Replace 
<VERSION_ID> with the ID from the upload:
Check the move
Send requests from your application to a sandbox, such as a command and a file read. Each Durable Object starts a 1.0 container on its first request once 
running is 
false. For a short time after the deploy, a request can still reach the 0.12 container, where a command runs in the 0.12 image. Wait a few minutes after the deploy before you check. List the container applications in your account:
The list shows the new application with the 
name you set. The old application is still there. Wrangler named it from your Worker and class names, such as 
my-worker-sandbox.
Clean up
Delete the old container application. Replace 
<OLD_APPLICATION_ID> with its ID from the list:
The old application runs its containers, and bills for them, until you delete it. Deleting it stops the containers that 0.12 started and deletes their files. Durable Objects and their storage stay.
The keys that 0.12 wrote stay in the storage of each Durable Object. Keep 
portTokens, 
tunnels, 
tunnels:meta, and 
OUTBOUND_CONFIGURATION while your class reads them, as the pages that move preview URLs, tunnels, and outbound rules do. If you delete other keys, name each key in a 
delete() call. Do not call 
deleteAll(), which also deletes your own keys and any 0.12 backup handles that you still need to convert.
Related resources
Move sandboxes side by side
Replace the Sandbox class
Changes in Sandbox SDK 1.0
Gradual deployments

Move preview URLs
import { Steps } from "~/components";
In Sandbox SDK 0.12, 
exposePort() stores a token for each port in Durable Object storage. 
proxyToSandbox() routes hostnames such as 
8080-ada-<TOKEN>.example.com to the server on that port. In 1.0, your Worker routes those hostnames, and your Durable Object checks the token and forwards the request with 
getTcpPort(). The code on this page reads the tokens where 0.12 stored them, so the preview URLs that your users already have keep working.
Before you start
Your 1.0 class replaces the 0.12 
Sandbox class and keeps its name and its 
Sandbox binding. For the class, refer to Replace the Sandbox class.
This page replaces 
exposePort(), 
unexposePort(), 
getExposedPorts(), 
isPortExposed(), 
validatePortToken(), 
proxyToSandbox(), and 
wsConnect(). Keep the wildcard DNS record, the certificate, and the Worker route that serve your preview hostnames. 1.0 uses them unchanged.
This page does not cover the server that a preview reaches. To start it, refer to Move background processes.
Replace the preview calls
Add these declarations to the top level of 
src/index.ts:
type PortToken = { token: string; name?: string };
type Stored = Record<string, string | PortToken>;
// The key where 0.12 stored preview tokens.
const PORT_TOKENS = "portTokens";
function previewUrl(
	port: number,
	name: string,
	token: string,
	hostname: string,
): string {
	return `https://${port}-${name}-${token}.${hostname}/`;
}
// 16 characters from [a-z0-9_], as 0.12 generated them.
function generateToken(): string {
	const bytes = crypto.getRandomValues(new Uint8Array(12));
	return btoa(String.fromCharCode(...bytes))
		.replace(/[+/]/g, "_")
		.toLowerCase();
}
Add a method that reads the tokens, and 
exposePort(), to your Durable Object class:
export class MySandbox extends DurableObject<Env> {
	// ...
	private async readPortTokens(): Promise<Record<string, PortToken>> {
		const stored = await this.ctx.storage.get<Stored>(PORT_TOKENS);
		const tokens: Record<string, PortToken> = {};
		// Early 0.12 versions stored the token as a string.
		for (const [port, value] of Object.entries(stored ?? {})) {
			tokens[port] =
				typeof value === "string" ? { token: value } : value;
		}
		return tokens;
	}
	async exposePort(
		sandboxName: string,
		port: number,
		options: { hostname: string; name?: string; token?: string },
	) {
		if (!Number.isInteger(port) || port < 1024 || port > 65535) {
			throw new Error(`Invalid port number: ${port}`);
		}
		if (options.token && !/^[a-z0-9_]{1,16}$/.test(options.token)) {
			throw new Error(`Invalid token: ${options.token}`);
		}
		const tokens = await this.readPortTokens();
		const token =
			options.token ?? tokens[port]?.token ?? generateToken();
		tokens[port] = { token, name: options.name };
		await this.ctx.storage.put(PORT_TOKENS, tokens);
		return {
			url: previewUrl(port, sandboxName, token, options.hostname),
			port,
			name: options.name,
		};
	}
}
The method stores tokens in the format that 0.12 used, and returns the same URL as 0.12. Unlike 0.12, it does not start the container. 0.12 read the sandbox name from its own storage, so pass the name from your Worker:
const sandbox = env.Sandbox.getByName(name);
const { url } = await sandbox.exposePort(name, 8080, {
	hostname: "example.com",
});
Add the other port methods to the class:
export class MySandbox extends DurableObject<Env> {
	// ...
	async unexposePort(port: number): Promise<void> {
		const tokens = await this.readPortTokens();
		delete tokens[port];
		await this.ctx.storage.put(PORT_TOKENS, tokens);
	}
	async getExposedPorts(sandboxName: string, hostname: string) {
		const tokens = await this.readPortTokens();
		return Object.entries(tokens).map(([port, { token }]) => ({
			url: previewUrl(Number(port), sandboxName, token, hostname),
			port: Number(port),
			status: "active" as const,
		}));
	}
	async isPortExposed(port: number): Promise<boolean> {
		const tokens = await this.readPortTokens();
		return port in tokens;
	}
	async validatePortToken(
		port: number,
		token: string,
	): Promise<boolean> {
		const tokens = await this.readPortTokens();
		const expected = tokens[port]?.token;
		if (expected === undefined) {
			return false;
		}
		// Compare in constant time, so timing does not reveal the token.
		const encoder = new TextEncoder();
		const a = encoder.encode(expected);
		const b = encoder.encode(token);
		if (a.byteLength !== b.byteLength) {
			return false;
		}
		return crypto.subtle.timingSafeEqual(a, b);
	}
}
0.12 
getExposedPorts() and 
isPortExposed() reported a port only after 
exposePort() ran in the current container. These methods report every stored port, because the Durable Object forwards requests to any stored port.
0.12 
destroy() deleted the tokens. Where your code calls 
destroy() to end a sandbox, also call 
this.ctx.storage.delete(PORT_TOKENS).
Route preview hostnames in your Worker. In 0.12, 
proxyToSandbox() runs before your other routes:
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const proxied = await proxyToSandbox(request, env);
		if (proxied) {
			return proxied;
		}
		// Your other routes.
	},
};
In 1.0, your Worker reads the port, the sandbox name, and the token from the hostname, and checks the token:
// <port>-<sandbox name>-<token>, as 0.12 issued preview hostnames.
const PREVIEW = /^(\d{4,5})-([a-z0-9-]{1,63})-([a-z0-9_]{1,63})\./;
// The Durable Object forwards to the port in this header.
function toPort(request: Request, port: number): Request {
	const headers = new Headers(request.headers);
	headers.set("X-Sandbox-Port", String(port));
	return new Request(request, { headers });
}
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);
		const preview = PREVIEW.exec(url.hostname);
		if (preview) {
			const [, portText, name, token] = preview;
			const port = Number(portText);
			const sandbox = env.Sandbox.getByName(name);
			if (!(await sandbox.validatePortToken(port, token))) {
				return new Response("Not found", { status: 404 });
			}
			return sandbox.fetch(toPort(request, port));
		}
		// Your other routes.
	},
} satisfies ExportedHandler<Env>;
The expression splits the first label as 0.12 did. The port ends at the first hyphen, and the token starts after the last hyphen. A wrong token, or a port without a token, gets 
404, as in 0.12.
The Durable Object trusts the 
X-Sandbox-Port header, and 
toPort() replaces any value that the visitor sent. Send requests to the 
fetch() handler of your Durable Object only through 
toPort(), or remove the header first, as Move browser terminals does.
Forward the request from the 
fetch() handler of your Durable Object:
export class MySandbox extends DurableObject<Env> {
	// ...
	async fetch(request: Request): Promise<Response> {
		const container = this.ctx.container;
		const port = Number(request.headers.get("X-Sandbox-Port"));
		// Preview requests do not start the container.
		if (!container?.running) {
			return new Response("The sandbox is not running", {
				status: 503,
			});
		}
		const url = new URL(request.url);
		url.protocol = "http:";
		const forwarded = new Request(url, request);
		forwarded.headers.delete("X-Sandbox-Port");
		try {
			const tcpPort = container.getTcpPort(port);
			const response = await tcpPort.fetch(forwarded);
			if (response.webSocket) {
				return bridge(response);
			}
			return response;
		} catch {
			return new Response("Nothing is listening on this port", {
				status: 503,
			});
		}
	}
}
Copy the 
bridge() function from Keep WebSocket connections open. A WebSocket that only passes through the Durable Object does not keep the container running, so the bridge accepts both ends.
The server receives the preview hostname in the 
Host header. 0.12 sent 
localhost:<PORT> and put the preview hostname in 
X-Forwarded-Host. If your server checks either header, as Vite does with 
server.allowedHosts, update its configuration.
Replace each 
wsConnect() call in your Worker. In 0.12, it connects a WebSocket to a port:
if (request.headers.get("Upgrade") === "websocket") {
	return getSandbox(env.Sandbox, name).wsConnect(request, 8080);
}
In 1.0, send the request through 
toPort() to the same 
fetch() handler:
if (request.headers.get("Upgrade") === "websocket") {
	return env.Sandbox.getByName(name).fetch(toPort(request, 8080));
}
The request does not start the container, so start the server before a page connects. Because this route has no token, keep the checks that your Worker runs before the call.
What happens to live previews
Your Durable Objects keep the 
portTokens key when you deploy the switch in place. After the switch, preview URLs behave as follows:
Request
Result
A URL that 0.12 issued
Returns 
503 until a server listens on its port in the new container, and then reaches that server. For a short time after the deploy, it can still reach the 0.12 server.
Any URL after a container starts again
Reaches the server without another 
exposePort() call. 0.12 returned 
410 until you exposed the port again.
A wrong token, or a port without a token
Returns 
404.
A URL after 
unexposePort()
Returns 
404.
If you move sandboxes side by side, 
copyFrom0x() copies the tokens into the 1.0 class. In the preview route of your Worker, get the stub with 
await sandboxFor(env, name).
Check preview URLs
Deploy to your staging Worker, and start a server in a sandbox that had a preview URL in 0.12. Request that URL:
curl https://8080-ada-<TOKEN>.example.com/
The response comes from your server. Request the same port with a wrong token:
curl https://8080-ada-wrong.example.com/ --write-out " %{http_code}\n"
Not found 404
Related resources
Preview a web application
Serve previews on their own hostnames
Move tunnels
getTcpPort()

Replace the Sandbox class
import { PackageManagers, Steps, WranglerConfig } from "~/components";
Replace the 0.12 
Sandbox class with a Durable Object class that you write. In 0.12, your Worker calls package methods through 
getSandbox(). In 1.0, your class starts the container through 
this.ctx.container, and your Worker calls the methods that your class defines.
Before you start
Your application runs 
@cloudflare/sandbox 0.12.14. This page replaces the 
Sandbox class, whether you export it from the package or extend it. It also replaces 
getSandbox() and its options, class fields such as 
sleepAfter and 
envVars, and the hooks 
onStart(), 
onStop(), 
onError(), and 
onActivityExpired().
The page ends with the Worker running under 
wrangler dev. You cannot undo the deploy that switches your sandboxes to 1.0. Before you deploy, follow Plan the move to Sandbox SDK 1.0.
The steps keep your class name, which moves every sandbox in place. To move sandboxes side by side, write the class under a new name, such as 
SandboxV1, and add its Wrangler configuration as Move sandboxes side by side describes.
Replace the class
Install version 1 of the package:
Replace the 
FROM docker.io/cloudflare/sandbox line in your 
Dockerfile with a base image that has the tools your commands use, and copy the 
sandbox-shim helper into it:
FROM node:24-trixie-slim
RUN apt-get update \
	&& apt-get install -y --no-install-recommends \
		ca-certificates git python3 \
	&& rm -rf /var/lib/apt/lists/*
COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim
WORKDIR /workspace
CMD ["sleep", "infinity"]
The 0.12 image included Python, Node.js, and Git. Keep the ones your commands use. 
Files, 
S3Mount, and 
DirectoryBackup need 
sandbox-shim. Match its tag to the 
@cloudflare/sandbox version that you installed. Remove 
EXPOSE lines, which 1.0 does not use. Commands that 
exec() runs do not see 
ENV lines, so pass those values in the 
env option instead.
Change the 
containers entry for your class in the Wrangler configuration. Keep your class name and its binding, so each name reaches the Durable Object and storage it reached in 0.12. Replace 
my-worker-mysandbox-v2 with a name that your account does not use yet:
{
	"containers": [
		{
			"class_name": "MySandbox",
			"name": "my-worker-mysandbox-v2",
			"scheduling_policy": "durable_object",
			"images": {
				"sandbox": {
					"dockerfile": "./Dockerfile",
				},
			},
		},
	],
}
The new entry makes these changes:
scheduling_policy: "durable_object" lets each Durable Object start its own container. This policy does not accept 
image, 
instance_type, or 
max_instances, so remove them. The 
Dockerfile moves to 
images, and the instance type moves to 
start().
The container application gets a new 
name. Without one, the new application takes the name that Wrangler generated for the old application, and the deploy fails after the new Worker version is already live.
Leave 
durable_objects and your 
migrations or 
exports as they are. The class keeps its name, so it needs no class migration.
Also remove 
SANDBOX_TRANSPORT, 
SANDBOX_INSTANCE_TIMEOUT_MS, 
SANDBOX_PORT_TIMEOUT_MS, and 
SANDBOX_POLL_INTERVAL_MS from 
vars, and keep 
nodejs_compat, which 1.0 requires.
Check your compatibility date.
:::note
this.ctx.exports is 
undefined before compatibility date 
2025-11-17, unless you add the 
enable_ctx_exports compatibility flag. The migration pages for outbound rules and bucket mounts use it. Several 0.12 templates set 
2025-05-06.
:::
Generate types for the new configuration:
Write the class. In this example, the 0.12 subclass sets a lifetime and environment variables, and overrides 
onStart():
import { getSandbox, Sandbox } from "@cloudflare/sandbox";
export class MySandbox extends Sandbox<Env> {
	sleepAfter = "30m";
	envVars = { NODE_ENV: "test" };
	override async onStart() {
		await this.ctx.storage.put("startedAt", Date.now());
	}
}
In 1.0, the class extends 
DurableObject and starts the container itself:
import { DurableObject } from "cloudflare:workers";
// Replaces sleepAfter and envVars.
const INACTIVITY_TIMEOUT_MS = 30 * 60 * 1000;
const ENV = { NODE_ENV: "test" };
export class MySandbox extends DurableObject<Env> {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		const container = ctx.container;
		// A restarted Durable Object sets the timeout again.
		if (container?.running) {
			void ctx.blockConcurrencyWhile(() =>
				container.setInactivityTimeout(
					INACTIVITY_TIMEOUT_MS,
				),
			);
		}
	}
	private get container(): Container {
		const container = this.ctx.container;
		if (!container) {
			throw new Error("No container is configured");
		}
		return container;
	}
	private setup: Promise<void> | null = null;
	private ensureRunning(): Promise<void> {
		// Set up each new container, and a running container
		// after this Durable Object restarts.
		if (this.setup === null || !this.container.running) {
			this.setup = this.startContainer().catch((error) => {
				this.setup = null;
				throw error;
			});
		}
		return this.setup;
	}
	private async startContainer(): Promise<void> {
		const newContainer = !this.container.running;
		if (newContainer) {
			this.container.start({
				image: this.container.images.sandbox,
				instance: "standard-1",
				env: ENV,
				// 0.12 allowed Internet access by default.
				enableInternet: true,
			});
		}
		try {
			if (newContainer) {
				// Replaces onStart().
				await this.ctx.storage.put("startedAt", Date.now());
			}
			await this.container.setInactivityTimeout(
				INACTIVITY_TIMEOUT_MS,
			);
		} catch (error) {
			// The next request starts a new container.
			await this.container.destroy();
			throw error;
		}
	}
}
Call 
ensureRunning() before each use of the container. It runs 
startContainer() once for each new container, and once more when a restarted Durable Object finds the container running. A deploy restarts the Durable Object and can stop setup partway, so every step after 
start() must be safe to run again. 
running is 
true as soon as 
start() returns, so requests that arrive during setup wait for the same 
startContainer() call. If a setup step throws, 
startContainer() stops the container, so no request runs commands in a container that is not set up.
start() returns before the container is ready, and the first 
exec() waits for it. The inactivity timeout does not survive a Durable Object restart. The constructor sets it again when a restarted Durable Object finds the container running. The timeout accepts at most 6 hours. If your commands do not need the Internet, set 
enableInternet to 
false.
Replace each class field and 
getSandbox() option that your code sets:
0.12
1.0
sleepAfter
setInactivityTimeout() after 
start(), and again in the constructor.
keepAlive
An alarm that runs more often than the inactivity timeout while work remains.
envVars, 
setEnvVars()
env on 
start() for the main process, and 
env on each 
exec() call. Commands do not inherit the 
start() variables, except 
PATH.
entrypoint
entrypoint on 
start(), or 
CMD in the image.
enableInternet
enableInternet on 
start(), which every call must pass. 0.12 defaulted to 
true.
labels, 
setLabels()
labels on 
start().
defaultPort, 
requiredPorts
this.container.getTcpPort(port). Refer to Move preview URLs.
allowedHosts, 
deniedHosts, 
outboundByHost, 
outbound, 
interceptHttps
Refer to Move outbound rules.
normalizeId
Lowercase the name before 
getByName().
containerTimeouts
An 
AbortSignal on the calls that need a deadline. Refer to Replace timeouts.
enableDefaultSession
Nothing. Each 
exec() call is its own process. Refer to Replace sessions.
transport, 
pingEndpoint
Nothing. Remove them.
Replace the hooks your subclass overrides:
onStart(): run the code in 
startContainer(), inside 
if (newContainer), as in the class from the previous step.
onStop() and 
onError(): watch the container with 
monitor(), and catch errors where you call 
start() and 
exec().
onActivityExpired(): no code runs before the inactivity timeout stops the container. To run code first, keep your own idle deadline in an alarm, and call 
this.container.destroy() when it passes. For an example that saves the sandbox before it stops, refer to Save a sandbox automatically.
To watch the container, call a method like this one in the 
try block of 
startContainer(). A restarted Durable Object runs 
startContainer() again, so it watches the running container too:
export class MySandbox extends DurableObject<Env> {
	// ...
	private watch(): void {
		this.container.monitor().then(
			() => console.log("Exited with code 0"),
			(error: unknown) => console.error("Stopped", error),
		);
	}
}
monitor() resolves when the main process exits with code 
0 or 
destroy() stops the container without a reason. It rejects when the process fails or 
destroy() passes a reason. The call ends when the Durable Object leaves memory, so it misses a stop that happens before the next request. While the call keeps the Durable Object in memory, the inactivity timeout does not start, and the container keeps running past the timeout. For more information, refer to Sandbox lifetime. For a record of every stop, refer to Run code when a sandbox stops.
Move the calls your Worker makes into methods on the class. In 0.12, the Worker calls package methods on the stub that 
getSandbox() returns:
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const id = new URL(request.url).pathname.slice(1);
		const sandbox = getSandbox(env.MY_SANDBOX, id, {
			normalizeId: true,
		});
		const result = await sandbox.exec("npm test", {
			cwd: "/workspace/app",
		});
		return Response.json({
			exitCode: result.exitCode,
			output: result.stdout,
		});
	},
};
In 1.0, the stub has only the methods your class defines. Add a method to 
MySandbox, and call it from the Worker:
export class MySandbox extends DurableObject<Env> {
	// ...
	async test(): Promise<{ exitCode: number; output: string }> {
		await this.ensureRunning();
		const process = await this.container.exec(["npm", "test"], {
			cwd: "/workspace/app",
			env: ENV,
		});
		const result = await process.output();
		return {
			exitCode: result.exitCode,
			output: new TextDecoder().decode(result.stdout),
		};
	}
}
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const id = new URL(request.url).pathname.slice(1);
		// Replaces normalizeId: true.
		const sandbox = env.MY_SANDBOX.getByName(id.toLowerCase());
		return Response.json(await sandbox.test());
	},
} satisfies ExportedHandler<Env>;
Move the methods that your 0.12 subclass defines into the 1.0 class. Your Worker calls them on the stub as it did in 0.12. Inside those methods, replace 
this.exec() and other package calls with calls on 
this.container. For each kind of call, refer to Change command calls and the feature pages in Migrate from Sandbox SDK 0.x.
Check the class
Start your Worker locally:
Wrangler builds the image when it starts. Send a request to each route that uses a sandbox. The first request for each name starts a container and waits for it. Each route returns what it returned on 0.12.
Next steps
To deploy the new class, follow Plan the move to Sandbox SDK 1.0.
To change 
exec() and sessions, refer to Change command calls.
To change file calls, refer to Change file calls.
For the methods on 
this.ctx.container, refer to the Container API.

Move browser terminals
import { Steps } from "~/components";
In Sandbox SDK 0.12, 
terminal() attaches a WebSocket to a shell that the container keeps for each session, and 
SandboxAddon reconnects the browser to it. In 1.0, your Durable Object attaches each WebSocket to a tmux session with 
exec(argv, { pty }). tmux keeps the shell running between connections.
Before you start
Your 1.0 class replaces the 0.12 
Sandbox class, and has the 
container getter, the 
ensureRunning() method, and the 
ENV constant from Replace the Sandbox class.
This page replaces 
terminal(), 
session.terminal(), 
proxyTerminal(), and 
SandboxAddon from 
@cloudflare/sandbox/xterm. It does not cover sessions for commands. For those, refer to Replace sessions.
Attach terminals to tmux
Add tmux to your 
Dockerfile:
RUN apt-get update \
	&& apt-get install -y --no-install-recommends \
		ca-certificates git python3 tmux \
	&& rm -rf /var/lib/apt/lists/*
# Scroll back with the mouse wheel, and keep more history.
RUN printf 'set -g mouse on\nset -g history-limit 50000\n' \
	> /etc/tmux.conf
Add the 
fetch() handler from Open a terminal in the browser to your class. Replace its 
container constant, 
start() call, and 
setInactivityTimeout() call with 
ensureRunning(), and start the shell with the directory and variables that 0.12 used:
await this.ensureRunning();
const abort = new AbortController();
const tmux = await this.container.exec(
	["tmux", "new-session", "-A", "-s", session],
	{
		pty: {
			cols: Number(url.searchParams.get("cols")) || 80,
			rows: Number(url.searchParams.get("rows")) || 24,
		},
		env: { ...ENV, TERM: "xterm-256color" },
		cwd: "/workspace",
		signal: abort.signal,
	},
);
0.12 started each shell in 
/workspace, with the variables from 
envVars and from the 
ENV lines of the image. 
exec() inherits only 
PATH from either, so add any other image variables that your shells need to 
ENV.
Send the message that 0.12 clients wait for, right after 
accept():
server.binaryType = "arraybuffer";
server.accept();
// 0.12 clients wait for this message before they send their size.
server.send(JSON.stringify({ type: "ready" }));
SandboxAddon and other clients written for the 0.12 messages stay in the 
connecting state until 
{"type":"ready"} arrives. Then they send the window size. The handler already reads 
cols and 
rows from the 0.12 resize message, which also carries 
"type": "resize". With this message, a page loaded before the switch keeps working when it reconnects.
If 
createSession() gave a session its own working directory and variables, pass them to tmux when a page opens that session:
// The working directory and variables of each 0.12 session
// that browsers open by name.
type SessionOptions = { cwd: string; env: Record<string, string> };
const SESSIONS: Record<string, SessionOptions> = {
	build: { cwd: "/workspace/app", env: { CI: "1" } },
};
In the handler, build the tmux command from the session name, and pass 
argv to 
exec() in place of the array:
const argv = ["tmux", "new-session", "-A", "-s", session];
const options = SESSIONS[session];
if (options) {
	argv.push("-c", options.cwd);
	for (const [name, value] of Object.entries(options.env)) {
		argv.push("-e", `${name}=${value}`);
	}
}
tmux applies 
-c and 
-e when it creates the session. A request without 
?session= opens the session 
main, which replaces the 0.12 default session.
The handler accepts session names of lowercase letters, digits, and hyphens, and tmux does not accept 
. or 
:. Rename 0.12 sessions that use other characters.
To run another command instead of 
bash, as the 0.12 
shell option did, refer to Run another command in the terminal.
If your class forwards preview URLs from Move preview URLs, it already has a 
fetch() handler. Rename that handler to 
forwardToPort(), rename the terminal handler to 
openTerminal(), make both 
private, and add a 
fetch() handler that chooses one:
export class MySandbox extends DurableObject<Env> {
	// ...
	async fetch(request: Request): Promise<Response> {
		// Only the preview route of the Worker sets this header.
		if (request.headers.has("X-Sandbox-Port")) {
			return this.forwardToPort(request);
		}
		return this.openTerminal(request);
	}
}
Forward the WebSocket
In 0.12, the Worker passes the WebSocket request to 
terminal():
const sandbox = getSandbox(env.MY_SANDBOX, id);
const sessionId = url.searchParams.get("session");
if (sessionId) {
	const session = await sandbox.getSession(sessionId);
	return session.terminal(request);
}
return sandbox.terminal(request, { cols: 80, rows: 24 });
In 1.0, the Worker forwards the request to the Durable Object, and the 
session query parameter goes with it:
return env.MY_SANDBOX.getByName(id).fetch(request);
Pass the name that 0.12 used. 0.12 kept the case of the name unless you passed 
normalizeId: true. In that case, call 
id.toLowerCase(), as Replace the Sandbox class shows.
Replace 
proxyTerminal(stub, sessionId, request) with the same 
fetch() call, and put the session in the 
session query parameter. The handler reads the size from the 
cols and 
rows query parameters, and uses 80 by 24 without them. A request without a WebSocket upgrade gets HTTP 
426, where 0.12 threw an error.
If your class also forwards preview URLs, remove the 
X-Sandbox-Port header before you forward the request. Otherwise a visitor who sends the header reaches a port without a preview token:
const headers = new Headers(request.headers);
headers.delete("X-Sandbox-Port");
const sandbox = env.MY_SANDBOX.getByName(id);
return sandbox.fetch(new Request(request, { headers }));
Replace SandboxAddon
1.0 has no 
@cloudflare/sandbox/xterm module. In 0.12, the page loads 
SandboxAddon into xterm.js:
import { SandboxAddon } from "@cloudflare/sandbox/xterm";
const addon = new SandboxAddon({
	getWebSocketUrl: ({ sandboxId, sessionId, origin }) => {
		const params = new URLSearchParams({ id: sandboxId });
		if (sessionId) params.set("session", sessionId);
		return `${origin}/ws/terminal?${params}`;
	},
	onStateChange: (state) => console.log(state),
});
terminal.loadAddon(addon);
addon.connect({ sandboxId: "my-sandbox", sessionId: "build" });
In 1.0, the page opens the WebSocket itself, and reconnects when it closes:
const encoder = new TextEncoder();
let socket: WebSocket;
let attempts = 0;
const send = (data: string | Uint8Array) => {
	if (socket.readyState === WebSocket.OPEN) socket.send(data);
};
const connect = () => {
	const url = new URL("/ws/terminal", location.href);
	url.protocol = location.protocol === "https:" ? "wss:" : "ws:";
	url.searchParams.set("id", "my-sandbox");
	url.searchParams.set("session", "build");
	url.searchParams.set("cols", String(terminal.cols));
	url.searchParams.set("rows", String(terminal.rows));
	socket = new WebSocket(url);
	socket.binaryType = "arraybuffer";
	socket.addEventListener("open", () => {
		attempts = 0;
		// tmux redraws the whole screen when a client attaches.
		terminal.reset();
	});
	socket.addEventListener("message", (event) => {
		// Skip the ready message.
		if (typeof event.data === "string") return;
		terminal.write(new Uint8Array(event.data));
	});
	socket.addEventListener("close", (event) => {
		// Code 1000 means the shell exited or the person detached.
		if (event.code === 1000 || attempts >= 10) return;
		const delay = Math.min(1000 * 2 ** attempts++, 30_000);
		setTimeout(connect, delay);
	});
};
connect();
terminal.onData((data) => send(encoder.encode(data)));
terminal.onResize(({ cols, rows }) => {
	send(JSON.stringify({ cols, rows }));
});
The states of the addon map to socket events. 
connecting lasts until the 
open event, and 
connected starts with it. 
disconnected follows a 
close event that the page does not retry.
Like the addon, the page retries after 1 second, doubles the delay, and stops after 10 attempts. An HTTP error in place of the upgrade arrives as a 
close event with code 
1006.
What changes at the terminal
A reconnected page shows the screen that tmux redraws, where 0.12 replayed up to 256 KiB of earlier output. Earlier output stays in the tmux history, so people scroll back with the mouse wheel and press 
q to leave the history.
When the shell exits, the socket closes with code 
1000, and the reason carries the exit code, such as 
Terminal closed with code 0. The next connection starts a new shell. 0.12 kept the ended terminal, so later connections showed its old output and ran nothing until the container restarted.
Detaching with 
CTRL + B then 
D also closes the socket with code 
1000, and the session keeps running.
Browsers that open the same session share one screen, as they did in 0.12.
Terminals open at the switch
The switch ends the 0.12 shells and their output. Open terminals stop receiving data without a close event, so 
SandboxAddon does not reconnect. Ask people to reload the page after the deploy, or add the read timeout from Plan the move. After a reload, the Durable Object creates a new tmux session.
Check the terminal
After you deploy the switch, open a terminal for a sandbox and make the window 100 columns by 30 rows. In the browser developer tools, the first message on the WebSocket is 
{"type":"ready"}. Run this command in the terminal:
echo pwd=$(pwd) NODE_ENV=$NODE_ENV; stty size
The shell starts in 
/workspace with the variables from 
ENV, and tmux takes one row for its status line:
pwd=/workspace NODE_ENV=test
29 100
Start a loop that prints a line every second, and reload the page. The count has kept going. Run 
exit. The WebSocket closes with code 
1000 and the reason 
Terminal closed with code 0, and the page does not reconnect.
Related resources
Open a terminal in the browser
Replace the Sandbox class
Plan the move
xterm.js documentation

Move tunnels
import { Steps } from "~/components";
In Sandbox SDK 0.12, 
tunnels.get() runs 
cloudflared in the container and returns a public URL. A quick tunnel gets a random 
trycloudflare.com URL, and a named tunnel gets a hostname in your account, such as 
ada.example.com. In 1.0, your Durable Object starts 
cloudflared with 
exec(). Named tunnels that 0.12 created stay in your account, and keep their hostnames once 
cloudflared runs again.
Your Worker already routes requests to the container, so most tunnels can become preview URLs instead. For those, refer to Move preview URLs.
Before you start
Your 1.0 class replaces the 0.12 
Sandbox class, and has the 
container getter and the 
ensureRunning() and 
startContainer() methods from Replace the Sandbox class. 
src/index.ts has the scripts and functions from step 1 of Run a server in the background, which start 
cloudflared and stop it.
startContainer() must start the container with 
enableInternet: true, because 
cloudflared connects out to Cloudflare. Code in the sandbox can then reach the Internet too. For what that allows, refer to Sandbox security.
This page replaces 
tunnels.get(), 
tunnels.list(), and 
tunnels.destroy(). Remove the 
SANDBOX_TRANSPORT variable, which 0.12 tunnels required.
Run cloudflared from your Durable Object
Copy 
cloudflared into your image. Add this line to your 
Dockerfile, after the 
FROM line:
COPY --from=docker.io/cloudflare/cloudflared:2026.10.2 \
	/usr/local/bin/cloudflared /usr/local/bin/cloudflared
0.12.14 also runs version 2026.10.2. 
cloudflared needs the 
ca-certificates package, which the 
Dockerfile from Replace the Sandbox class installs.
Add the scripts that check tunnels to the top level of 
src/index.ts:
const TUNNEL_ROOT = "/var/lib/tunnels";
const QUICK_URL = "https://[a-z0-9-]+\\.trycloudflare\\.com";
// Prints "connected" and any quick tunnel URL while cloudflared runs
// and serves requests.
const TUNNEL_STATUS = `${CURRENT}
dir=$1
current "$dir" && kill -0 "$pid" 2>/dev/null || exit 0
if grep -q 'Registered tunnel connection' "$dir/log"
then
	echo connected $(grep -o -m1 -E '${QUICK_URL}' "$dir/log")
fi`;
// Prints the port and URL of each connected quick tunnel.
const LIST = `status=$1
for dir in ${TUNNEL_ROOT}/*/; do
	[ -d "$dir" ] || continue
	set -- $(sh -c "$status" sh "$dir")
	[ "$1" = connected ] && [ -n "$2" ] &&
		echo "$(basename "$dir") $2"
done`;
async function capture(
	container: Container,
	argv: string[],
): Promise<string> {
	const process = await container.exec(argv);
	const output = await process.output();
	return new TextDecoder().decode(output.stdout).trim();
}
Each tunnel runs as a server in a directory named after its port. 
cloudflared logs 
Registered tunnel connection once the tunnel serves requests.
Add a method that starts 
cloudflared and waits for it to connect, and a method that opens a quick tunnel, to your Durable Object class:
export class MySandbox extends DurableObject<Env> {
	// ...
	private async startTunnel(
		port: number,
		args: string[],
		env: Record<string, string> = {},
	): Promise<string> {
		const dir = `${TUNNEL_ROOT}/${port}`;
		const argv = ["cloudflared", "tunnel", "--no-autoupdate", ...args];
		await stopServer(this.container, dir);
		await startServer(this.container, dir, argv, { env });
		const deadline = Date.now() + 30_000;
		while (Date.now() < deadline) {
			const status = await capture(this.container, [
				"sh",
				"-c",
				TUNNEL_STATUS,
				"sh",
				dir,
			]);
			if (status.startsWith("connected")) {
				return status.slice("connected".length).trim();
			}
			const log = await serverExited(this.container, dir);
			if (log !== undefined) {
				throw new Error(`cloudflared exited: ${log}`);
			}
			await scheduler.wait(500);
		}
		await stopServer(this.container, dir);
		throw new Error("The tunnel did not connect within 30 seconds");
	}
	async openTunnel(port: number): Promise<string> {
		await this.ensureRunning();
		const url = `http://localhost:${port}`;
		return this.startTunnel(port, ["--url", url]);
	}
}
openTunnel() replaces 
tunnels.get(port), and returns the 
trycloudflare.com URL. The URL can take several seconds to resolve after the method returns. A quick tunnel ends with its container, as in 0.12.
Each call stops any 
cloudflared that already serves the port, and returns a new URL. 0.12 returned the tunnel that already served the port. To keep a URL, look it up with 
listTunnels() from the next step before you call 
openTunnel().
Add methods that list and close quick tunnels:
export class MySandbox extends DurableObject<Env> {
	// ...
	async listTunnels(): Promise<{ port: number; url: string }[]> {
		if (!this.container.running) {
			return [];
		}
		const output = await capture(this.container, [
			"sh",
			"-c",
			LIST,
			"sh",
			TUNNEL_STATUS,
		]);
		return output
			.split("\n")
			.filter((line) => line !== "")
			.map((line) => {
				const [port, url] = line.split(" ");
				return { port: Number(port), url };
			});
	}
	async closeTunnel(port: number): Promise<void> {
		if (!this.container.running) {
			return;
		}
		await stopServer(this.container, `${TUNNEL_ROOT}/${port}`);
	}
}
listTunnels() replaces 
tunnels.list() for quick tunnels, and 
closeTunnel() replaces 
tunnels.destroy(). After 
closeTunnel(), the URL returns 
530.
Keep named tunnels that 0.12 created
0.12 recorded each named tunnel in Durable Object storage, under the 
tunnels and 
tunnels:meta keys. The keys hold the tunnel ID, its hostname, your account and zone, and its DNS record. They stay when you deploy the switch in place, so 1.0 can run the same tunnel again. If you move sandboxes side by side, 
copyFrom0x() copies the keys into the 1.0 class.
Keep the 
CLOUDFLARE_API_TOKEN secret that 0.12 used, with the Cloudflare Tunnel Edit and DNS Edit permissions. The code uses it to fetch the run token of each tunnel, and to delete tunnels and DNS records. For 
wrangler types to add the secret to 
Env, also set it in 
.dev.vars.
The code reads the account and zone that 0.12 stored, and does not need 
CLOUDFLARE_ACCOUNT_ID, 
CLOUDFLARE_TUNNEL_ACCOUNT_ID, or 
CLOUDFLARE_ZONE_ID.
Add the types and a function that calls the Cloudflare API to the top level of 
src/index.ts:
type Tunnels = Record<string, { id: string; hostname: string }>;
type TunnelsMeta = Record<
	string,
	{ accountId?: string; zoneId?: string; dnsRecordId?: string }
>;
type ApiBody<T> = { result: T; errors: unknown[] };
async function cloudflare<T>(
	env: Env,
	path: string,
	init: RequestInit = {},
): Promise<T> {
	const url = `https://api.cloudflare.com/client/v4${path}`;
	const response = await fetch(url, {
		...init,
		headers: {
			Authorization: `Bearer ${env.CLOUDFLARE_API_TOKEN}`,
		},
	});
	const body = await response.json<ApiBody<T>>();
	if (!response.ok) {
		const errors = JSON.stringify(body.errors);
		throw new Error(`Cloudflare API: ${errors}`);
	}
	return body.result;
}
Add methods that run and delete a named tunnel to your Durable Object class:
export class MySandbox extends DurableObject<Env> {
	// ...
	private async namedTunnel(port: number) {
		const { storage } = this.ctx;
		const tunnels = await storage.get<Tunnels>("tunnels");
		const meta = await storage.get<TunnelsMeta>("tunnels:meta");
		const tunnel = tunnels?.[port];
		return tunnel && { ...tunnel, ...meta?.[port] };
	}
	async resumeTunnel(port: number): Promise<string | undefined> {
		const tunnel = await this.namedTunnel(port);
		if (!tunnel?.accountId) {
			return undefined;
		}
		const { accountId, id } = tunnel;
		const token = await cloudflare<string>(
			this.env,
			`/accounts/${accountId}/cfd_tunnel/${id}/token`,
		);
		await this.ensureRunning();
		// TUNNEL_TOKEN keeps the token out of the process list.
		await this.startTunnel(
			port,
			["run", "--url", `http://localhost:${port}`],
			{ TUNNEL_TOKEN: token },
		);
		return `https://${tunnel.hostname}`;
	}
	async deleteTunnel(port: number): Promise<void> {
		const tunnel = await this.namedTunnel(port);
		if (!tunnel?.accountId) {
			return;
		}
		const { accountId, id, zoneId, dnsRecordId } = tunnel;
		await this.closeTunnel(port);
		await cloudflare(
			this.env,
			`/accounts/${accountId}/cfd_tunnel/${id}`,
			{ method: "DELETE" },
		);
		if (zoneId && dnsRecordId) {
			await cloudflare(
				this.env,
				`/zones/${zoneId}/dns_records/${dnsRecordId}`,
				{ method: "DELETE" },
			);
		}
		await this.ctx.storage.transaction(async (txn) => {
			const tunnels = (await txn.get<Tunnels>("tunnels")) ?? {};
			const meta =
				(await txn.get<TunnelsMeta>("tunnels:meta")) ?? {};
			delete tunnels[port];
			delete meta[port];
			await txn.put({ tunnels, "tunnels:meta": meta });
		});
	}
}
Both methods skip a port whose stored tunnel is a quick tunnel, because 0.12 stored the account only for named tunnels. For that port, 
resumeTunnel() returns 
undefined.
Call 
resumeTunnel() after each 
start(), for each port that your application serves through a named tunnel. 0.12 started a named tunnel again only on the next 
tunnels.get() for its port. Until 
cloudflared runs, the hostname returns error 1033.
deleteTunnel() replaces 
tunnels.destroy() for a named tunnel. It deletes the tunnel, its DNS record, and its storage entries. 0.12 
destroy() did this for every tunnel of a sandbox, so call 
deleteTunnel() for each stored port when you end a sandbox.
:::caution
Code in the sandbox can read the run token from the environment of the 
cloudflared process, as it could in 0.12. Anyone with the token can run the tunnel and serve its hostname. Keep one tunnel for each sandbox, as 0.12 did.
:::
Find tunnels that 0.12 left behind
After an in-place switch, no 0.12 
destroy() runs, so tunnels and DNS records for sandboxes that no longer exist stay in your account. 0.12 names each tunnel 
sandbox-<DURABLE_OBJECT_ID>-<NAME>, and tags it with 
createdBy: "sandbox-sdk" metadata. List those tunnels:
API=https://api.cloudflare.com/client/v4
curl --get "$API/accounts/$ACCOUNT_ID/cfd_tunnel" \
	--data is_deleted=false --data per_page=100 \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" |
	jq -r '.result[]
		| select(.metadata.createdBy == "sandbox-sdk")
		| "\(.id) \(.name) \(.status)"'
0.12 gives each DNS record the comment 
sandbox-<DURABLE_OBJECT_ID>. List those records:
curl --get "$API/zones/$ZONE_ID/dns_records" \
	--data comment.startswith=sandbox- \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" |
	jq -r '.result[] | "\(.id) \(.name) \(.comment)"'
A tunnel with the status 
down has no running 
cloudflared. For each sandbox that you no longer keep, delete its tunnel and its DNS record.
If you moved sandboxes side by side, the tunnels that 
copyFrom0x() moved keep the ID of the 0.12 Durable Object in their names and comments, and still serve the 1.0 class. Decide by hostname which tunnels to delete, not by Durable Object ID.
Serve new named hostnames
To give new sandboxes their own hostnames, serve the hostnames from your Worker, as Serve previews on their own hostnames describes. These hostnames have the same 
<NAME>.<ZONE> shape as the hostnames of 0.12 named tunnels. The sandbox runs no 
cloudflared and holds no token. To keep creating tunnels, create each with the Cloudflare Tunnel API and add a DNS record for it, as 0.12 did.
Check the tunnels
With a server listening on port 
8080, call 
openTunnel(8080), and request the URL it returns. The response comes from your server.
After you deploy the switch, request the hostname of a named tunnel that 0.12 created:
curl https://ada.example.com/ --write-out "%{http_code}\n"
error code: 1033
530
Call 
resumeTunnel(8080), and send the request again. The response comes from your server. After 
deleteTunnel(8080), the tunnel and its DNS record no longer appear in the lists from the previous section.
Related resources
Move preview URLs
Quick tunnels
Cloudflare Tunnel
Run a server in the background

Platform
import { Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
Information about the Sandbox SDK platform, including pricing and limits.
Available resources
Pricing - Understand costs based on the Containers platform
Limits - Resource limits and best practices
Since Sandbox SDK is built on Containers, it shares the same underlying platform characteristics. Refer to these pages to understand how pricing and limits work for your sandbox deployments.

Limits
import { WranglerConfig, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
Since the Sandbox SDK is built on top of the Containers platform, it shares the same underlying platform characteristics. Refer to these pages to understand how pricing and limits work for your sandbox deployments.
Sandbox also inherits current Containers lifecycle, placement, and routing behavior. For more
detail, refer to Lifecycle of a Container and
Scaling and Routing.
Container limits
Refer to Containers limits for complete details on:
Memory, vCPU, and disk limits for concurrent container instances
Instance types and their resource allocations
Image size and storage limits
Workers and Durable Objects limits
When using the Sandbox SDK from Workers or Durable Objects, you are subject to Workers subrequest limits. By default, the SDK uses HTTP transport where each operation (
exec(), 
readFile(), 
writeFile(), etc.) counts as one subrequest.
Subrequest limits
Workers Free: 50 subrequests per request
Workers Paid: 1,000 subrequests per request
Avoid subrequest limits with RPC transport
Enable RPC transport to multiplex all SDK calls over a single persistent connection:
```jsonc
{
	"vars": {
		"SANDBOX_TRANSPORT": "rpc"
	},
}
```
With RPC transport enabled:
The persistent connection counts as one subrequest
All subsequent SDK operations use the existing connection (no additional subrequests)
Ideal for workflows with many SDK operations per request
See Transport modes for a complete guide.
Best practices
To work within these limits:
Right-size your instances - Choose the appropriate instance type based on your workload requirements
Clean up unused sandboxes - Terminate sandbox sessions when they are no longer needed to free up resources
Optimize images - Keep your custom Dockerfiles lean to reduce image size
Use RPC transport for high-frequency operations - Enable 
SANDBOX_TRANSPORT=rpc to avoid subrequest limits when making many SDK calls per request

Pricing
import { Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />
Sandbox SDK pricing is determined by the underlying Containers platform it's built on.
Containers Pricing
Refer to Containers pricing for complete details on:
vCPU, memory, and disk usage rates
Network egress pricing
Instance types and their costs
Related Pricing
When using Sandbox, you'll also be billed for:
Workers - Handles incoming requests to your sandbox
Durable Objects - Powers each sandbox instance
Workers Logs - Optional observability (if enabled)

Build an AI code executor
import { Render, PackageManagers } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/get-started/build-an-ai-code-interpreter/", title: "Build an AI code interpreter" }} />
Build an AI-powered code execution system using Sandbox SDK and Claude. Turn natural language questions into Python code, execute it securely, and return results.
Time to complete: 20 minutes
What you'll build
An API that accepts questions like "What's the 100th Fibonacci number?", uses Claude to generate Python code, executes it in an isolated sandbox, and returns the results.
Prerequisites
You'll also need:
An Anthropic API key for Claude
Docker running locally
1. Create your project
Create a new Sandbox SDK project:
<PackageManagers
type="create"
pkg="cloudflare@latest"
args={"ai-code-executor --template=cloudflare/sandbox-sdk/examples/minimal#v0"}
/>
cd ai-code-executor
2. Install dependencies
Install the Anthropic SDK:
3. Build your code executor
Replace the contents of 
src/index.ts:
import { getSandbox, type Sandbox } from '@cloudflare/sandbox';
import Anthropic from '@anthropic-ai/sdk';
export { Sandbox } from '@cloudflare/sandbox';
interface Env {
	Sandbox: DurableObjectNamespace<Sandbox>;
	ANTHROPIC_API_KEY: string;
}
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		if (request.method !== 'POST' || new URL(request.url).pathname !== '/execute') {
			return new Response('POST /execute with { "question": "your question" }');
		}
		try {
			const { question } = await request.json();
			if (!question) {
				return Response.json({ error: 'Question is required' }, { status: 400 });
			}
			// Use Claude to generate Python code
			const anthropic = new Anthropic({ apiKey: env.ANTHROPIC_API_KEY });
			const codeGeneration = await anthropic.messages.create({
				model: 'claude-sonnet-4-5',
				max_tokens: 1024,
				messages: [{
					role: 'user',
					content: `Generate Python code to answer: "${question}"
Requirements:
- Use only Python standard library
- Print the result using print()
- Keep code simple and safe
Return ONLY the code, no explanations.`
				}],
			});
			const generatedCode = codeGeneration.content[0]?.type === 'text'
				? codeGeneration.content[0].text
				: '';
			if (!generatedCode) {
				return Response.json({ error: 'Failed to generate code' }, { status: 500 });
			}
			// Strip markdown code fences if present
			const cleanCode = generatedCode
				.replace(/^```python?\n?/, '')
				.replace(/\n?```\s*$/, '')
				.trim();
			// Execute the code in a sandbox
			const sandbox = getSandbox(env.Sandbox, 'demo-user');
			await sandbox.writeFile('/tmp/code.py', cleanCode);
			const result = await sandbox.exec('python /tmp/code.py');
			return Response.json({
				success: result.success,
				question,
				code: generatedCode,
				output: result.stdout,
				error: result.stderr
			});
		} catch (error: any) {
			return Response.json(
				{ error: 'Internal server error', message: error.message },
				{ status: 500 }
			);
		}
	},
};
How it works:
Receives a question via POST to 
/execute
Uses Claude to generate Python code
Writes code to 
/tmp/code.py in the sandbox
Executes with 
sandbox.exec('python /tmp/code.py')
Returns both the code and execution results
4. Set up local environment variables
Create a 
.dev.vars file in your project root for local development:
echo "ANTHROPIC_API_KEY=your_api_key_here" > .dev.vars
Replace 
your_api_key_here with your actual API key from the Anthropic Console.
:::note
The 
.dev.vars file is automatically gitignored and only used during local development with 
npm run dev.
:::
5. Test locally
Start the development server:
npm run dev
:::note
First run builds the Docker container (2-3 minutes). Subsequent runs are much faster.
:::
Test with curl:
curl -X POST http://localhost:8787/execute \
  -H "Content-Type: application/json" \
  -d '{"question": "What is the 10th Fibonacci number?"}'
Response:
{
  "success": true,
  "question": "What is the 10th Fibonacci number?",
  "code": "def fibonacci(n):\n    if n <= 1:\n        return n\n    return fibonacci(n-1) + fibonacci(n-2)\n\nprint(fibonacci(10))",
  "output": "55\n",
  "error": ""
}
6. Deploy
Deploy your Worker:
npx wrangler deploy
Then set your Anthropic API key as a production secret:
npx wrangler secret put ANTHROPIC_API_KEY
Paste your API key from the Anthropic Console when prompted.
:::caution
After first deployment, wait 2-3 minutes for container provisioning. Check status with 
npx wrangler containers list.
:::
7. Test your deployment
Try different questions:
# Factorial
curl -X POST https://ai-code-executor.YOUR_SUBDOMAIN.workers.dev/execute \
  -H "Content-Type: application/json" \
  -d '{"question": "Calculate the factorial of 5"}'
# Statistics
curl -X POST https://ai-code-executor.YOUR_SUBDOMAIN.workers.dev/execute \
  -H "Content-Type: application/json" \
  -d '{"question": "What is the mean of [10, 20, 30, 40, 50]?"}'
# String manipulation
curl -X POST https://ai-code-executor.YOUR_SUBDOMAIN.workers.dev/execute \
  -H "Content-Type: application/json" \
  -d '{"question": "Reverse the string \"Hello World\""}'
What you built
You created an AI code execution system that:
Accepts natural language questions
Generates Python code with Claude
Executes code securely in isolated sandboxes
Returns results with error handling
Next steps
Code interpreter with Workers AI - Use Cloudflare's native AI models with official packages
Analyze data with AI - Add pandas and matplotlib for data analysis
Code Interpreter API - Use the built-in code interpreter instead of exec
Streaming output - Show real-time execution progress
API reference - Explore all available methods
Related resources
Anthropic Claude documentation
Workers AI - Use Cloudflare's built-in models
AI SDK provider - Call Workers AI and AI Gateway models from the AI SDK

Analyze data with AI
import { Render, PackageManagers } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/get-started/build-an-ai-code-interpreter/", title: "Build an AI code interpreter" }} />
Build an AI-powered data analysis system that accepts CSV uploads, uses Claude to generate Python analysis code, executes it in sandboxes, and returns visualizations.
Time to complete: 25 minutes
Prerequisites
You'll also need:
An Anthropic API key for Claude
Docker running locally
1. Create your project
Create a new Sandbox SDK project:
<PackageManagers
type="create"
pkg="cloudflare@latest"
args={"analyze-data --template=cloudflare/sandbox-sdk/examples/minimal#v0"}
/>
cd analyze-data
2. Install dependencies
3. Build the analysis handler
Replace 
src/index.ts:
import { getSandbox, proxyToSandbox, type Sandbox } from "@cloudflare/sandbox";
import Anthropic from "@anthropic-ai/sdk";
export { Sandbox } from "@cloudflare/sandbox";
interface Env {
	Sandbox: DurableObjectNamespace<Sandbox>;
	ANTHROPIC_API_KEY: string;
}
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const proxyResponse = await proxyToSandbox(request, env);
		if (proxyResponse) return proxyResponse;
		if (request.method !== "POST") {
			return Response.json(
				{ error: "POST CSV file and question" },
				{ status: 405 },
			);
		}
		try {
			const formData = await request.formData();
			const csvFile = formData.get("file") as File;
			const question = formData.get("question") as string;
			if (!csvFile || !question) {
				return Response.json(
					{ error: "Missing file or question" },
					{ status: 400 },
				);
			}
			// Upload CSV to sandbox
			const sandbox = getSandbox(env.Sandbox, `analysis-${Date.now()}`);
			const csvPath = "/workspace/data.csv";
			await sandbox.writeFile(csvPath, await csvFile.text());
			// Analyze CSV structure
			const structure = await sandbox.exec(
				`python3 -c "import pandas as pd; df = pd.read_csv('${csvPath}'); print(f'Rows: {len(df)}'); print(f'Columns: {list(df.columns)[:5]}')"`,
			);
			if (!structure.success) {
				return Response.json(
					{ error: "Failed to read CSV", details: structure.stderr },
					{ status: 400 },
				);
			}
			// Generate analysis code with Claude
			const code = await generateAnalysisCode(
				env.ANTHROPIC_API_KEY,
				csvPath,
				question,
				structure.stdout,
			);
			// Write and execute the analysis code
			await sandbox.writeFile("/workspace/analyze.py", code);
			const result = await sandbox.exec("python /workspace/analyze.py");
			if (!result.success) {
				return Response.json(
					{ error: "Analysis failed", details: result.stderr },
					{ status: 500 },
				);
			}
			async function streamToBase64(stream) {
			  const blob = await new Response(stream).blob();
			  const buffer = await blob.arrayBuffer();
			  const bytes = new Uint8Array(buffer);
			  // Convert to base64
			  let binary = '';
			  for (let i = 0; i < bytes.length; i++) {
			    binary += String.fromCharCode(bytes[i]);
			  }
			  return btoa(binary);
			}
			// Check for generated chart
			let chart = null;
			try {
				const { content, mimeType } = await sandbox.readFile("/workspace/chart.png", {
					encoding: "none"
				});
				chart = `data:${mimeType};base64,${await streamToBase64(content)}`;
			} catch {
				// No chart generated
			}
			await sandbox.destroy();
			return Response.json({
				success: true,
				output: result.stdout,
				chart,
				code,
			});
		} catch (error: any) {
			return Response.json({ error: error.message }, { status: 500 });
		}
	},
};
async function generateAnalysisCode(
	apiKey: string,
	csvPath: string,
	question: string,
	csvStructure: string,
): Promise<string> {
	const anthropic = new Anthropic({ apiKey });
	const response = await anthropic.messages.create({
		model: "claude-sonnet-4-5",
		max_tokens: 2048,
		messages: [
			{
				role: "user",
				content: `CSV at ${csvPath}:
${csvStructure}
Question: "${question}"
Generate Python code that:
- Reads CSV with pandas
- Answers the question
- Saves charts to /workspace/chart.png if helpful
- Prints findings to stdout
Use pandas, numpy, matplotlib.`,
			},
		],
		tools: [
			{
				name: "generate_python_code",
				description: "Generate Python code for data analysis",
				input_schema: {
					type: "object",
					properties: {
						code: { type: "string", description: "Complete Python code" },
					},
					required: ["code"],
				},
			},
		],
	});
	for (const block of response.content) {
		if (block.type === "tool_use" && block.name === "generate_python_code") {
			return (block.input as { code: string }).code;
		}
	}
	throw new Error("Failed to generate code");
}
4. Set up local environment variables
Create a 
.dev.vars file in your project root for local development:
echo "ANTHROPIC_API_KEY=your_api_key_here\nSANDBOX_TRANSPORT=rpc" > .dev.vars
Replace 
your_api_key_here with your actual API key from the Anthropic Console.
The 
SANDBOX_TRANSPORT is required to use the new file streaming APIs.
:::note
The 
.dev.vars file is automatically gitignored and only used during local development with 
npm run dev.
:::
5. Test locally
Download a sample CSV:
# Create a test CSV
echo "year,rating,title
2020,8.5,Movie A
2021,7.2,Movie B
2022,9.1,Movie C" > test.csv
Start the dev server:
npm run dev
Test with curl:
curl -X POST http://localhost:8787 \
  -F "file=@test.csv" \
  -F "question=What is the average rating by year?"
Response:
{
	"success": true,
	"output": "Average ratings by year:\n2020: 8.5\n2021: 7.2\n2022: 9.1",
	"chart": "data:image/png;base64,...",
	"code": "import pandas as pd\nimport matplotlib.pyplot as plt\n..."
}
6. Deploy
Deploy your Worker:
npx wrangler deploy
Then set your Anthropic API key as a production secret:
npx wrangler secret put ANTHROPIC_API_KEY
Paste your API key from the Anthropic Console when prompted.
:::caution
Wait 2-3 minutes after first deployment for container provisioning.
:::
What you built
An AI data analysis system that:
Uploads CSV files to sandboxes
Uses Claude's tool calling to generate analysis code
Executes Python with pandas and matplotlib
Returns text output and visualizations
Next steps
Code Interpreter API - Use the built-in code interpreter
File operations - Advanced file handling
Streaming output - Real-time progress updates

Automated testing pipeline
import { Render, PackageManagers } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/commands/run-tests-from-a-git-repository/", title: "Run tests from a Git repository" }} />
Build a testing pipeline that clones Git repositories, installs dependencies, runs tests, and reports results.
Time to complete: 25 minutes
Prerequisites
You'll also need a GitHub repository with tests (public or private with access token).
1. Create your project
<PackageManagers
type="create"
pkg="cloudflare@latest"
args={"test-pipeline --template=cloudflare/sandbox-sdk/examples/minimal#v0"}
/>
cd test-pipeline
2. Build the pipeline
Replace 
src/index.ts:
import { getSandbox, proxyToSandbox, parseSSEStream, type Sandbox, type ExecEvent } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';
interface Env {
	Sandbox: DurableObjectNamespace<Sandbox>;
	GITHUB_TOKEN?: string;
}
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const proxyResponse = await proxyToSandbox(request, env);
		if (proxyResponse) return proxyResponse;
		if (request.method !== 'POST') {
			return new Response('POST { "repoUrl": "https://github.com/owner/repo", "branch": "main" }');
		}
		try {
			const { repoUrl, branch } = await request.json();
			if (!repoUrl) {
				return Response.json({ error: 'repoUrl required' }, { status: 400 });
			}
			const sandbox = getSandbox(env.Sandbox, `test-${Date.now()}`);
			try {
				// Clone repository
				console.log('Cloning repository...');
				let cloneUrl = repoUrl;
				
				if (env.GITHUB_TOKEN && cloneUrl.includes('github.com')) {
					cloneUrl = cloneUrl.replace('https://', `https://${env.GITHUB_TOKEN}@`);
				}
				await sandbox.gitCheckout(cloneUrl, {
					...(branch && { branch }),
					depth: 1,
					targetDir: 'repo'
				});
				console.log('Repository cloned');
				// Detect project type
				const projectType = await detectProjectType(sandbox);
				console.log(`Detected ${projectType} project`);
				// Install dependencies
				const installCmd = getInstallCommand(projectType);
				if (installCmd) {
					console.log('Installing dependencies...');
					const installStream = await sandbox.execStream(`cd /workspace/repo && ${installCmd}`);
					
					let installExitCode = 0;
					for await (const event of parseSSEStream<ExecEvent>(installStream)) {
						if (event.type === 'stdout' || event.type === 'stderr') {
							console.log(event.data);
						} else if (event.type === 'complete') {
							installExitCode = event.exitCode;
						}
					}
					
					if (installExitCode !== 0) {
						return Response.json({
							success: false,
							error: 'Install failed',
							exitCode: installExitCode
						});
					}
					console.log('Dependencies installed');
				}
				// Run tests
				console.log('Running tests...');
				const testCmd = getTestCommand(projectType);
				const testStream = await sandbox.execStream(`cd /workspace/repo && ${testCmd}`);
				
				let testExitCode = 0;
				for await (const event of parseSSEStream<ExecEvent>(testStream)) {
					if (event.type === 'stdout' || event.type === 'stderr') {
						console.log(event.data);
					} else if (event.type === 'complete') {
						testExitCode = event.exitCode;
					}
				}
				console.log(`Tests completed with exit code ${testExitCode}`);
				return Response.json({
					success: testExitCode === 0,
					exitCode: testExitCode,
					projectType,
					message: testExitCode === 0 ? 'All tests passed' : 'Tests failed'
				});
			} finally {
				await sandbox.destroy();
			}
		} catch (error: any) {
			return Response.json({ error: error.message }, { status: 500 });
		}
	},
};
async function detectProjectType(sandbox: any): Promise<string> {
	try {
		await sandbox.readFile('/workspace/repo/package.json');
		return 'nodejs';
	} catch {}
	try {
		await sandbox.readFile('/workspace/repo/requirements.txt');
		return 'python';
	} catch {}
	try {
		await sandbox.readFile('/workspace/repo/go.mod');
		return 'go';
	} catch {}
	return 'unknown';
}
function getInstallCommand(projectType: string): string {
	switch (projectType) {
		case 'nodejs': return 'npm install';
		case 'python': return 'pip install -r requirements.txt || pip install -e .';
		case 'go': return 'go mod download';
		default: return '';
	}
}
function getTestCommand(projectType: string): string {
	switch (projectType) {
		case 'nodejs': return 'npm test';
		case 'python': return 'python -m pytest || python -m unittest discover';
		case 'go': return 'go test ./...';
		default: return 'echo "Unknown project type"';
	}
}
3. Test locally
Start the dev server:
npm run dev
Test with a repository:
curl -X POST http://localhost:8787 \
  -H "Content-Type: application/json" \
  -d '{
    "repoUrl": "https://github.com/cloudflare/sandbox-sdk"
  }'
You will see progress logs in the wrangler console, and receive a JSON response:
{
  "success": true,
  "exitCode": 0,
  "projectType": "nodejs",
  "message": "All tests passed"
}
4. Deploy
npx wrangler deploy
For private repositories, set your GitHub token:
npx wrangler secret put GITHUB_TOKEN
What you built
An automated testing pipeline that:
Clones Git repositories
Detects project type (Node.js, Python, Go)
Installs dependencies automatically
Runs tests and reports results
Next steps
Streaming output - Add real-time test output
Background processes - Handle long-running tests
Sessions API - Cache dependencies between runs

Build a code review bot
import { Render, PackageManagers } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/coding-agents/", title: "Run coding agents in a sandbox" }} />
Build a GitHub bot that responds to pull requests, clones the repository in a sandbox, uses Claude to analyze code changes, and posts review comments.
Time to complete: 30 minutes
Prerequisites
You'll also need:
A GitHub account and fine-grained personal access token with the following permissions:
Repository access: Select the specific repository you want to test with
Permissions > Repository permissions:
Metadata: Read-only (required)
Contents: Read-only (required to clone the repository)
Pull requests: Read and write (required to post review comments)
An Anthropic API key for Claude
A GitHub repository for testing
1. Create your project
<PackageManagers
type="create"
pkg="cloudflare@latest"
args={"code-review-bot --template=cloudflare/sandbox-sdk/examples/minimal#v0"}
/>
cd code-review-bot
2. Install dependencies
3. Build the webhook handler
Replace 
src/index.ts:
import { getSandbox, proxyToSandbox, type Sandbox } from "@cloudflare/sandbox";
import { Octokit } from "@octokit/rest";
import Anthropic from "@anthropic-ai/sdk";
export { Sandbox } from "@cloudflare/sandbox";
interface Env {
	Sandbox: DurableObjectNamespace<Sandbox>;
	GITHUB_TOKEN: string;
	ANTHROPIC_API_KEY: string;
	WEBHOOK_SECRET: string;
}
export default {
	async fetch(
		request: Request,
		env: Env,
		ctx: ExecutionContext,
	): Promise<Response> {
		const proxyResponse = await proxyToSandbox(request, env);
		if (proxyResponse) return proxyResponse;
		const url = new URL(request.url);
		if (url.pathname === "/webhook" && request.method === "POST") {
			const signature = request.headers.get("x-hub-signature-256");
			const contentType = request.headers.get("content-type") || "";
			const body = await request.text();
			// Verify webhook signature
			if (
				!signature ||
				!(await verifySignature(body, signature, env.WEBHOOK_SECRET))
			) {
				return Response.json({ error: "Invalid signature" }, { status: 401 });
			}
			const event = request.headers.get("x-github-event");
			// Parse payload (GitHub can send as JSON or form-encoded)
			let payload;
			if (contentType.includes("application/json")) {
				payload = JSON.parse(body);
			} else {
				// Handle form-encoded payload
				const params = new URLSearchParams(body);
				payload = JSON.parse(params.get("payload") || "{}");
			}
			// Handle opened and reopened PRs
			if (
				event === "pull_request" &&
				(payload.action === "opened" || payload.action === "reopened")
			) {
				console.log(`Starting review for PR #${payload.pull_request.number}`);
				// Use waitUntil to ensure the review completes even after response is sent
				ctx.waitUntil(
					reviewPullRequest(payload, env).catch(console.error),
				);
				return Response.json({ message: "Review started" });
			}
			return Response.json({ message: "Event ignored" });
		}
		return new Response(
			"Code Review Bot\n\nConfigure GitHub webhook to POST /webhook",
		);
	},
};
async function verifySignature(
	payload: string,
	signature: string,
	secret: string,
): Promise<boolean> {
	const encoder = new TextEncoder();
	const key = await crypto.subtle.importKey(
		"raw",
		encoder.encode(secret),
		{ name: "HMAC", hash: "SHA-256" },
		false,
		["sign"],
	);
	const signatureBytes = await crypto.subtle.sign(
		"HMAC",
		key,
		encoder.encode(payload),
	);
	const expected =
		"sha256=" +
		Array.from(new Uint8Array(signatureBytes))
			.map((b) => b.toString(16).padStart(2, "0"))
			.join("");
	return signature === expected;
}
async function reviewPullRequest(payload: any, env: Env): Promise<void> {
	const pr = payload.pull_request;
	const repo = payload.repository;
	const octokit = new Octokit({ auth: env.GITHUB_TOKEN });
	const sandbox = getSandbox(env.Sandbox, `review-${pr.number}`);
	try {
		// Post initial comment
		console.log("Posting initial comment...");
		await octokit.issues.createComment({
			owner: repo.owner.login,
			repo: repo.name,
			issue_number: pr.number,
			body: "Code review in progress...",
		});
		// Clone repository
		console.log("Cloning repository...");
		const cloneUrl = `https://${env.GITHUB_TOKEN}@github.com/${repo.owner.login}/${repo.name}.git`;
		await sandbox.exec(
			`git clone --depth=1 --branch=${pr.head.ref} ${cloneUrl} /workspace/repo`,
		);
		// Get changed files
		console.log("Fetching changed files...");
		const comparison = await octokit.repos.compareCommits({
			owner: repo.owner.login,
			repo: repo.name,
			base: pr.base.sha,
			head: pr.head.sha,
		});
		const files = [];
		for (const file of (comparison.data.files || []).slice(0, 5)) {
			if (file.status !== "removed") {
				const content = await sandbox.readFile(
					`/workspace/repo/${file.filename}`,
				);
				files.push({
					path: file.filename,
					patch: file.patch || "",
					content: content.content,
				});
			}
		}
		// Generate review with Claude
		console.log(`Analyzing ${files.length} files with Claude...`);
		const anthropic = new Anthropic({ apiKey: env.ANTHROPIC_API_KEY });
		const response = await anthropic.messages.create({
			model: "claude-sonnet-4-5",
			max_tokens: 2048,
			messages: [
				{
					role: "user",
					content: `Review this PR:
Title: ${pr.title}
Changed files:
${files.map((f) => `File: ${f.path}\nDiff:\n${f.patch}\n\nContent:\n${f.content.substring(0, 1000)}`).join("\n\n")}
Provide a brief code review focusing on bugs, security, and best practices.`,
				},
			],
		});
		const review =
			response.content[0]?.type === "text"
				? response.content[0].text
				: "No review generated";
		// Post review comment
		console.log("Posting review...");
		await octokit.issues.createComment({
			owner: repo.owner.login,
			repo: repo.name,
			issue_number: pr.number,
			body: `## Code Review\n\n${review}\n\n---\n*Generated by Claude*`,
		});
		console.log("Review complete!");
	} catch (error: any) {
		console.error("Review failed:", error);
		await octokit.issues.createComment({
			owner: repo.owner.login,
			repo: repo.name,
			issue_number: pr.number,
			body: `Review failed: ${error.message}`,
		});
	} finally {
		await sandbox.destroy();
	}
}
4. Set up local environment variables
Create a 
.dev.vars file in your project root for local development:
cat > .dev.vars << EOF
GITHUB_TOKEN=your_github_token_here
ANTHROPIC_API_KEY=your_anthropic_key_here
WEBHOOK_SECRET=your_webhook_secret_here
EOF
Replace the placeholder values with:
GITHUB_TOKEN: Your GitHub personal access token with repo permissions
ANTHROPIC_API_KEY: Your API key from the Anthropic Console
WEBHOOK_SECRET: A random string (for example: 
openssl rand -hex 32)
:::note
The 
.dev.vars file is automatically gitignored and only used during local development with 
npm run dev.
:::
5. Expose local server with Cloudflare Tunnel
To test with real GitHub webhooks locally, use Cloudflare Tunnel to expose your local development server.
Start the development server:
npm run dev
In a separate terminal, create a tunnel to your local server:
cloudflared tunnel --url http://localhost:8787
This will output a public URL (for example, 
https://example.trycloudflare.com). Copy this URL for the next step.
:::note
If you do not have 
cloudflared installed, refer to Downloads.
:::
6. Configure GitHub webhook for local testing
:::note[Important]
Configure this webhook on a specific GitHub repository where you will create test pull requests. The bot will only review PRs in repositories where the webhook is configured.
:::
Navigate to your test repository on GitHub
Go to Settings > Webhooks > Add webhook
Set Payload URL: Your Cloudflare Tunnel URL from Step 5 with 
/webhook appended (for example, 
https://example.trycloudflare.com/webhook)
Set Content type: 
application/json
Set Secret: Same value you used for 
WEBHOOK_SECRET in your 
.dev.vars file
Select Let me select individual events → Check Pull requests
Click Add webhook
7. Test locally with a pull request
Create a test PR:
git checkout -b test-review
echo "console.log('test');" > test.js
git add test.js
git commit -m "Add test file"
git push origin test-review
Open the PR on GitHub. The bot should post a review comment within a few seconds.
8. Deploy to production
Deploy your Worker:
npx wrangler deploy
Then set your production secrets:
# GitHub token (needs repo permissions)
npx wrangler secret put GITHUB_TOKEN
# Anthropic API key
npx wrangler secret put ANTHROPIC_API_KEY
# Webhook secret (use the same value from .dev.vars)
npx wrangler secret put WEBHOOK_SECRET
9. Update webhook for production
Go to your repository Settings > Webhooks
Click on your existing webhook
Update Payload URL to your deployed Worker URL: 
https://code-review-bot.YOUR_SUBDOMAIN.workers.dev/webhook
Click Update webhook
Your bot is now running in production and will review all new pull requests automatically.
What you built
A GitHub code review bot that:
Receives webhook events from GitHub
Clones repositories in isolated sandboxes
Uses Claude to analyze code changes
Posts review comments automatically
Next steps
Git operations - Advanced repository handling
Sessions API - Manage long-running sandbox operations
GitHub Apps - Build a proper GitHub App

Tutorials
import { ResourcesBySelector, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/get-started/", title: "Get started" }} />
Learn how to build applications with Sandbox SDK through step-by-step tutorials. Each tutorial takes 20-30 minutes.
<ResourcesBySelector directory="sandbox/sdk/tutorials/" types={["tutorial"]} />
Before you start
All tutorials assume you have:
Completed the Get Started guide
Basic familiarity with Workers
Docker installed and running
Related resources
How-to guides - Solve specific problems
API reference - Complete SDK reference

Build an AI coding agent with OpenAI Agents SDK
import { Details, Render } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/coding-agents/", title: "Run coding agents in a sandbox" }} />
The OpenAI Agents SDK is a lightweight Python framework for building multi-agent workflows. A Cloudflare Sandbox integration is provided out of the box and ensures that the SDK includes a first-class Cloudflare backend that gives your agents isolated containers for running code, installing packages, and managing files.
In this tutorial, you will deploy a sandbox bridge Worker and build a Python agent that accepts a coding task, executes it inside a Cloudflare Sandbox, and copies the output files to your local machine.
Time to complete: 20 minutes
Prerequisites
Sign up for a Cloudflare account with the Containers / Sandbox beta enabled.
Install Python 3.12+ and uv.
Obtain an OpenAI API key.
1. Deploy the sandbox bridge
The sandbox bridge is a Cloudflare Worker that exposes the Sandbox API over HTTP so non-Worker clients — such as a Python script using the OpenAI Agents SDK — can create and control sandboxes.
The Sandbox environment comes pre-configured for Node.js and Python development, so your agents can start writing and running code immediately.
Deploy the bridge to your Cloudflare account:
The button deploys the Worker and generates a 
SANDBOX_API_KEY secret for authentication. When deployment finishes, note your Worker URL and API key — you will need them in the next step.
If you prefer to deploy step by step:
Install Node.js and Docker.
Scaffold the bridge project:
npm create cloudflare sandbox-bridge --template=cloudflare/sandbox-sdk/bridge/worker#v0
cd sandbox-bridge
Authenticate with Cloudflare:
npx wrangler login
Set the API key secret:
openssl rand -hex 32 | tee /dev/stderr | npx wrangler secret put SANDBOX_API_KEY
The key is printed to your terminal and piped to Wrangler. Save it — you will need it to authenticate API requests.
Deploy the Worker:
npx wrangler deploy
Verify the deployment:
curl https://cloudflare-sandbox-bridge.<your-subdomain>.workers.dev/health
You should see 
{"ok":true}.
2. Set up your Python project
Create a new directory for the agent:
mkdir openai-sandbox-agent && cd openai-sandbox-agent
Create a 
.env file with your credentials:
OPENAI_API_KEY=sk-your-openai-key
CLOUDFLARE_SANDBOX_API_KEY=your-bridge-token
CLOUDFLARE_SANDBOX_WORKER_URL=https://cloudflare-sandbox-bridge.your-subdomain.workers.dev
3. Build the agent
Create 
main.py with the following content. The inline script metadata tells 
uv which dependencies to install, so everything is contained in a single file:
# /// script
# requires-python = ">=3.12"
# dependencies = ["openai-agents[cloudflare]"]
# ///
"""One-shot coding agent backed by a Cloudflare Sandbox."""
from __future__ import annotations
import asyncio
import os
import sys
from pathlib import Path
from agents import Runner
from agents.extensions.sandbox.cloudflare import (
    CloudflareSandboxClient,
    CloudflareSandboxClientOptions,
)
from agents.run import RunConfig
from agents.sandbox import SandboxAgent, SandboxRunConfig
from agents.sandbox.capabilities import Shell
MODEL = "gpt-5.4"
INSTRUCTIONS = """\
You are an expert developer working inside a sandbox.
The sandbox has bun, node, npm, and python available on the PATH.
Implement the user's task in /workspace, test it, then copy deliverable files to /workspace/output/.
""".strip()
async def copy_output(session, dest: Path) -> list[Path]:
    """Download files from /workspace/output/ in the sandbox to a local directory."""
    dest.mkdir(parents=True, exist_ok=True)
    ls = await session.exec("find", "/workspace/output", "-maxdepth", "1", "-type", "f", shell=False)
    if not ls.ok():
        return []
    copied: list[Path] = []
    for name in (l.strip() for l in ls.stdout.decode().splitlines() if l.strip()):
        handle = await session.read(Path(name))
        local = dest / Path(name).name
        payload = handle.read(); handle.close()
        local.write_bytes(payload if isinstance(payload, bytes) else payload.encode())
        copied.append(local)
    return copied
async def run(prompt: str, output_dir: Path) -> None:
    worker_url = os.environ.get("CLOUDFLARE_SANDBOX_WORKER_URL", "")
    if not worker_url:
        sys.exit("Error: CLOUDFLARE_SANDBOX_WORKER_URL is not set.")
    agent = SandboxAgent(
        name="Developer",
        model=MODEL,
        instructions=INSTRUCTIONS,
        capabilities=[Shell()],
    )
    client = CloudflareSandboxClient()
    options = CloudflareSandboxClientOptions(worker_url=worker_url)
    session = await client.create(manifest=agent.default_manifest, options=options)
    try:
        async with session:
            run_config = RunConfig(
                sandbox=SandboxRunConfig(session=session),
                tracing_disabled=True,
            )
            # Stream tool calls so the user can follow progress.
            result = Runner.run_streamed(agent, prompt, run_config=run_config)
            async for ev in result.stream_events():
                if ev.type == "run_item_stream_event" and ev.name == "tool_called":
                    print(f"  [tool] {getattr(ev.item.raw_item, 'name', '')}")
                elif ev.type == "run_item_stream_event" and ev.name == "tool_output":
                    print(f"  [output] {str(getattr(ev.item, 'output', ''))[:200]}")
            # Copy output files from the sandbox to the local machine.
            copied = await copy_output(session, output_dir)
            if copied:
                print(f"\nCopied {len(copied)} file(s) to {output_dir}:")
                for p in copied:
                    print(f"   {p}")
            else:
                print("\nAgent did not produce any output files.")
    finally:
        await client.delete(session)
if __name__ == "__main__":
    prompt = sys.argv[1] if len(sys.argv) > 1 else "Create a hello world HTTP server using Bun.serve"
    asyncio.run(run(prompt, Path("output")))
Here is what the key pieces do:
Component
Purpose
SandboxAgent
An 
Agent subclass that accepts sandbox-specific configuration, including 
capabilities.
Shell()
A capability that exposes a shell tool to the LLM, allowing it to run commands inside the sandbox.
CloudflareSandboxClient
Creates and manages sandbox sessions through the bridge Worker. Reads 
CLOUDFLARE_SANDBOX_API_KEY from the environment for authentication.
CloudflareSandboxClientOptions
Points the client at your bridge Worker URL.
Runner.run_streamed()
Executes the agent and yields streaming events for tool calls and text output.
SandboxRunConfig
Attaches a live sandbox session to the run so the agent's tools execute inside the container.
4. Run the agent
uv run --env-file .env main.py "Create a hello world HTTP server using Bun.serve"
You should see tool calls and output streaming to the console:
Sending task to sandbox agent (gpt-5.4)...
  [tool] exec_command
  [output] exit_code=0 stdout: mkdir: created directory '/workspace/output'
  [tool] exec_command
  [output] exit_code=0 stdout: Listening on http://localhost:3000
Copied 1 file(s) to output:
   output/server.ts
The agent wrote the code, tested it inside the sandbox, and copied the deliverable to your local machine.
What you built
You built a Python coding agent that:
Accepts a natural-language coding task
Executes code in an isolated Cloudflare Sandbox container
Installs packages, runs tests, and iterates until the task is complete
Copies deliverable files back to your local machine
The bridge Worker's 
Dockerfile can be fully customized to suit your needs — install additional languages, system packages, or tools to match your use case.
The Cloudflare Sandbox provides more capabilities you can integrate into your agents:
PTY sessions — Open interactive terminal sessions to sandboxes via WebSocket for real-time I/O.
Bucket mounts — Mount R2 or S3-compatible buckets as local directories inside the sandbox for persistent data.
Workspace backup and restore — Persist workspace state with 
persist_workspace() and 
hydrate_workspace() to resume work across sandbox lifecycles.
File operations — Read, write, and manage files programmatically within the sandbox.
Next steps
Workspace chat example — A full-stack chat application with a file browser sidebar, built with the OpenAI Agents SDK and Cloudflare Sandbox.
OpenAI Agents SDK documentation — Learn about multi-agent handoffs, guardrails, tracing, and more.
Sandbox bridge — Overview of the bridge Worker, usage examples, and configuration.
HTTP API reference — Complete route reference for the bridge API.
Sandbox tutorials — More tutorials covering code execution, data analysis, and CI/CD pipelines.

Data persistence with R2
import { Render, PackageManagers, TypeScriptExample } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/files/mount-an-r2-bucket/", title: "Mount an R2 bucket" }} />
Mount object storage buckets as local filesystem paths to persist data across sandbox lifecycles. This tutorial uses Cloudflare R2, but the same approach works with any S3-compatible provider.
This tutorial shows how to persist an external data directory mounted at 
/data. If you want the working project in 
/workspace to persist, refer to Backup and restore.
Time to complete: 20 minutes
What you'll build
A Worker that processes data, stores results in an R2 bucket mounted as a local directory, and demonstrates that data persists even after the sandbox is destroyed and recreated.
Key concepts you'll learn:
Mounting R2 buckets as filesystem paths
Automatic data persistence across sandbox lifecycles
Working with mounted storage using standard file operations
Prerequisites
You'll also need:
Docker running locally
An R2 bucket (create one in the Cloudflare dashboard)
1. Create your project
<PackageManagers
type="create"
pkg="cloudflare@latest"
args={"data-pipeline --template=cloudflare/sandbox-sdk/examples/minimal#v0"}
/>
cd data-pipeline
2. Configure R2 binding
Add an R2 bucket binding to your 
wrangler.json:
{
  "name": "data-pipeline",
  "compatibility_date": "2025-11-09",
  "durable_objects": {
    "bindings": [
      { "name": "Sandbox", "class_name": "Sandbox" }
    ]
  },
  "r2_buckets": [
    {
      "binding": "DATA_BUCKET",
      "bucket_name": "my-data-bucket"
    }
  ]
}
Replace 
my-data-bucket with your R2 bucket name. Create the bucket first in the Cloudflare dashboard.
3. Build the data processor
Replace 
src/index.ts with code that mounts R2 and processes data:
```typescript
import { getSandbox, type Sandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';
interface Env {
Sandbox: DurableObjectNamespace;
DATA_BUCKET: R2Bucket;
}
export default {
async fetch(request: Request, env: Env): Promise {
const url = new URL(request.url);
const sandbox = getSandbox(env.Sandbox, 'data-processor');
	// Mount R2 bucket to /data directory
	await sandbox.mountBucket('my-data-bucket', '/data', {
		endpoint: 'https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com'
	});
	if (url.pathname === '/process') {
		// Process data and save to mounted R2
		const result = await sandbox.exec('python', {
			args: ['-c', `
import json
import os
from datetime import datetime
Read input (or create sample data)
data = [
{'id': 1, 'value': 42},
{'id': 2, 'value': 87},
{'id': 3, 'value': 15}
]
Process: calculate sum and average
total = sum(item['value'] for item in data)
avg = total / len(data)
Save results to mounted R2 (/data is the mounted bucket)
result = {
'timestamp': datetime.now().isoformat(),
'total': total,
'average': avg,
'processed_count': len(data)
}
os.makedirs('/data/results', exist_ok=True)
with open('/data/results/latest.json', 'w') as f:
json.dump(result, f, indent=2)
print(json.dumps(result))
`]
});
		return Response.json({
			message: 'Data processed and saved to R2',
			result: JSON.parse(result.stdout)
		});
	}
	if (url.pathname === '/results') {
		// Read results from mounted R2
		const result = await sandbox.exec('cat', {
			args: ['/data/results/latest.json']
		});
		if (!result.success) {
			return Response.json({ error: 'No results found yet' }, { status: 404 });
		}
		return Response.json({
			message: 'Results retrieved from R2',
			data: JSON.parse(result.stdout)
		});
	}
	if (url.pathname === '/destroy') {
		// Destroy sandbox to demonstrate persistence
		await sandbox.destroy();
		return Response.json({ message: 'Sandbox destroyed. Data persists in R2!' });
	}
	return new Response(`
Data Pipeline with Persistent Storage
Endpoints:
POST /process  - Process data and save to R2
GET /results   - Retrieve results from R2
POST /destroy  - Destroy sandbox (data survives!)
Try this flow:
POST /process  (processes and saves to R2)
POST /destroy  (destroys sandbox)
GET /results   (data still accessible from R2)
`, { headers: { 'Content-Type': 'text/plain' } });
}
};
</TypeScriptExample>
:::note[Replace YOUR_ACCOUNT_ID]
Replace `YOUR_ACCOUNT_ID` in the endpoint URL with your Cloudflare account ID. Find it in the [dashboard](https://dash.cloudflare.com/) under **R2** > **Overview**.
:::
## 4. Deploy to production
**Generate R2 API tokens:**
1. Go to **R2** > **Overview** in the [Cloudflare dashboard](https://dash.cloudflare.com/)
2. Select **Manage R2 API Tokens**
3. Create a token with **Object Read & Write** permissions
4. Copy the **Access Key ID** and **Secret Access Key**
**Set up credentials as Worker secrets:**
```sh
npx wrangler secret put AWS_ACCESS_KEY_ID
# Paste your R2 Access Key ID
npx wrangler secret put AWS_SECRET_ACCESS_KEY
# Paste your R2 Secret Access Key
Worker secrets are encrypted and only accessible to your deployed Worker. The SDK automatically detects these credentials when 
mountBucket() is called.
Deploy your Worker:
npx wrangler deploy
After deployment, wrangler outputs your Worker URL (e.g., 
https://data-pipeline.yourname.workers.dev).
5. Test the persistence flow
Now test against your deployed Worker. Replace 
YOUR_WORKER_URL with your actual Worker URL:
# 1. Process data (saves to R2)
curl -X POST https://YOUR_WORKER_URL/process
# Returns: { "message": "Data processed...", "result": { "total": 144, "average": 48, ... } }
# 2. Verify data is accessible
curl https://YOUR_WORKER_URL/results
# Returns the same results from R2
# 3. Destroy the sandbox
curl -X POST https://YOUR_WORKER_URL/destroy
# Returns: { "message": "Sandbox destroyed. Data persists in R2!" }
# 4. Access results again (from new sandbox)
curl https://YOUR_WORKER_URL/results
# Still works! Data persisted across sandbox lifecycle
The key insight: After destroying the sandbox, the next request creates a new sandbox instance, mounts the same R2 bucket, and finds the data still there.
What you learned
In this tutorial, you built a data pipeline that demonstrates filesystem persistence through R2 bucket mounting:
Mounting buckets: Use 
mountBucket() to make R2 accessible as a local directory
Standard file operations: Access mounted buckets using familiar filesystem commands (
cat, Python 
open(), etc.)
Automatic persistence: Data written to mounted directories survives sandbox destruction
Choose the right persistence model: Use bucket mounts for external storage directories such as 
/data, and consider backup and restore when you need a persistent workspace under 
/workspace
Credential management: Configure R2 access using environment variables or explicit credentials
Next steps
Mount buckets guide - Comprehensive mounting reference
Storage API - Complete API documentation
Environment variables - Credential configuration options
Related resources
R2 documentation - Learn about Cloudflare R2
Background processes guide - Long-running data processing
Sandboxes concept - Understanding sandbox lifecycle

Code interpreter with Workers AI
import { Render, PackageManagers, WranglerConfig } from "~/components";
<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/get-started/build-an-ai-code-interpreter/", title: "Build an AI code interpreter" }} />
Build a powerful code interpreter that gives the gpt-oss model on Workers AI the ability to execute Python code using the Cloudflare Sandbox SDK.
Time to complete: 15 minutes
What you'll build
A Cloudflare Worker that accepts natural language prompts, uses GPT-OSS to decide when Python code execution is needed, runs the code in isolated sandboxes, and returns results with AI-powered explanations.
Prerequisites
You'll also need:
Docker running locally
1. Create your project
Create a new Sandbox SDK project:
<PackageManagers
type="create"
pkg="cloudflare@latest"
args={
"workers-ai-interpreter --template=cloudflare/sandbox-sdk/examples/code-interpreter#v0"
}
/>
cd workers-ai-interpreter
2. Review the implementation
The template includes a complete implementation using the latest best practices. Let's examine the key components:
// src/index.ts
import { getSandbox } from "@cloudflare/sandbox";
import { generateText, stepCountIs, tool } from "ai";
import { createWorkersAI } from "workers-ai-provider";
import { z } from "zod";
const MODEL = "@cf/openai/gpt-oss-120b" as const;
async function handleAIRequest(input: string, env: Env): Promise<string> {
	const workersai = createWorkersAI({ binding: env.AI });
	const result = await generateText({
		model: workersai(MODEL),
		messages: [{ role: "user", content: input }],
		tools: {
			execute_python: tool({
				description: "Execute Python code and return the output",
				inputSchema: z.object({
					code: z.string().describe("The Python code to execute"),
				}),
				execute: async ({ code }) => {
					return executePythonCode(env, code);
				},
			}),
		},
		stopWhen: stepCountIs(5),
	});
	return result.text || "No response generated";
}
Key improvements over direct REST API calls:
Official packages: Uses 
workers-ai-provider instead of manual API calls
Vercel AI SDK: Leverages 
generateText() and 
tool() for clean function calling
No API keys: Uses native AI binding instead of environment variables
Type safety: Full TypeScript support with proper typing
3. Check your configuration
The template includes the proper Wrangler configuration:
```json
{
  "name": "sandbox-code-interpreter-example",
  "main": "src/index.ts",
  "upload_source_maps": true,
  "compatibility_date": "$today",
  "ai": {
    "binding": "AI"
  },
  "containers": [
    {
      "class_name": "Sandbox",
      "image": "./Dockerfile",
      "name": "sandbox",
      "max_instances": 1,
      "instance_type": "basic"
    }
  ],
  "durable_objects": {
    "bindings": [
      {
        "class_name": "Sandbox",
        "name": "Sandbox"
      }
    ]
  }
}
```
Configuration highlights:
AI binding: Enables direct access to Workers AI models
Container setup: Configures sandbox container with Dockerfile
Durable Objects: Provides persistent sandboxes with state management
4. Test locally
Start the development server:
npm run dev
:::note
First run builds the Docker container (2-3 minutes). Subsequent runs are much faster.
:::
Test with curl:
# Simple calculation
curl -X POST http://localhost:8787/run \
  -H "Content-Type: application/json" \
  -d '{"input": "Calculate 5 factorial using Python"}'
# Complex operations
curl -X POST http://localhost:8787/run \
  -H "Content-Type: application/json" \
  -d '{"input": "Use Python to find all prime numbers under 20"}'
# Data analysis
curl -X POST http://localhost:8787/run \
  -H "Content-Type: application/json" \
  -d '{"input": "Create a list of the first 10 squares and calculate their sum"}'
5. Deploy
Deploy your Worker:
npx wrangler deploy
:::caution
After first deployment, wait 2-3 minutes for container provisioning before making requests.
:::
6. Test your deployment
Try more complex queries:
# Data visualization preparation
curl -X POST https://workers-ai-interpreter.YOUR_SUBDOMAIN.workers.dev/run \
  -H "Content-Type: application/json" \
  -d '{"input": "Generate sample sales data for 12 months and calculate quarterly totals"}'
# Algorithm implementation
curl -X POST https://workers-ai-interpreter.YOUR_SUBDOMAIN.workers.dev/run \
  -H "Content-Type: application/json" \
  -d '{"input": "Implement a binary search function and test it with a sorted array"}'
# Mathematical computation
curl -X POST https://workers-ai-interpreter.YOUR_SUBDOMAIN.workers.dev/run \
  -H "Content-Type: application/json" \
  -d '{"input": "Calculate the standard deviation of [2, 4, 4, 4, 5, 5, 7, 9]"}'
How it works
User input: Send natural language prompts to the 
/run endpoint
AI decision: GPT-OSS receives the prompt with an 
execute_python tool available
Smart execution: Model decides whether Python code execution is needed
Sandbox isolation: Code runs in isolated Cloudflare Sandbox containers
AI explanation: Results are integrated back into the AI's response for final output
What you built
You deployed a sophisticated code interpreter that:
Native Workers AI integration: Uses the official 
workers-ai-provider package for seamless integration
Function calling: Leverages Vercel AI SDK for clean tool definitions and execution
Secure execution: Runs Python code in isolated sandbox containers
Intelligent responses: Combines AI reasoning with code execution results
Next steps
Analyze data with AI - Add pandas and matplotlib for advanced data analysis
Code Interpreter API - Use the built-in code interpreter with structured outputs
Streaming output - Show real-time execution progress
API reference - Explore all available sandbox methods
Related resources
Workers AI - Learn about Cloudflare's AI platform
workers-ai-provider package - Official Workers AI integration
Vercel AI SDK - Universal toolkit for AI applications
GPT-OSS model documentation - Model details and capabilities