Cloud Parts

Cloudflare Sandbox SDK

A way to run untrusted or AI-generated code on Cloudflare: each sandbox is a Linux container in its own microVM, started, fed commands and files, and cut off from the network by a Durable Object you write.

What it is
Containers
Part of
Built on Cloudflare Containers
Type
Commercial product
Made by
Cloudflare, Inc.
License
Apache 2.0 (the SDK); the Containers it runs on are a proprietary service
Facts checked
12 October 2026
Website Source code

What it is

A sandbox has three parts: a name, a Durable Object and a container instance. Your Worker authenticates the caller, derives a sandbox name from them, and calls getByName(); that Durable Object starts a container with ctx.container.start(), choosing the image, the instance size and whether the internet is reachable (it isn’t by default). It then runs processes with exec(), which takes an argument array and starts no shell unless you ask for one, and moves files with the Files helper from @cloudflare/sandbox. Each container runs in a Firecracker microVM with its own kernel, so one user’s code can’t reach another’s sandbox. A preview of a web server running inside is served by having your Worker forward requests, such as /previews/<name>/, to the sandbox’s port, behind your own hostname and authentication.

Credentials stay outside: an outbound handler in your Worker can add a token to HTTPS requests after they leave the container, and allow a package registry while blocking everything else. The instance runs while its Durable Object is active and for an inactivity timeout of up to 6 hours after that; when it stops, its disk and processes are gone unless you saved a snapshot or synced files to R2. Sandbox SDK 1.0 (September 30, 2026) turned the old Sandbox class into this do-it-yourself model, cutting the median time from start() to the first command from about 4 seconds to under 600 ms. Billing is ordinary Containers, Workers and Durable Objects usage on the Workers Paid plan.

Why teams pick it

  • Strong isolation per user or per job: every sandbox is a microVM with its own kernel and network, with the internet off unless you turn it on
  • Secrets never enter the sandbox: outbound handlers in your Worker add credentials and decide which hosts the code may reach
  • Starts fast on a prepared image (median under 600 ms to the first command in 1.0), and each start() can pick its own image and size
  • Works with existing tools: Claude Code, Codex, Devin and other coding agents have guides for running inside a sandbox

Watch out for

  • 1.0 is a thin library: your Durable Object handles lifetime, retries, timeouts, preview routing and snapshot bookkeeping, and it needs the durable_object scheduling policy, still in public beta
  • Code running inside doesn’t count as activity, so a long build stops when the inactivity timeout (at most 6 hours) ends unless an alarm or request keeps the Durable Object busy
  • Every process in a sandbox has root-equivalent capabilities, so the sandbox is the smallest unit of trust; two users must never share one
  • Moving from 0.x is a one-way switch that wrangler rollback can’t undo; 0.x gets only bug and security fixes until 2026-12-31

How it fits with other technologies

Run a command in a per-user Linux sandbox with no internet access (SDK 1.0) · ts

import { DurableObject } from "cloudflare:workers";

export class MySandbox extends DurableObject<Env> {
  async run(argv: string[]) {
    const container = this.ctx.container!;
    if (!container.running) {
      container.start({
        image: "cloudflare/debian-trixie",
        entrypoint: ["sleep", "infinity"], // keep it running between commands
        enableInternet: false,
      });
      await container.setInactivityTimeout(10 * 60 * 1000);
    }
    const proc = await container.exec(argv); // no shell unless you start one
    const out = await proc.output();
    return { stdout: new TextDecoder().decode(out.stdout), exitCode: out.exitCode };
  }
}

export default {
  async fetch(request: Request, env: Env) {
    const user = await authenticate(request); // derive the sandbox name from identity
    const { argv } = await request.json<{ argv: string[] }>();
    return Response.json(await env.MY_SANDBOX.getByName(user.id).run(argv));
  },
};

See it in a real stack

No architecture uses Cloudflare Sandbox SDK yet. Drop it into the playground and wire it up yourself.Open playground →
Where it came from2025–2026

The first Cloudflare Containers announcement, in April 2025, led with one use case: a platform where users run code an LLM wrote, which is untrusted, so each user needs a secure sandbox of their own. The cloudflare/sandbox-sdk repository appeared on GitHub in June 2025, as Containers entered public beta, and a major release on August 5, 2025 turned it into a full execution platform: streamed output, persistent Python and JavaScript code interpreters, file access, Git operations, background processes and public preview URLs for running services.

Containers and Sandboxes became generally available together on April 13, 2026, by which point the SDK had added browser terminals, backup and restore of workspaces, and file watching. In June 2026 Cloudflare deprecated several features, saying the SDK had shipped many experiments as agent workflows developed: a Linux desktop for computer use was removed for low adoption, exposePort() gave way to Cloudflare Tunnel, and a default shell session shared across exec() calls was dropped because it confused agents and caused hard-to-trace bugs.

Sandbox SDK 1.0, released on September 30, 2026 during Birthday Week alongside a rebuild of Containers for agent sandboxes, moved control into the developer’s own Durable Object: the package no longer starts, stops or tracks containers, and keeps only helpers such as Files. In exchange, each sandbox can choose its image and size at start time, deploys no longer restart running sandboxes, and start-up got roughly seven times faster.

Why it’s built this way

A container in a microVM, not an isolate, for Linux code
Most existing tools expect an operating system: npm test needs Node.js, files and child processes, and preview servers keep processes listening on ports. Cloudflare offers Dynamic Workers for code that only calls known methods, and Containers for everything that needs Linux.
Your Durable Object, not the SDK, owns each sandbox (1.0)
How long a sandbox runs, what it can reach and whether a failed command is safe to rerun depend on the application. A cancelled command may already have changed files, and only the application knows whether running it again is safe.
Commands as argument arrays with no shared session
In 1.0 exec() starts a process without a shell, so text in an argument can’t start a second command, and each call sets its own working directory and environment. A session carried between calls had confused agents.

Timeline

  1. 2025

    Containers announced in April with per-user sandboxes for LLM-generated code as the lead example

  2. 2025

    The sandbox-sdk repository is published in June, as Containers enter public beta

  3. 2025

    August 5: code interpreters, Git, background processes and preview URLs

  4. 2026

    Containers and Sandboxes generally available on April 13

  5. 2026

    June 9: desktop, exposePort() and default sessions deprecated

  6. 2026

    Sandbox SDK 1.0 on September 30: control moves into your own Durable Object

Sources13 · facts checked 12 October 2026

Improve this page on GitHub