[Sandbox] Document v1.0 migration

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

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/<plugin>";
+
+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.

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:
+
+<PackageManagers pkg="@cloudflare/sandbox@next" />
+
+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).

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()`

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()`

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()`

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()`

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:

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.

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

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: