Skip to content

SYSTEM Cited by 5 sources

Cloudflare Sandbox SDK

Sandbox SDK is Cloudflare's higher-level developer API for running untrusted or agent-generated code inside isolated Cloudflare Containers from a Workers application. It was announced in mid-2025 and is positioned as the structural answer to AI agents needing to execute arbitrary code securely without a user-managed container-lifecycle layer.

What the SDK gives you

Instead of raw Container APIs, the SDK exposes a small, ergonomic TypeScript surface for:

  • Command execution: sandbox.exec('node -v')
  • Filesystem management: sandbox.mkdir(path, { recursive: true })
  • Code contexts / REPL-style execution: sandbox.createCodeContext({ language: 'python' }) then sandbox.runCode(...) with persistent state across calls
  • Background processes
  • Service exposure from inside the container
  • Per-key sandbox instances: getSandbox(env.Sandbox, 'user-123') — per-user or per-session isolation without the app managing lifecycle
  • sandbox.mountBucket() — mount an R2 bucket as a filesystem partition inside the container, giving ephemeral containers a durable working directory with zero application code changes (canonical instance of mountable-persistent-storage)

The SDK owns container lifecycle, networking, file systems, process management, and the Worker↔container channel — letting the developer focus on application logic.

Relationship to Cloudflare Containers

Sandbox SDK is built on top of Cloudflare Containers. Containers are inherently ephemeral (durable-vs-ephemeral-sandbox); Sandbox SDK adds the ergonomic layer and the mountable-persistence escape hatch via R2.

Example

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, 'user-123');
    await sandbox.mkdir('/workspace/project/src', { recursive: true });
    const version = await sandbox.exec('node -v');
    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 });
    return Response.json({ version, result });
  }
};

Sandbox SDK 1.0 — utilities, not a base class (2026-09-30)

When Containers launched, Cloudflare deliberately hid the Durable Object behind the Container class, and the Sandbox SDK was built on that class — filling real gaps (native command execution, outbound request interception, snapshots) in userspace. The 2026-09 Containers rearchitecture made those capabilities native on ctx.container, and the cost of the abstraction became clear: hiding the DO made it hard to combine its identity/state/coordination with the Container it controls, and nearly every team needed something slightly different from the generic lifecycle (own sleep policy, own credential handling, own eval-run tracking). (Source: sources/2026-09-30-cloudflare-containers-rebuilt-to-scale-agent-sandboxes)

So Cloudflare made the Durable Object explicit in the developer experience:

  • New capabilities are native-only. The durable_object scheduling policy, faster startup, runtime image/instance selection, and filesystem snapshots are available only through ctx.container — not through the SDK's base class.
  • Container + legacy Sandbox classes maintained through 2026-12-31. Existing deployments keep running after that date but the classes stop getting updates; Cloudflare recommends migrating to ctx.container.
  • Sandbox SDK 1.0 is a set of utilities, not a base class. Its helpers work inside your own Durable Object class, alongside ctx.container.
  • @cloudflare/computer is offered as the higher-level environment (Dynamic Workers + Containers + synchronized filesystem) for teams that want more than raw primitives.

Migration is mostly changing extends Container to extends DurableObject and calling this.ctx.container directly.

Seen in

customer-authored CI pipeline pattern.

  • systems/cloudflare-containers — the lower-level container primitive Sandbox SDK wraps.
  • systems/cloudflare-workers — the compute tier that drives Sandbox SDK.
  • systems/cloudflare-r2 — mounted as durable filesystem via mountBucket().
  • systems/project-think — agent SDK that exposes Sandbox SDK as Tier 4 of the execution ladder.
  • systems/dynamic-workers — the adjacent Tiers 1-3 isolate tier; the ladder escalates from Dynamic Workers to Sandbox when the workload needs full OS semantics.
  • durable-vs-ephemeral-sandbox — the problem shape.
  • execution-ladder — Tier 4 capability.
  • mountable-persistent-storage — the R2-as-FS solution shape.
  • additive-capability-ladder — the ladder pattern Sandbox SDK slots into.
  • companies/cloudflare — operator.
Last updated · 766 distilled / 2,225 read