Cloudflare Sandbox SDK 1.0: Your Durable Object Owns the Container

Cloudflare stopped pretending the sandbox wrapper was the product. On September 30, 2026, the company shipped Sandbox SDK 1.0 and, in the same wave, rebuilt Containers for on-demand agent workspaces. Your own Durable Object class now owns each Linux sandbox through this.ctx.container. Image, instance size, idle policy, outbound credentials, and agent tools live in application code — not in a deploy-time Containers app you have to mint for every toolchain.

That is the practitioner story. Artifacts open beta gave agents a Git remote on October 1. Cloudflare Computer already argued isolates first, containers on demand. Sandbox SDK 1.0 is the container control plane catching up: faster starts, runtime configuration, and beta filesystem snapshots so a workspace can sleep without losing the checkout.

Same week, Cloudflare Agents SDK also wired Pi Durable into a beta PiHarness lifecycle helper. That is a harness persistence story, not a bigger sandbox launch — see our Pi 1.0 / Pi Durable post. This article stays on Sandbox SDK 1.0.

TL;DR — what people are asking

What Sandbox SDK 1.0 actually adds for agents

The changelog is blunt: Sandbox SDK 1.0 is available, and your Durable Object class controls each sandbox container directly. With 1.0 your class can:

• Choose the image and instance size each time it starts a sandbox
• Run sandboxes on different images from one class
• Leave running sandboxes alone across deploys (new image applies on next start)
• Snapshot filesystem state (public beta) and start the same or a new sandbox from it
• Decide when each sandbox stops (task done, user idle, after snapshot)
• Exec with streamed I/O, send signals, open terminals
• Serve previews from sandbox ports with your hostnames and auth
• Handle outbound requests per hostname in Worker code so secrets never enter the container
• Expose only the RPC methods callers need
• Run an agent in the same Durable Object and give the model a tool that runs commands in the sandbox

That last bullet is the agent harness pattern Cloudflare keeps repeating: brain in the Durable Object, hands in Linux. It matches Anthropic's "decouple the brain from the hands" framing that Cloudflare cites in the Containers blog — the agent stays available while sandboxes start, stop, fail, or get replaced.

@cloudflare/sandbox is no longer "the base class you inherit." It is utilities for work the native API does not cover:

Native path: ctx.container.start(), exec(), outbound handlers, snapshots. Package path: file streaming, bucket mounts, directory backups.

How this relates to Containers, Workers, and Artifacts

Think of three layers Cloudflare is stacking for coding agents:

Workers still front the request. Containers still bill the Linux VM. Sandbox SDK 1.0 is how your Durable Object programs that VM without a generic Sandbox lifecycle papering over your sleep policy.

Artifacts is not replaced. A sandbox without a remote is still "files died when the container slept" unless you snapshot or mount storage. The October Artifacts open beta is the Git remote; Sandbox SDK is where git clone / npm install / pytest actually run. Pair them in a coding-agent loop: fork an Artifacts repo, start a sandbox, hand the agent remote + token + an exec tool, push, preview.

@cloudflare/computer remains the higher-level bet from Agents Week: one Workspace filesystem, isolate backends for cheap work, containers when you need real Linux. Cloudflare's Containers post still points there for "synchronized filesystem across Dynamic Workers and Containers." Sandbox SDK 1.0 is the lower-level escape hatch when you want ctx.container without the Computer abstraction.

The durable_object scheduling policy (why starts got faster)

Until now, image and instance type were deploy-time Containers configuration. One Node lite sandbox and one Python build sandbox meant two apps, two namespaces, and routing in your Worker. Agents do not work that way. They create sandboxes per task, expect them ready immediately, and want to pause and resume.

The new durable_object scheduling policy (public beta) moves those decisions into start():

// wrangler.jsonc (shape from Cloudflare's Containers blog)
{
  "containers": [
    {
      "class_name": "AgentSandbox",
      "scheduling_policy": "durable_object",
      "images": {
        "node": { "dockerfile": "./images/node/Dockerfile" },
        "python": { "dockerfile": "./images/python/Dockerfile" }
      }
    }
  ],
  "durable_objects": {
    "bindings": [{ "name": "SANDBOX", "class_name": "AgentSandbox" }]
  }
}

At runtime your Durable Object picks this.ctx.container.images.node or .python and an instance type (lite, standard-2, etc.). Rollouts become code: pin an image in DO storage, canary by hashing the DO id, migrate after a snapshot. A deploy does not yank a running agent mid-npm install.

Scheduling also got a new path. Demand starts at the Durable Object. Placement prefers the same machine, then the same location, then hosts that already have the image or snapshot cached. The runtime restores a prepared VM instead of booting from scratch for every first command.

Cloudflare published ComputeSDK Burst TTI numbers (100 concurrent sandboxes, client time-to-interactive):

They also claim a preliminary burst of 100,000 containers in 5.387 seconds across six locations. Treat that as a platform stress number, not your app SLA — but it is the signal Cloudflare wants agent platforms to hear.

For agents that configure the environment at runtime, Cloudflare ships cloudflare/debian-trixie: Debian Trixie Slim plus Node.js 24.20.0 LTS, pre-distributed so first start is not "download and unpack a custom Dockerfile while the user waits."

Filesystem snapshots: pause without losing the workspace

Cold start is only half the wait. Clone + install + toolchain setup still dominate coding-agent sessions. Filesystem snapshots (public beta on the new policy) let you:

1. Prepare a workspace once
2. snapshotContainer({ name: "project-ready" })
3. Persist the snapshot handle in Durable Object storage
4. Later start({ containerSnapshot: snapshot, instance: "standard-2", ... })

Two patterns Cloudflare calls out:

• Resume a project — save when the user leaves; restore tomorrow with repo, node_modules, and edits intact
• Eval / RL forks — one immutable baseline snapshot starts N isolated attempts so prompt or model diffs are not confounded by environment drift

Snapshots complement Artifacts. Artifacts is the durable Git history humans review. Snapshots are the hot workspace disk (deps, caches, dirty trees) you do not want to rebuild every turn. Many teams will use both: Artifacts for the remote of record, snapshots for session continuity inside Containers.

Minimal setup sketch

Official docs walk migration and deploy in full. The 1.0 shape from the changelog looks like this:

import { Files } from "@cloudflare/sandbox";
import { DurableObject } from "cloudflare:workers";

export class MySandbox extends DurableObject<Env> {
  private readonly container: Container;
  private readonly files: Files;

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    if (!ctx.container) {
      throw new Error("No container is configured");
    }
    this.container = ctx.container;
    this.files = new Files(ctx.container);
  }

  async run(script: string) {
    if (!this.container.running) {
      this.container.start({
        image: this.container.images.sandbox,
        instance: "lite",
        enableInternet: false,
      });
    }

    await this.files.writeFile("/tmp/task.sh", script);
    const proc = await this.container.exec(["sh", "/tmp/task.sh"]);
    return proc.output();
  }
}

Practical checklist:

1. Put the Durable Object on scheduling_policy: "durable_object" and declare the images it may choose.
2. Start with enableInternet: false. Allow specific hostnames through outbound handlers so tokens never sit inside the sandbox.
3. Decide idle policy in your class (stop after task, after snapshot, after user idle) — 1.0 expects you to own lifetime.
4. For untrusted JavaScript/Python/Wasm without a full Linux box, use Dynamic Workers (Sandbox docs cover that path separately).
5. If you are on 0.x, read Migrate from Sandbox SDK 0.x. You can run a 1.0 class beside 0.x and move sandboxes gradually. The deploy that flips an existing class to the new policy is one-way — rehearse first.

0.x apps keep running on npm. Cloudflare commits bug and security fixes for Sandbox SDK 0.x through December 31, 2026. After that, deployments keep running but the legacy Container / Sandbox classes stop getting updates. New capabilities (runtime image selection, the fast path, snapshots) are native-only on ctx.container.

Pricing and limits (as stated)

Sandbox SDK has no separate price list. Docs say billing is the underlying Containers platform, plus Workers, Durable Objects, and optional Workers Logs.

From Containers pricing (as of the docs Cloudflare links from Sandbox):

Charges start when a request hits the container or you start it manually. Charges stop after the instance sleeps (timeout). Memory and disk bill on provisioned instance type; CPU bills on active use.

Instance types currently listed:

Network egress (Containers docs): North America & Europe $0.025/GB (1 TB included); Oceania/Korea/Taiwan $0.05/GB (500 GB); elsewhere $0.04/GB (500 GB).

For agent platforms the cost model is: sleep aggressively, snapshot or push to Artifacts before stop, prefer lite/basic until the task proves it needs standard-*, and keep the agent loop in the Durable Object so idle Linux is not running while the model thinks.

Workers subrequest limits still matter if you chatter to the container a lot from a single Worker invocation. Prefer RPC-style patterns from inside the Durable Object that owns the container rather than fan-out HTTP from a short-lived Worker request.

What people are asking (and what to answer)

Do I need a new Dockerfile for every agent task?

Not always. Start from cloudflare/debian-trixie, exec to clone and install, then snapshot. Or declare a small set of images in Wrangler and pick at start(). The point of the new policy is that task code chooses, not a new wrangler deploy per toolchain.

Should I migrate off 0.x this week?

