Cloudflare Sandbox

Cloudflare Sandbox via a Worker / Durable Object binding — a code interpreter, native ports with proxied fetch, and get-or-create semantics. Worker-only.

Website Docs GitHub

Installation

@cloudflare/sandbox is an optional peer dependency, used from inside a Cloudflare Worker. The adapter needs the Durable Object namespace binding for your exported Sandbox class.

pnpm add sbox-sdk @cloudflare/sandbox

Usage

Cloudflare is Worker-only — it runs against a live Durable Object binding, not a plain Node process. Pass the binding from your Worker env:

import { createSandboxClient } from "sbox-sdk";
import { cloudflare } from "sbox-sdk/cloudflare";

export default {
  async fetch(request: Request, env: Env) {
    const client = createSandboxClient({
      provider: cloudflare({
        binding: env.Sandbox, // your Durable Object namespace
        hostname: "my-worker.example.com", // for preview URLs
      }),
    });

    const sandbox = await client.create({ name: "session-42" });
    const exec = await sandbox.code.runCode("print('hello from the edge')");
    return Response.json({ logs: exec.logs });
  },
};

The base image is defined by your Worker's container config at deploy time, so template is ignored. create() uses name (or the idempotency key) as the Durable Object id, giving get-or-create semantics. list is unsupported.

Authentication

No API key — a Worker Durable Object binding.

Authentication variables for the cloudflare adapter.
Option	Env var	Required	Description
`binding`	—	required	The Durable Object namespace binding for your exported Sandbox class, read from the Worker `env`.
`hostname`	—	optional	Your Worker's domain — required to build preview URLs for exposed ports.

Cloudflare runs inside a Worker; authorization is the binding configured in wrangler.toml, not an environment variable.

Options

Prop

Type

Capabilities

Capability	Level	Notes
`setTimeout`	native
`streaming`	native
`filesUpload`	native
`codeInterpreter` / `statefulKernel`	native	`sandbox.code` is defined
`exposePort`	native	preview via wildcard DNS
`proxiedFetch`	native	`ports.fetch()` proxies through the Worker
`list` / `stop` / `pause` / `background`	unsupported
`snapshot` / `fork`	unsupported

previewModel is wildcardDNS.