infochanged

Sandboxes - Sandbox SDK 1.0: control every sandbox from your own Durable Object

Announced: 2026-09-30
Effective: 2026-12-31
Tags: Sandboxes
Severity: info, set by reef/rss-rule-v1
Source: https://developers.cloudflare.com/changelog/post/2026-09-30-sandbox-sdk-1-0/

Sandbox SDK 1.0 is available. Your own Durable Object class now controls each sandbox container directly, through the <a href="https://developers.cloudflare.com/containers/api/durable-object-container/">Durable Object container API</a> on <code>this.ctx.container</code>. With 1.0, your class can: <ul> <li>Choose the image and instance size each time it starts a sandbox. One class can run sandboxes on different images, and a deploy does not restart sandboxes that are running.</li> <li>Save the files of a sandbox as a <a href="https://developers.cloudflare.com/sandbox/files/save-and-restore-a-workspace/">snapshot</a>, in public beta, and start the same sandbox or a new one from it.</li> <li>Decide when each sandbox stops, for example when a task finishes, when its user goes idle, or after it saves a snapshot.</li> <li>Run commands with streamed input and output, send them signals, and open <a href="https://developers.cloudflare.com/sandbox/commands/open-a-terminal-in-the-browser/">terminals</a>.</li> <li>Serve <a href="https://developers.cloudflare.com/sandbox/previews/">previews</a> from ports in the sandbox, with your own hostnames and authentication.</li> <li>Handle outbound requests for each hostname in Worker code, so <a href="https://developers.cloudflare.com/sandbox/network/call-an-authenticated-api/">credentials</a> and bindings stay in your Worker.</li> <li>Expose only the methods that you want callers to use.</li> <li>Run an <a href="https://developers.cloudflare.com/agents/tools/sandbox/">agent</a> in the same Durable Object, and give the model a tool that runs commands in the sandbox.</li> </ul> <div><div data-nb-tabs data-nb-sync-key="workersExamples" class><div class="relative flex border-b border-border" role="tablist" data-nb-tabs-list></div><div class="mt-3"><div role="tabpanel" data-nb-tabs-content data-nb-tab-label="JavaScript" class><figure class="nb-code-figure nb-code-figure-titled" data-nb-lang="js"><figcaption class="nb-code-title">src/index.jsjs</figcaption><pre class="astro-code astro-code-themes github-light github-dark nb-shiki-c6xiwz" tabindex="0" data-language="js" data-nb-lang="js"><code>import { Files } from "@cloudflare/sandbox"; import { DurableObject } from "cloudflare:workers"; export class MySandbox extends DurableObject { container; files; constructor(ctx, 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) { if (!this.container.running) { // Your code chooses the image, size, and network access. 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(); } }</code></pre></figure></div><div role="tabpanel" data-nb-tabs-content data-nb-tab-label="TypeScript" class><figure class="nb-code-figure nb-code-figure-titled" data-nb-lang="ts"><figcaption class="nb-code-title">src/index.tsts</figcaption><pre class="astro-code astro-code-themes github-light github-dark nb-shiki-c6xiwz" tabindex="0" data-language="ts" data-nb-lang="ts"><code>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) { // Your code chooses the image, size, and network access. 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(); } }</code></pre></figure></div></div></div><script type="module" src="https://developers.cloudflare.com/home/runner/work/cloudflare-docs/cloudflare-docs/src/components/ui/tabs/Tabs.astro?astro&type=script&index=0&lang.ts"></script></div> Your class uses the container API directly, with the <a href="https://developers.cloudflare.com/changelog/post/2026-09-30-durable-object-scheduling-policy/"><code>durable_object</code> scheduling policy</a> and <a href="https://developers.cloudflare.com/changelog/post/2026-09-30-snapshots/">container snapshots</a>, both in public beta. <a href="https://developers.cloudflare.com/sandbox/reference/"><code>@cloudflare/sandbox</code></a> adds classes for work that the API does not include: <ul> <li><code>Files</code> streams files in and out of the running sandbox.</li> <li><code>S3Mount</code> mounts an S3-compatible bucket, such as R2. Your Worker signs each storage request, so the credentials stay out of the sandbox.</li> <li><code>DirectoryBackup</code> saves a directory to R2 and restores it into any sandbox, including one on a newer image.</li> </ul> <div tabindex="-1" class="heading-wrapper level-h4"><h4 id="if-you-use-sandbox-sdk-0x">If you use Sandbox SDK 0.x</h4><a class="anchor-link" href="#if-you-use-sandbox-sdk-0x"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></a></div> Your 0.x applications keep running, and <code>@cloudflare/sandbox</code> 0.x stays on npm. Sandbox SDK 0.x receives bug and security fixes until 2026-12-31, and its documentation stays at <a href="https://developers.cloudflare.com/sandbox/sdk/">Sandbox SDK 0.x</a>. When you are ready, <a href="https://developers.cloudflare.com/sandbox/sdk/migrate/">Migrate from Sandbox SDK 0.x</a> shows the 1.0 code for each 0.x feature, including preview URLs, tunnels, background processes, terminals, backups, and the code interpreter. The guide keeps the preview URLs and named tunnels that your 0.x application created working. You can move every sandbox in one deploy, or run a 1.0 class next to your 0.x class and move sandboxes one at a time. The deploy that moves an existing class to the new policy is one-way, so the guide shows how to rehearse it first. The <a href="https://developers.cloudflare.com/sandbox/">Sandboxes documentation</a> also covers Dynamic Workers, for untrusted code in JavaScript, Python, or WebAssembly.

The text above is the source's. reef added the severity, the dates it could read from the text, and the endpoints and scopes named in code.