智能体
developers.cloudflare.com ·
@Cloudflare Developers
Cloudflare 发布 Sandbox SDK 1.0：用自有 Durable Object 控制每个沙箱
Cloudflare 官方 changelog 宣布 Sandbox SDK 1.0 可用，开发者可通过 Durable Object 容器 API（this.ctx.container）直接控制沙箱容器。1.0 支持每次启动时选择镜像与实例规格、将沙箱文件保存为快照（public beta）并据此恢复或新建沙箱、自定义停止时机、流式执行命令并发送信号、打开浏览器终端、以自有域名和鉴权提供端口预览、在 Worker 代码中处理各主机名出站请求以保留凭证与绑定、仅暴露指定方法，并可在同一 Durable Object 内运行 agent 并向模型提供执行沙箱命令的工具。文中给出 JS 与 TS 示例代码。
AI推荐理由 Cloudflare 官方 changelog 发布 Sandbox SDK 1.0，明确列出 Durable Object 直接控制沙箱容器、按次选择镜像与实例规格、快照保存/恢复（public beta）、流式命令与终端、端口预览、出站请求凭证托管、同 DO 内运行 agent 并暴露命令执行工具等能力，并附 JS/TS 代码示例。属于官方首发、事实明确、信息密度高，对 Agent 沙箱与开发工具有直接参考价值；局限是快照仍为 public beta，且未提供性能或稳定性实测数据。
82
正文
Sandbox SDK 1.0 is available. Your own Durable Object class now controls each sandbox container directly, through the [Durable Object container API](https://developers.cloudflare.com/containers/api/durable-object-container/) on `this.ctx.container`.
With 1.0, your class can:
* 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.
* Save the files of a sandbox as a [snapshot](https://developers.cloudflare.com/sandbox/files/save-and-restore-a-workspace/), in public beta, and start the same sandbox or a new one from it.
* Decide when each sandbox stops, for example when a task finishes, when its user goes idle, or after it saves a snapshot.
* Run commands with streamed input and output, send them signals, and open [terminals](https://developers.cloudflare.com/sandbox/commands/open-a-terminal-in-the-browser/).
* Serve [previews](https://developers.cloudflare.com/sandbox/previews/) from ports in the sandbox, with your own hostnames and authentication.
* Handle outbound requests for each hostname in Worker code, so [credentials](https://developers.cloudflare.com/sandbox/network/call-an-authenticated-api/) and bindings stay in your Worker.
* Expose only the methods that you want callers to use.
* Run an [agent](https://developers.cloudflare.com/agents/tools/sandbox/) in the same Durable Object, and give the model a tool that runs commands in the sandbox.
src/index.jsjs
```
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();
}
}
```
src/index.tsts
```
import { Files } from "@cloudflare/sandbox";
import { DurableObject } from "cloudflare:workers";
export class MySandbox extends DurableObject {
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();
}
}
```
Your class uses the container API directly, with the [`durable_object` scheduling policy](https://developers.cloudflare.com/changelog/post/2026-09-30-durable-object-scheduling-policy/) and [container snapshots](https://developers.cloudflare.com/changelog/post/2026-09-30-snapshots/), both in public beta. [`@cloudflare/sandbox`](https://developers.cloudflare.com/sandbox/reference/) adds classes for work that the API does not include:
* `Files` streams files in and out of the running sandbox.
* `S3Mount` mounts an S3-compatible bucket, such as R2. Your Worker signs each storage request, so the credentials stay out of the sandbox.
* `DirectoryBackup` saves a directory to R2 and restores it into any sandbox, including one on a newer image.
#### If you use Sandbox SDK 0.x
Your 0.x applications keep running, and `@cloudflare/sandbox` 0.x stays on npm. Sandbox SDK 0.x receives bug and security fixes until 2026-12-31, and its documentation stays at [Sandbox SDK 0.x](https://developers.cloudflare.com/sandbox/sdk/).
When you are ready, [Migrate from Sandbox SDK 0.x](https://developers.cloudflare.com/sandbox/sdk/migrate/) 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 [Sandboxes documentation](https://developers.cloudflare.com/sandbox/) also covers Dynamic Workers, for untrusted code in JavaScript, Python, or WebAssembly.