If you need runtime image selection, the fast scheduling path, or snapshots — yes, those are 1.0 / ctx.container only. If 0.x is stable and you are not hitting the wrapper's lifecycle limits, you have until end of 2026 for bugfixes. Plan the one-way policy cutover; do not treat it as a casual config flip.

Where do credentials live?

In the Worker / Durable Object. Outbound handlers inject tokens for allowed hostnames. The container should not hold GitHub PATs or package-registry secrets on disk if you can avoid it. Same discipline as Artifacts repo-scoped tokens: short-lived, scoped, outside the untrusted workspace.

Is this the same as OpenAI Agents sandbox or Vercel Sandbox?

Same industry shape (ephemeral Linux for tool use), different control plane. Cloudflare's differentiator is the Durable Object attached to every container — identity, storage, and policy next to the VM. For OpenAI's public Agents API sandbox framing, see our Agents API public beta coverage. For isolate-first routing, stay with Cloudflare Computer.

What about Pi Durable in Agents SDK this week?

Cloudflare's AI changelog documents PiHarness: run Pi Durable sessions inside an Agent / Durable Object with lifecycle recovery after eviction. It is beta, experimental, and about harness transcript durability, not about replacing Containers. Mention it so you do not write a second news post for a smaller ship — then come back to Sandbox SDK when you need a real Linux workspace.

Honest limitations

• durable_object policy and snapshots are public beta. Expect API and ops docs to move.
• Containers require Workers Paid. Free plan has no Containers allotment in the published table.
• 0.x sunset for updates is December 31, 2026. Existing deploys may keep running; do not assume feature parity forever.
• Sandbox ID ≠ immortal container. Idle stop or replacement drops processes, terminals, and local files unless you restored from snapshot, backup, or mount.
• Internet is off until you enable it. enableInternet: true is a deliberate security decision, not a default comfort setting.
• SDK docs still have 0.x and 1.0 tracks. Match Worker package and container image lines; do not mix @next Worker package with a stable container image (or the reverse) if docs warn against it.
• Artifacts billing starts mid-October on a separate meter. Snapshot storage and Artifacts storage are not the same invoice line — model both if your loop uses both.

What builders should do this week

1. Read the Sandbox SDK 1.0 changelog and the Containers agent-sandboxes blog. Confirm you need Linux, not just Dynamic Workers.
2. Stand up one Durable Object on scheduling_policy: "durable_object" with cloudflare/debian-trixie or a tiny custom image. Measure time from start() to first exec() on your account.
3. Add a model tool that only calls methods you expose (e.g. run(script)), not raw container RPC from the client.
4. Wire Artifacts as the Git remote for anything you want reviewed outside the sandbox disk.
5. If you are on 0.x, schedule a migration rehearsal before year-end; keep the one-way policy cutover intentional.
6. If you care about Pi sessions on Cloudflare, skim PiHarness docs and our Pi 1.0 post — then decide whether that is your loop or whether you still need Sandbox SDK for compilers and previews.

Closing

Sandbox SDK 1.0 is Cloudflare admitting the wrapper was in the way. Agents need programmable Linux that starts in hundreds of milliseconds, picks compute per task, sleeps without losing the workspace story, and keeps secrets in the Durable Object. Containers pricing and Artifacts remotes are the rest of the bill. Migrate when you need the native path; do not confuse a beta PiHarness with a container runtime.

Follow @explainx_ai as snapshot GA, 0.x sunset, and the Artifacts contest deadline land this month.

Related on explainx.ai

• Cloudflare Artifacts open beta: Git remotes for AI agents — the versioned remote next to this sandbox
• Cloudflare Computer: agents need isolates, not just containers — higher-level Workspace + isolate backends
• Pi 1.0 and Pi Durable — same-week Agents SDK harness note, not a second sandbox article
• Loop engineering for coding agents — why N agents need N workspaces
• What is an agent harness? — brain vs hands framing
• Cloudflare Worker Previews — branch environments when the agent pushes
• OpenAI Agents API public beta sandbox — parallel industry sandbox shape
• Cloudflare OS: Gatekeepers and Gadgets — policy layer above the workspace

Sources

• Sandbox SDK 1.0 changelog (September 30, 2026)
• Cloudflare Blog — Containers rebuilt for agent sandboxes (September 30, 2026)
• Sandbox SDK docs
• Changes in Sandbox SDK 1.0
• Containers pricing
• Sandbox pricing (points at Containers)
• AI changelog — Pi Durable / PiHarness

Sandbox SDK 1.0 APIs, Containers pricing, snapshot beta status, and 0.x support dates reflect Cloudflare materials dated September 30, 2026 and the docs linked above. Re-check changelog, pricing, and migration guides before you cut over production classes — beta scheduling and snapshots can still move.

Update — October 3, 2026: Related: Cloudflare Web Search API via AI Gateway.