diff --git a/public/__redirects b/public/__redirects index 91e2221ce3d..3486041b637 100644 --- a/public/__redirects +++ b/public/__redirects @@ -624,6 +624,8 @@ # Sandbox /sandbox/platform/beta-info/ /sandbox/platform/ 301 /sandbox/guides/openai-agents-sdk/ /sandbox/tutorials/openai-agents/ 301 +/sandbox/guides/2026-deprecation/ /sandbox/guides/migrating-to-1-0/ 301 +/sandbox/guides/2026-deprecation/SKILL.md /sandbox/guides/migrating-to-1-0/SKILL.md 301 # D1 /d1/client-api/ /d1/worker-api/ 301 /d1/build-with-d1/d1-client-api/ /d1/worker-api/ 301 diff --git a/public/sandbox/guides/2026-deprecation/SKILL.md b/public/sandbox/guides/2026-deprecation/SKILL.md deleted file mode 100644 index d949ad1afb2..00000000000 --- a/public/sandbox/guides/2026-deprecation/SKILL.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -name: sandbox-2026-deprecation -description: Migrate Cloudflare Sandbox SDK codebases away from features deprecated in June 2026 (HTTP and WebSocket transports, desktop, exposePort, default sessions, and stream-specific file and command APIs). ---- - -# Sandbox SDK 2026 deprecation migration - -Use this skill when migrating a codebase that depends on the Cloudflare Sandbox SDK away from features deprecated in June 2026. - -For the announcement, refer to the [changelog entry](https://developers.cloudflare.com/changelog/sandbox/2026-06-09-deprecating-sandbox-sdk-features/). For detailed documentation, refer to the [migration guide](https://developers.cloudflare.com/sandbox/guides/2026-deprecation/). - -## Migration checklist - -1. Update `@cloudflare/sandbox` and the sandbox container image before changing runtime configuration. -2. Search the codebase for deprecated configuration and APIs: - - ```sh - rg 'SANDBOX_TRANSPORT|transport:|exposePort\(|enableDefaultSession|execStream\(|readFileStream|writeFileStream' - ``` - -3. Switch every sandbox to RPC transport with `SANDBOX_TRANSPORT=rpc` or `getSandbox(..., { transport: "rpc" })`. -4. Replace Sandbox SDK desktop APIs with Cloudflare Browser Run where browser automation is required. -5. Replace `exposePort()` with `sandbox.tunnels.get()`. Use quick tunnels for development and named tunnels for stable production hostnames. -6. Set `enableDefaultSession: false` on `getSandbox()`. -7. Replace workflows that depend on persisted shell state with explicit sessions from `sandbox.createSession()`. -8. Move stream-specific file and command logic to the base `readFile()`, `writeFile()`, and `exec()` APIs where streaming behavior is supported. -9. Deploy the Worker and smoke-test command execution, file operations, public URLs, and stateful session workflows. - -## API replacements - -| Deprecated feature | Replacement | -| ---------------------------------------- | ---------------------------------------------------- | -| HTTP or WebSocket transport | RPC transport | -| Sandbox SDK desktop | Cloudflare Browser Run | -| `exposePort()` | `sandbox.tunnels.get()` | -| Default sessions | `enableDefaultSession: false` with explicit sessions | -| Stream-specific command and file helpers | Base command and file APIs with streaming support | - -## Notes for agents - -- Do not remove `exposePort()` blindly if the Worker uses `proxyToSandbox()` to inject authentication or rewrite responses. Preserve that behavior before moving traffic to tunnels. -- If code relies on `cd` carrying across separate `exec()` calls, create an explicit session with `cwd` instead. -- Tunnels require RPC transport. Configure RPC before migrating public URLs. -- Large or binary file streaming requires RPC transport. diff --git a/public/sandbox/guides/migrating-to-1-0/SKILL.md b/public/sandbox/guides/migrating-to-1-0/SKILL.md new file mode 100644 index 00000000000..ece13d4bb6d --- /dev/null +++ b/public/sandbox/guides/migrating-to-1-0/SKILL.md @@ -0,0 +1,158 @@ +--- +name: sandbox-migrating-to-1-0 +description: Migrate Cloudflare Sandbox SDK projects to @cloudflare/sandbox@next and update deprecated transports, execution APIs, sessions, plugins, and extensions. +--- + +# Sandbox SDK 1.0 migration + +Use this skill when migrating a codebase from the current `@cloudflare/sandbox` release to the `1.0` preview, published on the `@cloudflare/sandbox@next` npm tag. + +Existing projects should migrate as soon as possible. New projects should install `@cloudflare/sandbox@next` today. + +For the full guide, refer to [Migrate to Sandbox SDK 1.0](https://developers.cloudflare.com/sandbox/guides/migrating-to-1-0/). + +## Install the 1.0 preview + +Install the `1.0` preview: + +```sh +npm install @cloudflare/sandbox@next +``` + +Deploy Worker code and the container image together when the migration changes behavior across the SDK and runtime. + +## Scan the codebase + +Search for these legacy APIs and configuration values: + +- `SANDBOX_TRANSPORT` +- `transport: "http"` +- `transport: "websocket"` +- `execStream(` +- `startProcess(` +- `enableDefaultSession` +- `createCodeContext(` +- `runCode(` +- `gitCheckout(` +- `terminal(` +- `@cloudflare/sandbox/xterm` + +## Migration checklist + +### HTTP and WebSocket transports + +HTTP and WebSocket transports are removed in `1.0`. RPC is the supported transport path. + +Before installing the `1.0` preview, test the project with `SANDBOX_TRANSPORT=rpc`. Remove code that forces `transport: "http"` or `transport: "websocket"`. + +### Execution APIs + +`exec()`, `execStream()`, and `startProcess()` are being consolidated into one `exec()` API that mirrors the Containers `container.exec()` model. + +Use this migration map: + +| Current API | Next API | Notes | +| ------------------------------- | ---------------------------------------- | ------------------------------- | +| `sandbox.exec(command)` | `sandbox.exec(...)` | Use for one-shot commands. | +| `sandbox.execStream(command)` | `sandbox.exec(...)` with streamed output | Use process stream APIs. | +| `sandbox.startProcess(command)` | `sandbox.exec(...)` process handle | Use for long-running processes. | + +Confirm the final Sandbox SDK `exec()` TypeScript interface against the installed `1.0` preview package before rewriting production code. + +### Default sessions + +Hidden default sessions are removed in `1.0`. The `enableDefaultSession` flag is removed from `getSandbox()`. + +Remove `enableDefaultSession`: + +```ts +const sandbox = getSandbox(env.Sandbox, "my-sandbox"); +``` + +Use explicit sessions when shell state must persist: + +```ts +const session = await sandbox.createSession(); +await session.exec("cd /workspace/app"); +await session.exec("pwd"); +``` + +### Plugins + +Code Interpreter, Git, and PTY support move from the core SDK into plugins. + +Plugins follow this pattern: + +```ts +import { Sandbox } from "@cloudflare/sandbox"; +import { withFeature } from "@cloudflare/sandbox/"; + +export class MySandbox extends Sandbox { + feature = withFeature(this); +} +``` + +The public interfaces should remain the same, but they are namespaced on the sandbox instance through the plugin. + +Expected migration patterns: + +```ts +import { withCodeInterpreter } from "@cloudflare/sandbox/code-interpreter"; + +export class MySandbox extends Sandbox { + codeInterpreter = withCodeInterpreter(this); +} + +await sandbox.codeInterpreter.runCode("1 + 1"); +``` + +```ts +import { withGit } from "@cloudflare/sandbox/git"; + +export class MySandbox extends Sandbox { + git = withGit(this); +} + +await sandbox.git.gitCheckout("https://github.com/user/repo"); +``` + +```ts +import { withPty } from "@cloudflare/sandbox/pty"; + +export class MySandbox extends Sandbox { + pty = withPty(this); +} + +return await sandbox.pty.terminal(request); +``` + +Confirm plugin identifiers and helper names against the installed `1.0` preview package before rewriting production code. + +### Extension API + +Use the new extension API when you want to attach reusable methods, state, or lifecycle behavior to a Sandbox instance. + +Extensions use the same attachment model as plugins: + +```ts +import { withMyExtension } from "@cloudflare/sandbox/my-extension"; + +export class MySandbox extends Sandbox { + myExtension = withMyExtension(this); +} + +await sandbox.myExtension.doWork(); +``` + +Confirm the final extension authoring interface against the installed `1.0` preview package before publishing custom extensions. + +## Verification + +After migrating: + +1. Confirm `@cloudflare/sandbox` resolves to the `1.0` preview release. +2. Deploy the Worker and container image together. +3. Run one top-level `exec()` call. +4. Test workflows that previously used default sessions. +5. Test Code Interpreter, Git, and PTY plugin calls. +6. Run the project integration tests. diff --git a/src/content/changelog/sandbox/2026-07-01-announcing-sandbox-sdk-1-0-preview.mdx b/src/content/changelog/sandbox/2026-07-01-announcing-sandbox-sdk-1-0-preview.mdx new file mode 100644 index 00000000000..86828ba099f --- /dev/null +++ b/src/content/changelog/sandbox/2026-07-01-announcing-sandbox-sdk-1-0-preview.mdx @@ -0,0 +1,27 @@ +--- +title: Announcing the Sandbox SDK 1.0 preview +description: A new preview package introduces a consolidated exec() command interface and an extensions API ahead of the 1.0.0 release. +products: + - sandbox +date: 2026-07-01 +publish_future_dated_entry: true +--- + +import { PackageManagers } from "~/components"; + +Following on from our [recent deprecation announcement](/changelog/post/2026-06-09-deprecating-sandbox-sdk-features/), we are announcing a new preview package that contains the replacement APIs. + +Install the `1.0` preview with: + + + +The preview includes: + +- A revised command interface that consolidates `exec()`, `execStream()`, and `startProcess()` into a single `exec()` function, aligning with the Containers `container.exec()` model. +- A new extensions API for adding reusable Sandbox capabilities outside the core SDK, including the Code Interpreter, Git, and PTY features that are moving into plugins. + +We are aiming to ship this preview as `1.0.0` on July 31, 2026. + +To get started, refer to [Migrate to Sandbox SDK 1.0](/sandbox/guides/migrating-to-1-0/). We also provide an [agent skill](/sandbox/guides/migrating-to-1-0/SKILL.md) to help with the migration. + +For any questions, ask in the [Cloudflare Developers Discord](https://discord.gg/cloudflaredev). diff --git a/src/content/docs/sandbox/api/commands.mdx b/src/content/docs/sandbox/api/commands.mdx index 9c2cd3155ce..d39239b1a43 100644 --- a/src/content/docs/sandbox/api/commands.mdx +++ b/src/content/docs/sandbox/api/commands.mdx @@ -12,6 +12,10 @@ import { Details, TypeScriptExample } from "~/components"; Execute commands and manage background processes in the sandbox's isolated container environment. +:::note[Sandbox SDK 1.0] +In `@cloudflare/sandbox@next`, `exec()`, `execStream()`, and `startProcess()` are consolidated into a single `exec()` API. For more information, refer to [Migrate to Sandbox SDK 1.0](/sandbox/guides/migrating-to-1-0/). +::: + ## Methods ### `exec()` diff --git a/src/content/docs/sandbox/api/interpreter.mdx b/src/content/docs/sandbox/api/interpreter.mdx index 704dc22ec5a..546d058c42c 100644 --- a/src/content/docs/sandbox/api/interpreter.mdx +++ b/src/content/docs/sandbox/api/interpreter.mdx @@ -12,6 +12,10 @@ import { TypeScriptExample } from "~/components"; Execute Python, JavaScript, and TypeScript code with support for data visualizations, tables, and rich output formats. Contexts maintain state (variables, imports, functions) across executions. +:::note[Sandbox SDK 1.0] +In `@cloudflare/sandbox@next`, Code Interpreter moves from the core SDK into a plugin. The public interface remains available through a plugin namespace. For more information, refer to [Migrate to Sandbox SDK 1.0](/sandbox/guides/migrating-to-1-0/). +::: + ## Methods ### `createCodeContext()` diff --git a/src/content/docs/sandbox/api/sessions.mdx b/src/content/docs/sandbox/api/sessions.mdx index 2fbbbfcacfb..4c274c71851 100644 --- a/src/content/docs/sandbox/api/sessions.mdx +++ b/src/content/docs/sandbox/api/sessions.mdx @@ -16,6 +16,10 @@ Create shell sessions within a sandbox. Each session maintains its own shell sta By default, for backwards compatibility, every sandbox has a default session that maintains shell state. It is recommended to set `enableDefaultSession` to `false` on `getSandbox()` so operations without an explicit `sessionId` run in isolation. Create additional sessions for separate workflows inside the same user workspace, such as development and runtime processes using the `createSession()` method. Use separate sandboxes for separate users. For sandbox-level operations like creating containers or destroying the entire sandbox, refer to the [Lifecycle API](/sandbox/api/lifecycle/). ::: +:::note[Sandbox SDK 1.0] +In `@cloudflare/sandbox@next`, hidden default sessions and the `enableDefaultSession` flag are removed. Top-level operations run sessionlessly by default. Use the `createSession()` method when shell state must persist across calls. For more information, refer to [Migrate to Sandbox SDK 1.0](/sandbox/guides/migrating-to-1-0/). +::: + ## Methods ### `createSession()` diff --git a/src/content/docs/sandbox/api/terminal.mdx b/src/content/docs/sandbox/api/terminal.mdx index 1831f840429..c271455fbd5 100644 --- a/src/content/docs/sandbox/api/terminal.mdx +++ b/src/content/docs/sandbox/api/terminal.mdx @@ -12,6 +12,10 @@ import { TypeScriptExample } from "~/components"; Connect browser-based terminal UIs to sandbox shells via WebSocket. The server-side `terminal()` method proxies WebSocket connections to the container, and the client-side `SandboxAddon` integrates with xterm.js for terminal rendering. +:::note[Sandbox SDK 1.0] +In `@cloudflare/sandbox@next`, PTY support moves from the core SDK into a plugin. The public interface remains available through a plugin namespace. For more information, refer to [Migrate to Sandbox SDK 1.0](/sandbox/guides/migrating-to-1-0/). +::: + ## Server-side methods ### `terminal()` diff --git a/src/content/docs/sandbox/concepts/sessions.mdx b/src/content/docs/sandbox/concepts/sessions.mdx index 2372c475293..b5ea2ba21bf 100644 --- a/src/content/docs/sandbox/concepts/sessions.mdx +++ b/src/content/docs/sandbox/concepts/sessions.mdx @@ -15,6 +15,10 @@ Sessions are bash shell execution contexts within a sandbox. Think of them as te Sessions are useful for organizing work inside one sandbox. They are not a security boundary between users because sessions share the same filesystem and process space. +:::note[Sandbox SDK 1.0] +In `@cloudflare/sandbox@next`, hidden default sessions and the `enableDefaultSession` flag are removed. Top-level operations run sessionlessly by default. Use explicit sessions when shell state must persist. For more information, refer to [Migrate to Sandbox SDK 1.0](/sandbox/guides/migrating-to-1-0/). +::: + ## Default session By default, every sandbox has a default session that maintains shell state between commands while the container is active: diff --git a/src/content/docs/sandbox/concepts/terminal.mdx b/src/content/docs/sandbox/concepts/terminal.mdx index 06601ad70ff..abc5c4593b8 100644 --- a/src/content/docs/sandbox/concepts/terminal.mdx +++ b/src/content/docs/sandbox/concepts/terminal.mdx @@ -10,6 +10,10 @@ products: Terminal connections let browser-based UIs interact directly with sandbox shells. Instead of executing discrete commands with `exec()`, a terminal connection opens a persistent, bidirectional channel to a bash shell — the same model as SSH or a local terminal emulator. +:::note[Sandbox SDK 1.0] +In `@cloudflare/sandbox@next`, PTY support moves from the core SDK into a plugin. For more information, refer to [Migrate to Sandbox SDK 1.0](/sandbox/guides/migrating-to-1-0/). +::: + ## How terminal connections work Terminal connections use WebSockets to stream raw bytes between a browser terminal (like [xterm.js](https://xtermjs.org/)) and a pseudo-terminal (PTY) process running inside the sandbox container. diff --git a/src/content/docs/sandbox/configuration/sandbox-options.mdx b/src/content/docs/sandbox/configuration/sandbox-options.mdx index 0d7a65741da..392c739f3cb 100644 --- a/src/content/docs/sandbox/configuration/sandbox-options.mdx +++ b/src/content/docs/sandbox/configuration/sandbox-options.mdx @@ -12,6 +12,10 @@ import { TypeScriptExample, WranglerConfig } from "~/components"; Configure sandbox behavior by passing options when creating a sandbox instance with `getSandbox()`. +:::note[Sandbox SDK 1.0] +The `enableDefaultSession` option is removed in `@cloudflare/sandbox@next`. Top-level operations run sessionlessly by default. For more information, refer to [Migrate to Sandbox SDK 1.0](/sandbox/guides/migrating-to-1-0/). +::: + ## Available options ```ts diff --git a/src/content/docs/sandbox/configuration/transport.mdx b/src/content/docs/sandbox/configuration/transport.mdx index dce27bacce1..c090f660d44 100644 --- a/src/content/docs/sandbox/configuration/transport.mdx +++ b/src/content/docs/sandbox/configuration/transport.mdx @@ -14,6 +14,10 @@ import { WranglerConfig } from "~/components"; Configure how the Sandbox SDK communicates with containers using transport modes. +:::note[Sandbox SDK 1.0] +HTTP and WebSocket transports are removed in `@cloudflare/sandbox@next`. Move existing projects to RPC before migrating. For more information, refer to [Migrate to Sandbox SDK 1.0](/sandbox/guides/migrating-to-1-0/). +::: + ## Overview The Sandbox SDK supports three transport modes for communication between the Durable Object and the container: diff --git a/src/content/docs/sandbox/guides/2026-deprecation.mdx b/src/content/docs/sandbox/guides/2026-deprecation.mdx deleted file mode 100644 index e4bf658c9b4..00000000000 --- a/src/content/docs/sandbox/guides/2026-deprecation.mdx +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: 2026 deprecation migration guide -pcx_content_type: how-to -sidebar: - order: 99 -description: Migrate away from Sandbox SDK features deprecated in June 2026. -products: - - sandbox ---- - -import { WranglerConfig } from "~/components"; - -This guide walks through migrating away from the Sandbox SDK features deprecated in June 2026. These features will no longer be present in future Sandbox SDK versions after July 9, 2026. - -For the announcement and rationale, refer to the [deprecation changelog entry](/changelog/sandbox/2026-06-09-deprecating-sandbox-sdk-features/). - -## Before you migrate - -Update to the latest Sandbox SDK release before changing transport or session configuration. If your project uses a version earlier than `0.9.1`, deploy the newer `@cloudflare/sandbox` package and container image before switching to RPC transport. - -Search your codebase for deprecated configuration and APIs: - -```sh -rg 'SANDBOX_TRANSPORT|transport:|exposePort\(|enableDefaultSession|execStream\(|readFileStream|writeFileStream' -``` - -Also review any code that uses stream-specific file helpers or depends on shell state carrying across separate `exec()` calls. - -## HTTP and WebSocket transports - -HTTP and WebSocket transports will no longer be present in Sandbox SDK versions released after July 9, 2026. Switch to the RPC transport before that date. - -To configure RPC transport for every sandbox in your Worker, set `SANDBOX_TRANSPORT` in your Worker's configuration: - - -```jsonc -{ - "vars": { - "SANDBOX_TRANSPORT": "rpc" - } -} -``` - - -To configure RPC transport for a specific sandbox, pass `transport: "rpc"` to `getSandbox()`: - -```ts -import { getSandbox } from "@cloudflare/sandbox"; - -const sandbox = getSandbox(env.Sandbox, "user-123", { - transport: "rpc", -}); -``` - -For more information, refer to [Transport modes](/sandbox/configuration/transport/). - -## Desktop - -The desktop feature was removed in `0.10.2`. If your application used Sandbox SDK desktop APIs for browser automation, move that browser automation to [Cloudflare Browser Run](/browser-run/). - -Keep Sandbox SDK for isolated command execution, file operations, and runtime workflows that do not require a full remote browser environment. - -## Expose ports - -Replace `exposePort()` with the tunnels API for public URLs. The tunnels API requires RPC transport. - -Use quick tunnels for development, demos, and short-lived URLs. Use named tunnels for production traffic, webhook receivers, OAuth callbacks, and stable hostnames on a zone you control. - -```ts -import { getSandbox } from "@cloudflare/sandbox"; - -const sandbox = getSandbox(env.Sandbox, "my-sandbox", { - transport: "rpc", -}); - -const server = await sandbox.startProcess("python -m http.server 8080"); -await server.waitForPort(8080); - -const tunnel = await sandbox.tunnels.get(8080); -return Response.json({ url: tunnel.url }); -``` - -If your `exposePort()` flow used `proxyToSandbox()` to inject authentication or rewrite responses, account for that behavior before moving the public URL to a tunnel. - -For more information, refer to [Tunnels](/sandbox/api/tunnels/) and [Expose services](/sandbox/guides/expose-services/). - -## Default sessions - -Set `enableDefaultSession: false` on `getSandbox()`. Operations without an explicit session will then run in isolation and will not inherit shell state from earlier calls. - -```ts -import { getSandbox } from "@cloudflare/sandbox"; - -const sandbox = getSandbox(env.Sandbox, "user-123", { - enableDefaultSession: false, - transport: "rpc", -}); -``` - -If your code expects commands like `cd /workspace/app` to affect later `exec()` calls, create an explicit session and run related commands through that session: - -```ts -const buildSession = await sandbox.createSession({ - id: "build", - cwd: "/workspace/app", -}); - -await buildSession.exec("npm install"); -await buildSession.exec("npm test"); -``` - -For one-off commands, pass `cwd` or `env` directly to `exec()` instead of relying on persisted shell state: - -```ts -await sandbox.exec("npm test", { - cwd: "/workspace/app", - env: { - NODE_ENV: "test", - }, -}); -``` - -For more information, refer to [Sandbox options](/sandbox/configuration/sandbox-options/#enabledefaultsession) and [Sessions](/sandbox/api/sessions/). - -## Streaming APIs - -The Sandbox SDK is consolidating separate streaming APIs into the base `exec()`, `readFile()`, and `writeFile()` methods. Audit code that depends on stream-specific helpers and move to the base APIs where they support streaming behavior. - -For command output, use `exec()` with streaming callbacks: - -```ts -await sandbox.exec("npm install", { - stream: true, - onOutput: (stream, data) => { - console.log(`[${stream}] ${data}`); - }, -}); -``` - -For large or binary files, use the base file APIs with RPC transport. Pass a `ReadableStream` to `writeFile()`, or read a file as a stream with `encoding: "none"`: - -```ts -const request = await fetch("https://example.com/archive.tar.gz"); - -if (!request.body) { - throw new Error("Expected archive response body"); -} - -await sandbox.writeFile("/workspace/archive.tar.gz", request.body); - -const file = await sandbox.readFile("/workspace/archive.tar.gz", { - encoding: "none", -}); - -return new Response(file.content, { - headers: { "Content-Type": file.mimeType }, -}); -``` - -For more information, refer to [Commands](/sandbox/api/commands/) and [Files](/sandbox/api/files/). - -## Verify the migration - -Use this checklist before upgrading to a Sandbox SDK version released after July 9, 2026: - -- RPC transport is configured with `SANDBOX_TRANSPORT=rpc` or `transport: "rpc"`. -- No `websocket` or `http` transport configuration remains. -- No `exposePort()` usage remains in the migrated path. -- `enableDefaultSession` is set to `false`. -- Stateful command workflows use `sandbox.createSession()`. -- One-off commands pass `cwd` and `env` directly. -- Streaming file and command code uses the base APIs. -- Your Worker has been deployed and smoke-tested. - -## Agent skill - -An agent skill is available to assist with the migration: [SKILL.md](/sandbox/guides/2026-deprecation/SKILL.md). diff --git a/src/content/docs/sandbox/guides/code-execution.mdx b/src/content/docs/sandbox/guides/code-execution.mdx index 5d3cad4a3b5..853a9d34690 100644 --- a/src/content/docs/sandbox/guides/code-execution.mdx +++ b/src/content/docs/sandbox/guides/code-execution.mdx @@ -12,6 +12,10 @@ import { TypeScriptExample } from "~/components"; This guide shows you how to execute Python and JavaScript code with rich outputs using the Code Interpreter API. +:::note[Sandbox SDK 1.0] +In `@cloudflare/sandbox@next`, Code Interpreter moves from the core SDK into a plugin. For more information, refer to [Migrate to Sandbox SDK 1.0](/sandbox/guides/migrating-to-1-0/). +::: + ## When to use code interpreter Use the Code Interpreter API for **simple, direct code execution** with minimal setup: diff --git a/src/content/docs/sandbox/guides/execute-commands.mdx b/src/content/docs/sandbox/guides/execute-commands.mdx index 946ccfeabe0..50c493087b3 100644 --- a/src/content/docs/sandbox/guides/execute-commands.mdx +++ b/src/content/docs/sandbox/guides/execute-commands.mdx @@ -12,6 +12,10 @@ import { TypeScriptExample } from "~/components"; This guide shows you how to execute commands in the sandbox, handle output, and manage errors effectively. +:::note[Sandbox SDK 1.0] +In `@cloudflare/sandbox@next`, `exec()`, `execStream()`, and `startProcess()` are consolidated into a single `exec()` API. For more information, refer to [Migrate to Sandbox SDK 1.0](/sandbox/guides/migrating-to-1-0/). +::: + ## Choose the right method The SDK provides multiple approaches for running commands: diff --git a/src/content/docs/sandbox/guides/git-workflows.mdx b/src/content/docs/sandbox/guides/git-workflows.mdx index 2f15f865040..ac9bf116245 100644 --- a/src/content/docs/sandbox/guides/git-workflows.mdx +++ b/src/content/docs/sandbox/guides/git-workflows.mdx @@ -12,6 +12,10 @@ import { TypeScriptExample } from "~/components"; This guide shows you how to clone repositories, manage branches, and automate Git operations in the sandbox. +:::note[Sandbox SDK 1.0] +In `@cloudflare/sandbox@next`, Git support moves from the core SDK into a plugin. The public interface remains available through a plugin namespace. For more information, refer to [Migrate to Sandbox SDK 1.0](/sandbox/guides/migrating-to-1-0/). +::: + ## Clone repositories diff --git a/src/content/docs/sandbox/guides/migrating-to-1-0.mdx b/src/content/docs/sandbox/guides/migrating-to-1-0.mdx new file mode 100644 index 00000000000..11ba4fd29c7 --- /dev/null +++ b/src/content/docs/sandbox/guides/migrating-to-1-0.mdx @@ -0,0 +1,330 @@ +--- +title: Migrate to Sandbox SDK 1.0 +pcx_content_type: how-to +sidebar: + order: 99 +description: Migrate existing Sandbox SDK projects to the 1.0 preview and update deprecated APIs. +products: + - sandbox +--- + +import { PackageManagers, TypeScriptExample } from "~/components"; + +The Sandbox SDK `1.0` preview contains the replacement APIs for upcoming breaking changes. It is published on the `@cloudflare/sandbox@next` npm tag and is aiming to ship as `1.0.0` on July 31, 2026. Existing projects should migrate as soon as possible. New projects should install `@cloudflare/sandbox@next` today. + +The current release now marks the legacy APIs as deprecated. The `1.0` preview removes or replaces those APIs so you can test the migration before the `1.0.0` release. + +For the announcement and rationale, refer to the [Sandbox SDK deprecations changelog](/changelog/post/2026-06-09-deprecating-sandbox-sdk-features/). + +:::note[Interfaces in progress] +The `1.0` preview APIs are still stabilizing. This guide includes the migration path and the expected public interface patterns. Some interface details will be updated as the final TypeScript interfaces land. +::: + +## Install the 1.0 preview + +Install the `1.0` preview of the Sandbox SDK: + + + +Update the package in local development and in the deployment environment. If the migration changes both Worker code and container runtime behavior, deploy the Worker and container image together. + +After installing the `1.0` preview, verify the migration in a development environment: + +1. Confirm your lockfile resolves `@cloudflare/sandbox` to the `1.0` preview release. +2. Deploy the Worker and container image together. +3. Create or retrieve a sandbox instance. +4. Run one top-level `exec()` call. +5. Test each plugin or extension your application depends on. + +## Migrate deprecated features + +This section covers each legacy API surface and the migration path for the `1.0` preview. + +### HTTP and WebSocket transports + +The `1.0` preview removes HTTP and WebSocket transports. RPC is the supported transport path. + +Before installing the `1.0` preview, move your current project to RPC and test it. Set the transport variable in your Worker configuration: + +```txt +SANDBOX_TRANSPORT=rpc +``` + +If your code passes a transport option to `getSandbox()`, remove values that force HTTP or WebSocket: + + +```ts +// Before +const sandbox = getSandbox(env.Sandbox, "my-sandbox", { + transport: "websocket", +}); + +// After +const sandbox = getSandbox(env.Sandbox, "my-sandbox"); +``` + + +After installing the `1.0` preview, remove obsolete transport toggles from Worker configuration unless the `1.0` API keeps an explicit RPC setting. For more information on current transport behavior, refer to [Transport modes](/sandbox/configuration/transport/). + +### Execution API consolidation + +The `1.0` preview consolidates `exec()`, `execStream()`, and `startProcess()` into a single `exec()` API. The new API aligns with the Containers `container.exec()` model: a command starts a process, and the returned process object exposes output, streams, exit status, and process control. + +:::note[Final Sandbox signature pending] +The final Sandbox SDK `exec()` TypeScript signature is still being finalized. Use this section for the migration model, but verify the exact method signature against the `1.0` preview release before updating production code. +::: + +Use the following migration map: + +| Current API | 1.0 preview API | Notes | +| ------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------- | +| `sandbox.exec(command)` | `sandbox.exec(...)` | Use for one-shot commands. The returned process exposes output and exit status. | +| `sandbox.execStream(command)` | `sandbox.exec(...)` with streamed output | Use the process stream APIs instead of a separate streaming method. | +| `sandbox.startProcess(command)` | `sandbox.exec(...)` process handle | Use for long-running processes and process control. | + +The expected process model mirrors Containers: + + +```ts +const process = await sandbox.exec(["node", "--version"]); +const output = await process.output(); +const decoder = new TextDecoder(); + +return { + exitCode: output.exitCode, + stdout: decoder.decode(output.stdout), + stderr: decoder.decode(output.stderr), +}; +``` + + +Commands are started as an executable with arguments. Invoke a shell explicitly when you need pipes, redirects, or variable expansion: + + +```ts +await sandbox.exec(["sh", "-lc", "cd /workspace/app && npm test"]); +``` + + +Final examples for streaming output, standard input, signals, and long-running process lifecycle will be added after the Sandbox `exec()` interface lands. + +### Default sessions and `enableDefaultSession` + +The `1.0` preview removes hidden default sessions. It also removes the `enableDefaultSession` option from `getSandbox()`. + +Top-level sandbox operations are sessionless by default. They do not preserve shell state such as the current working directory or exported environment variables between calls. Create an explicit session when you need persistent shell state. + +Remove `enableDefaultSession` from `getSandbox()`: + + +```ts +// Before +const sandbox = getSandbox(env.Sandbox, "my-sandbox", { + enableDefaultSession: false, +}); + +// After +const sandbox = getSandbox(env.Sandbox, "my-sandbox"); +``` + + +Use an explicit session for stateful shell workflows: + + +```ts +const session = await sandbox.createSession(); + +await session.exec("cd /workspace/app"); +const result = await session.exec("pwd"); + +console.log(result.stdout); +``` + + +Use separate sandboxes for separate users. Use explicit sessions for separate workflows inside one user workspace. + +### Plugins for Code Interpreter, Git, and PTY support + +The `1.0` preview extracts Code Interpreter, Git, and PTY support from the core SDK into plugins. The existing public interfaces should remain the same, but they are namespaced on the sandbox instance through the plugin. + +Plugins use this pattern: + + +```ts +import { Sandbox } from "@cloudflare/sandbox"; +import { withFeature } from "@cloudflare/sandbox/"; + +export class MySandbox extends Sandbox { + feature = withFeature(this); +} +``` + + +Replace `` with the plugin import path, `feature` with the namespace you want on the sandbox instance, and `withFeature` with the matching helper exported by that plugin package. + +#### Code Interpreter plugin + +Current code uses Code Interpreter methods directly on the sandbox instance: + + +```ts +const context = await sandbox.createCodeContext({ language: "python" }); +const result = await sandbox.runCode("1 + 1", { context }); +``` + + +On the `1.0` preview, import the Code Interpreter plugin and call the same public interface through the plugin namespace: + + +```ts +import { Sandbox } from "@cloudflare/sandbox"; +import { withCodeInterpreter } from "@cloudflare/sandbox/code-interpreter"; + +export class MySandbox extends Sandbox { + codeInterpreter = withCodeInterpreter(this); +} + +const context = await sandbox.codeInterpreter.createCodeContext({ + language: "python", +}); +const result = await sandbox.codeInterpreter.runCode("1 + 1", { context }); +``` + + +#### Git plugin + +Current code uses Git methods directly on the sandbox instance: + + +```ts +await sandbox.gitCheckout("https://github.com/user/repo"); +``` + + +On the `1.0` preview, import the Git plugin and call the same public interface through the plugin namespace: + + +```ts +import { Sandbox } from "@cloudflare/sandbox"; +import { withGit } from "@cloudflare/sandbox/git"; + +export class MySandbox extends Sandbox { + git = withGit(this); +} + +await sandbox.git.gitCheckout("https://github.com/user/repo"); +``` + + +#### PTY plugin + +Current code uses terminal methods directly on the sandbox instance or on a session: + + +```ts +return await sandbox.terminal(request, { cols: 120, rows: 30 }); +``` + + +On the `1.0` preview, import the PTY plugin and call the same public interface through the plugin namespace: + + +```ts +import { Sandbox } from "@cloudflare/sandbox"; +import { withPty } from "@cloudflare/sandbox/pty"; + +export class MySandbox extends Sandbox { + pty = withPty(this); +} + +return await sandbox.pty.terminal(request, { cols: 120, rows: 30 }); +``` + + +Confirm plugin identifiers and helper names against the installed `1.0` preview package before updating production code. + +### Extension API + +The `1.0` preview introduces a Sandbox extension API. Use extensions when a capability needs to attach reusable methods, state, or lifecycle behavior to a Sandbox instance. + +Extensions follow the same attachment model as plugins: + + +```ts +import { Sandbox } from "@cloudflare/sandbox"; +import { withMyExtension } from "@cloudflare/sandbox/my-extension"; + +export class MySandbox extends Sandbox { + myExtension = withMyExtension(this); +} + +await sandbox.myExtension.doWork(); +``` + + +Use an extension when you want to: + +- Share a Sandbox capability across projects. +- Keep optional functionality out of the core SDK. +- Add methods that operate on an existing Sandbox instance. + +The final extension authoring interface will be documented when the extension framework API lands. + +## Public interfaces + +This section collects the public interfaces that affect migration. + +### `exec()` API + +The final Sandbox `exec()` signature is pending. The migration target follows this model: + + +```ts +const process = await sandbox.exec(command, options); +const output = await process.output(); + +output.exitCode; +output.stdout; +output.stderr; +``` + + +Expected behavior: + +- The command can be an executable with arguments. +- The returned process object provides complete output. +- The returned process object provides streamed output for long-running commands. +- The returned process object supports process lifecycle control. +- Shell features require an explicit shell command. + +### Plugin API pattern + +Plugins are imported from `@cloudflare/sandbox/` and attached to the Sandbox instance with `with(this)`: + + +```ts +import { Sandbox } from "@cloudflare/sandbox"; +import { withGit } from "@cloudflare/sandbox/git"; + +export class MySandbox extends Sandbox { + git = withGit(this); +} +``` + + +The plugin namespace exposes the same public methods that existed on the core sandbox instance for that feature. + +### Extension API pattern + +Extensions use the same attachment model as plugins. They should expose a namespaced API from the Sandbox instance and avoid changing core SDK behavior for applications that do not install the extension. + +## Next steps + +1. Install `@cloudflare/sandbox@next` in a development environment. +2. Remove HTTP and WebSocket transport configuration. +3. Replace default-session assumptions with explicit sessions. +4. Move Code Interpreter, Git, and PTY usage to plugins. +5. Replace `execStream()` and `startProcess()` usage after the final `exec()` interface lands. +6. Run your application's integration tests against the `1.0` preview. + +For agent-assisted migrations, use the [Sandbox SDK 1.0 migration skill](/sandbox/guides/migrating-to-1-0/SKILL.md). diff --git a/src/content/docs/sandbox/guides/streaming-output.mdx b/src/content/docs/sandbox/guides/streaming-output.mdx index d3604226427..4e1ffd23e44 100644 --- a/src/content/docs/sandbox/guides/streaming-output.mdx +++ b/src/content/docs/sandbox/guides/streaming-output.mdx @@ -12,6 +12,10 @@ import { TypeScriptExample } from "~/components"; This guide shows you how to handle real-time output from commands, processes, and code execution. +:::note[Sandbox SDK 1.0] +In `@cloudflare/sandbox@next`, streaming command output moves to the consolidated `exec()` process API. For more information, refer to [Migrate to Sandbox SDK 1.0](/sandbox/guides/migrating-to-1-0/). +::: + ## When to use streaming Use streaming when you need: diff --git a/src/content/docs/sandbox/migrating-to-1-0.mdx b/src/content/docs/sandbox/migrating-to-1-0.mdx new file mode 100644 index 00000000000..b7f5b79aba7 --- /dev/null +++ b/src/content/docs/sandbox/migrating-to-1-0.mdx @@ -0,0 +1,11 @@ +--- +title: Migrate to Sandbox SDK 1.0 +pcx_content_type: navigation +description: Migrate existing Sandbox SDK projects to the 1.0 preview and update deprecated APIs. +external_link: /sandbox/guides/migrating-to-1-0/ +sidebar: + order: 2.5 + label: Migrate to v1.0 +products: + - sandbox +---