Compute
Sandbox
Run the Cloudflare Sandbox SDK on OpenOrange with a sandbox provider you choose.
Runs on @cloudflare/sandbox on the ORANGE_SANDBOX_PROVIDER backend: a local host directory (default), an embedded agentOS VM through @rivet-dev/agentos-core, or E2B, Daytona, or Freestyle through @rivet-dev/sandbox-adapter
- Works
exec(), streamed output, files, background processes,gitCheckout(), and preview URLs, through the same@cloudflare/sandboxAPI- Differs
- Each sandbox runs on a provider you choose, not in a container, and your Dockerfile does not run. The default
localprovider is not isolated. - Missing
createSession(),createCodeContext(), andrunCode(), and preview URLs on E2B, Daytona, and Freestyle- Migration
- Not needed A sandbox starts fresh on its provider.
- Configure
containersdurable_objectsmigrations- Checks
- 1 pass
Your @cloudflare/sandbox Worker code runs unchanged. On Cloudflare each
sandbox runs in a Container. On OpenOrange it runs on a provider you choose:
E2B, Daytona, Freestyle, an embedded agentOS VM, or a local directory on the
host.
Quickstart
-
Add the Sandbox class
Use the Wrangler configuration from Cloudflare’s Sandbox guide, unchanged.
{ "name": "my-worker", "main": "src/index.ts", "compatibility_date": "2026-09-03", "containers": [ { "class_name": "Sandbox", "image": "./Dockerfile", "instance_type": "lite" } ], "durable_objects": { "bindings": [{ "class_name": "Sandbox", "name": "Sandbox" }] }, "migrations": [{ "new_sqlite_classes": ["Sandbox"], "tag": "v1" }] } -
Write the Worker
getSandbox()gives you one sandbox per name. You do not need to install@cloudflare/sandbox, because Orange supplies it.import { getSandbox, proxyToSandbox, type Sandbox } from "@cloudflare/sandbox"; export { Sandbox } from "@cloudflare/sandbox"; interface Env { Sandbox: DurableObjectNamespace<Sandbox>; } export default { async fetch(request, env): Promise<Response> { // Requests to a preview URL go to the exposed port in the sandbox. const preview = await proxyToSandbox(request, env); if (preview) return preview; // One sandbox per user: POST /users/<id>/run const user = new URL(request.url).pathname.split("/")[2] ?? "default"; const sandbox = getSandbox(env.Sandbox, user); const { command } = await request.json<{ command: string }>(); const { exitCode, stderr, stdout, success } = await sandbox.exec(command); return Response.json({ exitCode, stderr, stdout, success }); }, } satisfies ExportedHandler<Env>; -
Choose a provider
Set
ORANGE_SANDBOX_PROVIDERin.dev.vars. The default,local, runs commands on your machine, so choose another provider to run untrusted code.Provider ORANGE_SANDBOX_PROVIDERAlso set E2B e2bE2B_API_KEY, andpnpm add e2bDaytona daytonaDAYTONA_API_KEY, andpnpm add @daytonaio/sdkFreestyle freestyleFREESTYLE_API_KEY, andpnpm add freestyleagentOS agentosNothing Local directory local(default)ORANGE_SANDBOX_DIR(optional)# .dev.vars ORANGE_SANDBOX_PROVIDER=e2b E2B_API_KEY=<API key> -
Run it
orange devruns theSandboxclass as a Rivet Actor, and warns once that it does not run the container image.orange dev Binding Resource Runs on env.Sandbox Durable Object Rivet Actor · SandboxRun a command in Ada’s sandbox. A failing command is a result, not an error:
curl localhost:8787/users/ada/run -d '{"command":"echo hi; echo oops >&2"}' {"exitCode":0,"stderr":"oops\n","stdout":"hi\n","success":true} curl localhost:8787/users/ada/run -d '{"command":"exit 3"}' {"exitCode":3,"stderr":"","stdout":"","success":false}
For a fuller app, with streamed output, files, Git, and a preview URL, see
examples/sandbox.
How it works
- Each
SandboxDurable Object owns one provider sandbox. The first call creates it. - The object stores the sandbox’s id, so after an
orange devrestart it reconnects to the same sandbox. destroy()deletes the sandbox. The next call starts a new, empty one.
Containers
Runs on No container runtime. A class listed under containers gets a ctx.container that runs one sandbox per object on ORANGE_SANDBOX_PROVIDER
- Works
ctx.container.start(),exec(),monitor(),destroy(),signal(), andgetTcpPort().fetch(), withFilesfrom@cloudflare/sandbox1.x- Differs
- Images are not built or run.
start()takes only a Cloudflare Sandbox image, and runs one sandbox per object onORANGE_SANDBOX_PROVIDER. - Missing
- Other images,
start({ entrypoint }),exec()withptyorstdin, the outbound HTTP intercepts,snapshotContainer(), andinspect() - Migration
- Not needed A container starts fresh, with nothing kept from Cloudflare.
- Configure
containers- Checks
- 1 not run
A Durable Object class that containers lists gets a ctx.container, as on
Cloudflare, backed by a sandbox on the same provider. Code written for the
@cloudflare/sandbox 1.x API, with ctx.container.exec() and Files, runs
unchanged. See ctx.container for the details.
AI context Compatibility, limits and details
Written for LLMs and coding agents: every edge case, measurement, and known deviation. You do not need it to use the feature.
Compatibility
| Feature | Status | Notes |
|---|---|---|
getSandbox, Sandbox export | Supported | normalizeId: true lowercases the id, as on Cloudflare. |
exec | Supported | Options: cwd, env, timeout. A failing command returns its exitCode and does not throw. |
execStream, parseSSEStream | Supported | SSE events start, stdout, stderr, complete, error. |
startProcess, listProcesses, getProcess, killProcess, killAllProcesses | Supported | Returns Process objects with kill, getStatus, getLogs, waitForLog, waitForPort, and waitForExit. |
getProcessLogs, streamProcessLogs | Supported | |
writeFile, readFile | Supported | With encoding: "base64". |
mkdir, deleteFile, renameFile, moveFile, exists, listFiles | Supported | |
gitCheckout | Supported | Runs git clone in the sandbox. |
setEnvVars | Supported | |
exposePort, unexposePort, getExposedPorts, proxyToSandbox | Partial | Local and agentOS providers only. See Preview URLs. |
destroy | Supported | |
createSession | Not supported | Throws. Use exec() with cwd and env. |
createCodeContext, runCode | Not supported | Throws. Run code with exec(). |
ctx.container start(), exec(), monitor(), destroy(), signal() | Supported | In a class that containers lists, with a Cloudflare Sandbox image. See ctx.container. |
ctx.container.getTcpPort().fetch() | Partial | Local and agentOS providers only. |
start({ entrypoint }), exec({ pty }), exec({ stdin }) | Not supported | Throw. Start the command with exec(). |
interceptOutboundHttp(), interceptAllOutboundHttp(), interceptOutboundHttps(), snapshotContainer(), inspect() | Not supported | Throw. |
setInactivityTimeout() | Partial | Does nothing. The sandbox stays until destroy(). |
Files: readFile(), writeFile(), readDirectory(), mkdir(), rename(), remove() | Supported | Errors are SandboxFileErrors with code, operation, and path. |
Files.stat(), Files.lstat() | Partial | Local and agentOS providers only. |
S3Mount, DirectoryBackup, S3Gateway, DirectoryBackupGateway | Not supported | They load, so a Worker can export them, and throw when used. |
| Container images | Not supported | Not built or run. A sandbox has the provider’s tools. |
Limits
| What | Limit | What happens over it |
|---|---|---|
| Preview port | 1024 to 65535 | exposePort() throws Invalid port number: <port>. Must be 1024-65535. |
Custom preview token | 1 to 16 characters of a-z, 0-9, and _, unique per sandbox | exposePort() throws Cloudflare’s message, such as Custom token too long. Maximum 16 characters allowed. Received: <n> characters. |
| Sandbox id in a preview URL | Lowercase | exposePort() throws Preview URLs require lowercase sandbox IDs. Your ID "<id>" contains uppercase letters. |
| A background process | Lives as long as the orange dev process | It stops when orange dev stops. |
| An agentOS VM | Lives in the memory of the orange dev process | After a restart, the next call starts an empty VM. |
A ctx.container image | A Cloudflare Sandbox image, which names cloudflare/sandbox | start() throws. See ctx.container. |
Providers
| Provider | Isolation |
|---|---|
| E2B | E2B micro-VM |
| Daytona | Daytona sandbox |
| Freestyle | Freestyle VM |
| agentOS | agentOS VM in the orange dev process. See The agentOS provider. |
| Local directory | None. Commands run as host processes. See The local provider. |
- E2B, Daytona, and Freestyle come from
@rivet-dev/sandbox-adapter. They load only when selected. - Choosing a provider works like the S3 option for R2 and the provider for Workers AI.
The E2B, Daytona, and Freestyle providers
/workspaceis the working directory for commands, as on Cloudflare. Orange creates it when it connects to a sandbox. On Daytona, it usessudo.- Freestyle VMs can reach the Internet, as Cloudflare sandboxes can by default.
- Daytona returns a command’s output only when the command ends. While a
background process runs,
getProcessLogs(),streamProcessLogs(), andwaitForLog()see no output. - On Daytona,
killProcess()stops Orange’s wait for the process, but the command keeps running in the sandbox until it exits or the sandbox is destroyed. - Daytona runs commands with
zsh.
The agentOS provider
The agentOS provider runs each sandbox in a VM from
@rivet-dev/agentos-core,
embedded in the orange dev process. It needs no account or API key.
- Each sandbox id gets one VM. The first call boots it, which takes about 1 to 3 seconds.
/workspaceis a directory inside the VM and is the working directory for commands. Absolute paths in commands are VM paths.- Commands run in the VM’s shell with its tools, such as
shandnode. Host environment variables are not passed. - VMs are in memory.
destroy()disposes the VM. Files do not survive anorange devrestart, so the next call after a restart starts an empty VM. - Preview URLs go through a small proxy in the VM. Servers in the VM listen only on the VM’s own network, so no host port bypasses the preview URL token.
The local provider
The local provider is for development. It is not isolated:
- Each sandbox is a directory:
<ORANGE_SANDBOX_DIR>/<id>. The default is asandboxesfolder in the project’s.open-orangeRivetKit storage, so files surviveorange devrestarts. - File APIs map sandbox paths into that directory.
/workspace/a.txtis<dir>/workspace/a.txt. - Commands run as host processes with
sh -c, as your user. The working directory is the sandbox’sworkspacefolder. A command that uses an absolute path, such ascat /workspace/a.txt, reads the host path. Use relative paths in commands. - Commands see the host’s tools, for example the host’s
python3andnode. - Commands get only
PATHandLANGfrom the host, plus theenvyou pass.HOMEis the sandbox’sworkspacefolder. Other variables oforange dev, such as API keys, are not passed. orange devkills running sandbox processes when it exits.- A server in the sandbox listens on a host port. Anything that can reach that
port, such as another process or, for a server that binds
0.0.0.0, your network, reaches it without the preview URL token.
Configuration
orange dev does not build or run the container image. It prints one warning
for containers and runs the Sandbox class on the provider instead:
Orange does not run container images. Container classes and @cloudflare/sandbox run on ORANGE_SANDBOX_PROVIDER (default: local), which runs only Cloudflare Sandbox images.OpenOrange replaces the @cloudflare/sandbox package with its own module when
it bundles the Worker, like cloudflare:* modules.
A wrong configuration fails the first sandbox call with an error that names the fix. For example:
ORANGE_SANDBOX_PROVIDER=e2b needs E2B_API_KEY. Set E2B_API_KEY in the environment of orange dev, or unset ORANGE_SANDBOX_PROVIDER to use the local provider.If the provider rejects the key or cannot be reached, the error names the provider and the key:
The daytona sandbox provider failed: Invalid credentials. Check DAYTONA_API_KEY, and that orange dev can reach daytona.- Orange reads
ORANGE_SANDBOX_PROVIDER,ORANGE_SANDBOX_DIR, and the provider keys from the shell,.dev.vars, or.env. For theORANGE_*settings, the shell wins. orange doctorchecks the provider of a project with acontainersclass. Itssandboxcheck isokwith<name> provider, or an action with the error above and the hintSet the provider key in .dev.vars, or unset ORANGE_SANDBOX_PROVIDER to use the local provider.
Other errors, each at the first call that needs it:
| Message | Cause |
|---|---|
ORANGE_SANDBOX_PROVIDER=e2b needs the e2b package. Install it next to Orange: pnpm add e2b | The provider’s SDK is not installed. Daytona needs @daytonaio/sdk, and Freestyle needs freestyle. |
ORANGE_SANDBOX_PROVIDER="docker" is not a sandbox provider. Use one of: local, e2b, daytona, freestyle, agentos. | An unknown provider name. |
This sandbox was created with the local provider, but ORANGE_SANDBOX_PROVIDER is now agentos. Switch back, or call destroy() to start over. | The provider changed after the sandbox was created. |
Sandbox.exposePort() is not supported by Orange yet. The e2b provider has no preview URLs on Orange. Use ORANGE_SANDBOX_PROVIDER=local or agentos for preview URLs. | Preview URLs on E2B, Daytona, or Freestyle. |
Sandbox.createSession() is not supported by Orange yet. Use exec() with the cwd and env options. | createSession(). createCodeContext() and runCode() suggest exec('python3 script.py'). |
git clone failed: <stderr> | gitCheckout() could not clone. |
Sandbox lifecycle
getSandbox(env.Sandbox, "my-sandbox")
-> Sandbox Durable Object (Rivet Actor)
storage: { provider: "local", id: "<provider sandbox id>" }
-> provider sandbox (local directory, agentOS VM, E2B, Daytona, or Freestyle)- The first call stores the provider sandbox’s id and the provider name in the object’s storage.
- When the object wakes, for example after an
orange devrestart, it reconnects to the stored sandbox. If the provider no longer has it, the object creates a new one. destroy()deletes the stored id along with the provider sandbox, stops its background processes, and drops its preview URL tokens.- If
ORANGE_SANDBOX_PROVIDERchanges after a sandbox was created, calls fail and name both providers. Switch back, or calldestroy().destroy()deletes the sandbox with the provider that created it, so that provider’s key must still be set.
Preview URLs
exposePort(port, { hostname, token? }) returns
<scheme>://<port>-<sandbox name>-<token>.<hostname>/, as on Cloudflare. The
scheme is http for localhost hostnames and https otherwise. The token is
16 random characters (a-z, 0-9, _), or the token option. Exposing an
exposed port again keeps its token. unexposePort() revokes it, so the next
exposePort() returns a new URL. getExposedPorts(hostname) lists the
exposed ports and their URLs.
proxyToSandbox() in the Worker’s fetch handler sends matching requests to
the Sandbox object, which compares the token in constant time and forwards to
the port. A wrong token, a missing token, or an unexposed port gets Cloudflare’s
404 with {"error":"Access denied: Invalid token or port not exposed","code":"INVALID_TOKEN"}.
With orange dev, send requests to the dev server with that Host header,
for example http://8080-my-sandbox-<token>.localhost:8787/. Most systems
resolve *.localhost to 127.0.0.1. The local and agentOS providers serve
preview URLs.
- The scheme is
httpforlocalhost,127.0.0.1,0.0.0.0, and[::1]. - Call
exposePort()andgetExposedPorts()on a stub fromgetSandbox(), which carries the sandbox name. On another stub, they throwCall exposePort() on a stub from getSandbox(), which carries the sandbox name preview URLs need. - A token in use by another port throws
Token '<token>' is already in use by port <port>. Please use a different token. proxyToSandbox()usesenv.Sandbox, or else the first Durable Object namespace inenv. If forwarding fails, it answers500withProxy routing error.- The token check runs in the Sandbox object, so a caller that reaches the object without the Worker still needs the token.
ctx.container
A class that containers lists gets a ctx.container that runs one sandbox
per Durable Object on ORANGE_SANDBOX_PROVIDER. In any other class, reading
ctx.container throws a NotSupportedError.
start()connects to the object’s stored sandbox, or creates one. The image must be a Cloudflare Sandbox image: its reference, or the Dockerfile it names, containscloudflare/sandbox. Any other image throwsContainer image "<image>" cannot run on the <provider> sandbox provider. Orange runs Container classes on ORANGE_SANDBOX_PROVIDER, which runs only Cloudflare Sandbox images: a Dockerfile or image that names cloudflare/sandbox.start({ entrypoint })throwsContainer.start({ entrypoint }) is not supported on the <provider> sandbox provider. Start the command with exec() instead.A secondstart()throwsThe container is already running.start({ env })sets the environment of later commands.exec(argv)passes each item to the command as one literal argument. It runs in/workspaceunless you passcwd.stdoutandstderrcan be"ignore", andstderr: "combined"merges it intostdout. Beforestart(), it fails withThe container is not running. Call ctx.container.start() first.monitor()resolves afterdestroy(), and rejects withThe container is not runningbeforestart().destroy()stops running commands and deletes the sandbox with the provider that created it. The nextstart()gets a new, empty sandbox.signal()stops every running command.getTcpPort(port).fetch()reaches the port on the local and agentOS providers. On the others, it throws.new Files(ctx.container)reads and writes the same sandbox thatexec()sees. A missing file, or a write into a missing directory, is aSandboxFileErrorwithcode: "ENOENT". A relative path needs an absolutecwdoption.
Deviations
- No container image runs. The
imageincontainersmust name a Cloudflare Sandbox image (cloudflare/sandbox).ctx.container.start()refuses any other image. A sandbox has the provider’s tools, not the tools in your Dockerfile. - The local provider is not isolated. See The local provider.
- Background processes belong to the
orange devprocess. They stop whenorange devstops. On Cloudflare they run until the container sleeps. Processmethods work only on a stub fromgetSandbox(). A rawenv.Sandbox.get(id)stub returns plain process data.kill(signal)always sendsSIGKILLto the process group.- E2B, Daytona, and Freestyle report stdout and stderr as one stream, so
streamed output arrives as
stdoutevents. - A command killed by a signal exits with 128 plus the signal number on the local provider. On the other providers, a killed or timed-out command has no exit code, and Orange reports 137.
exposePort()takes port 3000, which Cloudflare reserves for its container control plane.- The
@cloudflare/sandbox0.xSandboxclass does not check the image.ctx.container.start()does.
Conformance
An end-to-end orange dev test uses a Worker that imports
@cloudflare/sandbox as Cloudflare’s docs show.
| Provider | What the test covers |
|---|---|
| Local | Exit codes for failing commands, streamed exec output, file round trips, streamed background process logs, killing a process, isolation of two sandbox ids, destroy(), preview URL tokens (wrong, missing, revoked, and custom tokens), reconnecting after an orange dev restart, destroy() after ORANGE_SANDBOX_PROVIDER changed, and errors for a missing API key and an unknown provider |
| agentOS | Exec output and exit codes, a file round trip, a missing file, a preview URL, waitForPort(), and a sandbox that is still there after its Durable Object sleeps |
| E2B, Daytona, and Freestyle | A file round trip in /workspace, waitForPort(), and the error for a wrong API key |
The E2B, Daytona, and Freestyle tests create real provider sandboxes, so they
run only when SANDBOX_TEST_E2B_API_KEY, SANDBOX_TEST_DAYTONA_API_KEY, or
SANDBOX_TEST_FREESTYLE_API_KEY is set.
- The local and agentOS tests also check that a secret in the environment of
orange devdoes not reach sandbox commands. ctx.containeron the local provider: exit codes and both streams, argv items with shell characters,destroy(),FileswithENOENT, and the error for an image that is not a Sandbox image. These run intests/bindings/sandbox.test.ts.tests/examples/runnable-examples.test.tsrunsexamples/sandbox, and thesandbox-v1fixture for the 1.x API, on a realorange dev.- The Containers claim has no recorded run of its own yet.
Recorded results
Recorded results from the conformance run of 2026-11-10 (Orange ea40348), 1,670 of 1,851 tests passing across every area. Each check is works when every result passed and partial when some did. The full feature matrix is on the compatibility page.
Sandboxes
| Check | Status | Results |
|---|---|---|
| Sandboxes | Works |
|
Containers
| Check | Status | Results |
|---|---|---|
| Containers | Not run | |