Run untrusted or generated code in a Linux sandbox that belongs to one user, task, or session. Your Worker decides who gets a sandbox, which hosts it can reach, and which credentials stay out of it.

A sandbox is a Durable Object and the Container it starts. The Durable Object starts the instance and runs commands with the Container API on this.ctx.container. @cloudflare/sandbox adds three things that API does not have:

• Files streams files in and out of the running instance and reports Linux errors such as ENOENT.
• S3Mount mounts an S3-compatible bucket at a path. Your Worker signs each storage request, so the credentials never enter the sandbox.
• DirectoryBackup saves a directory to R2 and restores it into any Container, including one on a newer image. The Container reaches only the one object each operation needs.

Read the documentation

Create a project from the minimal template, or deploy it directly:

npm create cloudflare@latest -- my-sandbox --template=cloudflare/sandbox-sdk/examples/minimal

The template gives each name in the URL its own sandbox. At its core is a Durable Object like this one:

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

export class Sandbox extends DurableObject<Env> {
  async run(script: string) {
    const container = this.ctx.container;
    if (!container) throw new Error("The container binding is not configured");

    if (!container.running) {
      container.start({ image: container.images.sandbox, enableInternet: false });
    }

    const files = new Files(container);
    await files.writeFile("/workspace/task.sh", script);

    const process = await container.exec(["sh", "task.sh"], { cwd: "/workspace" });
    const { exitCode, stdout } = await process.output();
    return { exitCode, stdout: new TextDecoder().decode(stdout) };
  }
}

export default {
  async fetch(request, env) {
    // Authenticate the request, then choose the sandbox for this user or task.
    const sandbox = env.SANDBOX.getByName("user-123");
    return Response.json(await sandbox.run(await request.text()));
  },
} satisfies ExportedHandler<Env>;

The image needs the helper that Files runs, and the Worker needs nodejs_compat. Refer to Requirements.

To run JavaScript or Python without a Linux environment, use Dynamic Workers instead.

Version 0.x provided a Sandbox class that owned the Container and ran commands for you. In 1.0, your own Durable Object starts the Container, and this package provides only file operations and bucket mounts. The migration guide maps each 0.x API to its replacement. The 0.x source is on the v0 branch.

To learn how these parts fit together, read Architecture. The package and sandbox-shim exchange frames described in Shim protocol. S3 mounts design explains S3Mount and S3Gateway. To add an example, read Examples.

Build and test with Node.js and Docker:

npm install
npm run check
npm test

Testing explains what these commands check, how to build behind a TLS-inspecting proxy, and how to test in production. Releasing explains how maintainers publish the package and its image.

Apache License 2.0