@cloudflare/sandbox 0.13.0-next.769.1 → 1.0.0-rc.0

package/README.md

@@ -1,263 +1,106 @@
-<img width="1362" height="450" alt="Image" src="https://github.com/user-attachments/assets/6f770ae3-0a14-4d2b-9aed-a304ee5446c5" />
+<img width="1362" height="450" alt="sandbox" src="https://github.com/user-attachments/assets/6f770ae3-0a14-4d2b-9aed-a304ee5446c5" />
 
 # Cloudflare Sandbox SDK
 
 [![npm version](https://img.shields.io/npm/v/@cloudflare/sandbox)](https://www.npmjs.com/package/@cloudflare/sandbox)
 [![npm downloads](https://img.shields.io/npm/dw/@cloudflare/sandbox)](https://www.npmjs.com/package/@cloudflare/sandbox)
 
-**Build secure, isolated code execution environments on Cloudflare.**
+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.
 
-The Sandbox SDK lets you run untrusted code safely in isolated containers. Execute commands, manage files, run background processes, and expose services — all from your Workers applications.
+A sandbox is a Durable Object and the [Container](https://developers.cloudflare.com/containers/) 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:
 
-Perfect for AI code execution, interactive development environments, data analysis platforms, CI/CD systems, and any application that needs secure code execution at the edge.
+- [`Files`](https://developers.cloudflare.com/sandbox/reference/files/) streams files in and out of the running instance and reports Linux errors such as `ENOENT`.
+- [`S3Mounts`](https://developers.cloudflare.com/sandbox/reference/s3-mounts/) mounts an S3-compatible bucket at a path. Your Worker signs each storage request, so the credentials never enter the sandbox.
+- [`DirectoryBackups`](https://developers.cloudflare.com/sandbox/reference/directory-backups/) 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.
 
-## Getting Started
+**[Read the documentation](https://developers.cloudflare.com/sandbox/)**
 
-### Prerequisites
+## Try it
 
-1. Install [Node.js](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) (version 16.17.0 or later)
-2. Ensure Docker is running locally ([see setup guide](https://developers.cloudflare.com/sandbox/get-started/#ensure-docker-is-running-locally))
-3. For deploying to production, sign up for a [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages)
+Create a project from the minimal template, or deploy it directly:
 
-### 1. Create a new project
-
-Create a new Sandbox SDK project using the minimal template:
-
-```bash
+```sh
 npm create cloudflare@latest -- my-sandbox --template=cloudflare/sandbox-sdk/examples/minimal
-cd my-sandbox
-```
-
-### 2. Test locally
-
-Start the development server:
-
-```bash
-npm run dev
-```
-
-> **Note:** First run builds the Docker container (2-3 minutes). Subsequent runs are much faster.
-
-Test the endpoints:
-
-```bash
-# Execute Python code
-curl http://localhost:8787/run
-
-# File operations
-curl http://localhost:8787/file
-```
-
-### 3. Deploy to production
-
-Deploy your Worker and container:
-
-```bash
-npx wrangler deploy
 ```
 
-> **Wait for provisioning:** After first deployment, wait 2-3 minutes before making requests.
-
-**📖 [View the complete getting started guide](https://developers.cloudflare.com/sandbox/get-started/)** for detailed instructions and explanations.
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/sandbox-sdk/tree/main/examples/minimal)
 
-## Quick API Example
+The template gives each name in the URL its own sandbox. At its core is a Durable Object like this one:
 
-```typescript
-import { getSandbox, proxyToSandbox, type Sandbox } from '@cloudflare/sandbox';
-
-export { Sandbox } from '@cloudflare/sandbox';
-
-type Env = {
-  Sandbox: DurableObjectNamespace<Sandbox>;
-};
-
-export default {
-  async fetch(request: Request, env: Env): Promise<Response> {
-    // Required for preview URLs
-    const proxyResponse = await proxyToSandbox(request, env);
-    if (proxyResponse) return proxyResponse;
+```ts
+import { Files } from "@cloudflare/sandbox";
+import { DurableObject } from "cloudflare:workers";
 
-    const url = new URL(request.url);
-    const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
+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");
 
-    // Execute Python code
-    if (url.pathname === '/run') {
-      const process = await sandbox.exec(['python3', '-c', 'print(2 + 2)']);
-      const output = await process.output({ encoding: 'utf8' });
-      return Response.json({
-        output: output.stdout,
-        success: output.exitCode === 0
-      });
+    if (!container.running) {
+      container.start({ image: container.images.sandbox, enableInternet: false });
     }
 
-    // Work with files
-    if (url.pathname === '/file') {
-      await sandbox.writeFile('/workspace/hello.txt', 'Hello, Sandbox!');
-      const file = await sandbox.readFile('/workspace/hello.txt');
-      return Response.json({ content: file.content });
-    }
+    const files = new Files(container);
+    await files.writeFile("/workspace/task.sh", script);
 
-    return new Response('Try /run or /file');
+    const process = await container.exec(["sh", "task.sh"], { cwd: "/workspace" });
+    const { exitCode, stdout } = await process.output();
+    return { exitCode, stdout: new TextDecoder().decode(stdout) };
   }
-};
-```
-
-## Process Execution
-
-A Sandbox is the long-running computer. `exec()` launches one supervised argv process and returns after the runtime confirms launch; it does not run through a hidden persistent shell.
-
-```ts
-const process = await sandbox.exec(['python3', '-c', 'print(2 + 2)']);
-const output = await process.output({ encoding: 'utf8' });
-
-console.log(process.id, process.pid, output.stdout, output.exitCode);
-```
-
-`await sandbox.exec(argv)` waits only for launch; `process.pid` is available once it resolves. `await process.output()` and `await process.waitForExit()` wait for completion. `process.status()` observes the current state, and `process.logs()` streams replayable cursor events incrementally.
-
-`output()` is replayable but may return `truncated: true`; use `logs({ since, replay, follow })` for cursor resume and output too large to buffer. `exec(argv, { timeout })` sets a remote process lifetime deadline: the supervisor may terminate and then kill the process internally, and completion is reported with `timedOut: true`. Timeouts and `AbortSignal`s on `logs()`, `output()`, `waitForExit()`, `waitForLog()`, and `waitForPort()` cancel only that local observation—they do not stop the process. Call `process.kill(signal)` with a numeric signal (default `15`) to request termination.
-
-Use explicit shell argv when you need shell syntax:
+}
 
-```ts
-const proc = await sandbox.exec(['/bin/bash', '-lc', 'cd app && npm test'], {
-  cwd: '/workspace',
-  env: { CI: '1' }
-});
-```
-
-For asynchronous work, keep `proc.id` and recover the live process from a later Worker request:
-
-```ts
-const server = await sandbox.exec([
-  '/bin/bash',
-  '-lc',
-  'npm run dev -- --host 0.0.0.0'
-]);
-await server.waitForPort(3000);
-
-const recovered = await sandbox.getProcess(server.id);
-const running = await sandbox.listProcesses();
-```
-
-`getProcess()` and `listProcesses()` are non-waking discovery calls: with no active runtime they return `null` and `[]` instead of starting a replacement. Handles, IDs, PIDs, statuses, retained logs, and cursors belong to the runtime that launched the process. After sleep, restart, or replacement, discovery cannot recover them and operations on an old handle fail with `STALE_PROCESS_HANDLE` rather than targeting a replacement runtime.
-
-Use `createTerminal()` for a persistent interactive PTY shell with input, resize, interrupt, terminate, and reconnect semantics. Terminals remain separate from supervised processes and are also runtime-local.
-
-## Quick tunnels
-
-`sandbox.tunnels.get(port)` exposes a service running inside the
-sandbox on a `*.trycloudflare.com` URL. No Cloudflare account or DNS
-setup required — cloudflared opens a persistent QUIC connection to
-Cloudflare's edge and Cloudflare hands back a hostname.
-
-```ts
-// Inside a Worker with a sandbox:
-const tunnel = await sandbox.tunnels.get(8080);
-console.log(tunnel.url);
-// → https://random-words-here.trycloudflare.com
-
-// Repeated calls for the same port return the same record:
-const same = await sandbox.tunnels.get(8080);
-console.log(same.url === tunnel.url); // true
-
-// Tear down by port number or by the record:
-await sandbox.tunnels.destroy(8080);
-// or: await sandbox.tunnels.destroy(tunnel);
+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>;
 ```
 
-`get()` is idempotent: it consults a per-sandbox cache in Durable
-Object storage, returns the cached record on a hit, and only spawns a
-fresh cloudflared process on a miss. `list()` returns every cached
-tunnel.
+The image needs the helper that `Files` runs, and the Worker needs `nodejs_compat`. Refer to [Requirements](https://developers.cloudflare.com/sandbox/reference/#requirements).
 
-Notes:
+## What you can build
 
-- URLs do **not** survive a container restart. Cloudflare assigns the
-  hostname during cloudflared's startup handshake, so every restart
-  yields a new URL. The SDK clears its cache on container start, so
-  the next `get(port)` after a restart returns a fresh record.
-- The first fetch through a brand-new URL can take a couple of
-  seconds while DNS propagates, even after `get()` resolves.
-- `*.trycloudflare.com` buffers `text/event-stream` responses.
-  WebSockets work fine.
-- Local builds behind a TLS-intercepting proxy (e.g. Cloudflare WARP)
-  need the host CA bundle injected at build time — see
-  [DOCKER_README.md](../../DOCKER_README.md).
+| Goal                                   | Guide                                                                                                                              | Example                                                                                                  |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Run a script and read its output       | [Execute commands](https://developers.cloudflare.com/sandbox/commands/execute-commands/)                                           | [`workspace`](examples/workspace)                                                                        |
+| Keep a server or build running         | [Run background processes](https://developers.cloudflare.com/sandbox/commands/run-background-processes/)                           | [`process-workspace`](examples/process-workspace)                                                        |
+| Open a shell in the browser            | [Open a terminal in the browser](https://developers.cloudflare.com/sandbox/commands/open-a-terminal-in-the-browser/)               | [`terminal-workspace`](examples/terminal-workspace)                                                      |
+| Process files from a bucket            | [Mount an R2 bucket](https://developers.cloudflare.com/sandbox/files/mount-an-r2-bucket/)                                          | [`artifact-workspace`](examples/artifact-workspace)                                                      |
+| Save a workspace and resume it later   | [Save and restore a sandbox](https://developers.cloudflare.com/sandbox/files/save-and-restore-a-workspace/)                        | [`checkpoint-workspace`](examples/checkpoint-workspace), [`backup-workspace`](examples/backup-workspace) |
+| Preview a web app while you edit it    | [Preview a web application](https://developers.cloudflare.com/sandbox/previews/preview-a-web-application/)                         | [`preview-workspace`](examples/preview-workspace)                                                        |
+| Share a port on its own URL            | [Serve previews on their own hostnames](https://developers.cloudflare.com/sandbox/previews/serve-previews-on-their-own-hostnames/) | [`share-workspace`](examples/share-workspace)                                                            |
+| Choose which hosts a sandbox can reach | [Control network access](https://developers.cloudflare.com/sandbox/network/)                                                       | [`outbound-workspace`](examples/outbound-workspace)                                                      |
+| Run a coding agent on a repository     | [Coding agents](https://developers.cloudflare.com/sandbox/coding-agents/)                                                          | [`coding-agents`](examples/coding-agents), [`devin`](devin), [`openai/agents-api`](openai/agents-api)    |
 
-## Documentation
+To run JavaScript or Python without a Linux environment, use [Dynamic Workers](https://developers.cloudflare.com/sandbox/choose-an-environment/) instead.
 
-**📖 [Full Documentation](https://developers.cloudflare.com/sandbox/)**
+## Coming from 0.x
 
-- [Get Started Guide](https://developers.cloudflare.com/sandbox/get-started/) - Step-by-step tutorial
-- [API Reference](https://developers.cloudflare.com/sandbox/api/) - Complete API docs
-- [Guides](https://developers.cloudflare.com/sandbox/guides/) - Execute commands, manage files, expose services
-- [Examples](https://developers.cloudflare.com/sandbox/tutorials/) - AI agents, data analysis, CI/CD pipelines
+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](https://developers.cloudflare.com/sandbox/sdk/migrate/) maps each 0.x API to its replacement. The 0.x source is on the [`v0`](https://github.com/cloudflare/sandbox-sdk/tree/v0) branch.
 
-## Key Features
+## Repository
 
-- **Secure Isolation** - Each sandbox runs in its own container
-- **Edge-Native** - Runs on Cloudflare's global network
-- **Code Interpreter** - Execute Python and JavaScript with rich outputs
-- **File System Access** - Read, write, and manage files
-- **Command Execution** - Run any command with streaming support
-- **Preview URLs** - Expose services with public URLs
-- **Quick tunnels** - Zero-config `*.trycloudflare.com` URLs via `sandbox.tunnels.get(port)`
-- **Git Integration** - Clone repositories directly
+| Path                                           | Contents                                                                              |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------- |
+| [`packages/sandbox`](packages/sandbox)         | The `@cloudflare/sandbox` package                                                     |
+| [`crates/sandbox-tools`](crates/sandbox-tools) | `sandbox-shim`, the Linux helper that `Files`, `S3Mounts`, and `DirectoryBackups` run |
+| [`images/sandbox-tools`](images/sandbox-tools) | The `cloudflare/sandbox` image that ships `sandbox-shim`                              |
+| [`examples`](examples)                         | Deployable Workers, one per goal                                                      |
 
-## Contributing
+To learn how these parts fit together, read [Architecture](docs/architecture.md). The package and `sandbox-shim` exchange frames described in [Shim protocol](docs/shim-protocol.md). [S3 mounts design](docs/s3-mounts-design.md) explains `S3Mounts` and `S3Gateway`. To add an example, read [Examples](docs/examples.md).
 
-We welcome contributions from the community! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on:
+Build and test with Node.js and Docker:
 
-- Setting up your development environment
-- Creating pull requests
-- Code style and testing requirements
-
-## Development
-
-This repository contains the SDK source code. Quick start:
-
-```bash
-# Clone the repo
-git clone https://github.com/cloudflare/sandbox-sdk
-cd sandbox-sdk
-
-# Install dependencies
+```sh
 npm install
-
-# Run tests
-npm test
-
-# Build the project
-npm run build
-
-# Type checking and linting
 npm run check
+npm test
 ```
 
-## Examples
-
-See the [examples directory](./examples) for complete working examples:
-
-- [Minimal](./examples/minimal) - Start here: exec commands, read/write files
-- [Code Interpreter](./examples/code-interpreter) - Give [gpt-oss](https://developers.cloudflare.com/workers-ai/models/gpt-oss-120b/) on Workers AI a Python REPL
-- [Claude Code](./examples/claude-code) - Run [Claude Code](https://claude.ai/code) headless on any repo
-- [OpenAI Agents](./examples/openai-agents) - `Shell` and `Editor` tools for [OpenAI Agents SDK](https://openai.github.io/openai-agents-js/)
-- [OpenCode](./examples/opencode) - [OpenCode](https://github.com/sst/opencode) web UI or [SDK](https://opencode.ai/docs/sdk/) in a sandbox
-- [Git Repo Per Sandbox](./examples/git-repo-per-sandbox) - One Artifacts Git repo per sandbox
-- [TypeScript Validator](./examples/typescript-validator) - Build with npm in sandbox, execute in [isolates](https://developers.cloudflare.com/workers/runtime-apis/bindings/worker-loader/)
-
-## Status
-
-**Beta** - The SDK is in active development. APIs may change before v1.0.
+[Testing](docs/testing.md) explains what these commands check, how to build behind a TLS-inspecting proxy, and how to test in production. [Releasing](docs/releasing.md) explains how maintainers publish the package and its image.
 
 ## License
 
 [Apache License 2.0](LICENSE)
-
-## Links
-
-- [Documentation](https://developers.cloudflare.com/sandbox/)
-- [GitHub Issues](https://github.com/cloudflare/sandbox-sdk/issues)
-- [Developer Discord](https://discord.cloudflare.com)
-- [Cloudflare Developers](https://twitter.com/CloudflareDev)