docs(sdk): add migration guide to Together Sandbox

packages/projects-docs/pages/sdk/_meta.json

@@ -49,6 +49,7 @@
   },
   "template-library": "Template Library",
   "version-history": "Version History",
+  "migration-guide": "Migration Guide",
   "contact": {
     "title": "Contact Us",
     "href": "https://codesandbox.io/support#form",

packages/projects-docs/pages/sdk/migration-guide.mdx

@@ -0,0 +1,192 @@
+---
+title: SDK Migration Guide
+description: How to migrate off the CodeSandbox SDK — to Daytona for feature parity, or to Together Sandbox.
+---
+
+import { Callout } from 'nextra-theme-docs'
+
+# Migrate from the CodeSandbox SDK
+
+CodeSandbox is now part of Together AI, and we recommend migrating off `@codesandbox/sdk`. This guide covers two destinations:
+
+- **[Option 1 — Daytona](#option-1--daytona-recommended-for-feature-parity)** *(recommended for feature parity)*: the provider whose SDK matches the broadest set of CodeSandbox SDK capabilities — sandboxes, fork, snapshots, preview URLs with token auth, terminals, git, and code interpreters.
+- **[Option 2 — Together Sandbox](#option-2--together-sandbox)**: the Together AI sandbox SDK. It supports the core sandbox loop — create, run commands, files, snapshots, ports — with a focused API. Some CodeSandbox features aren't part of it; this guide shows which, and how to add them where you need them.
+
+<Callout>
+This guide focuses on the TypeScript SDK and CLI. If you're on the Python or Node-specific paths, the concepts map across but the exact APIs differ.
+</Callout>
+
+## Choosing a path
+
+| Your situation | Recommended path |
+| --- | --- |
+| You rely on previews/hosts, sessions, terminals, git, code interpreters, or fork | **Daytona** — these have direct equivalents |
+| You use the core loop (create, run commands, files, ports) and want to stay within Together AI | **Together Sandbox** — a focused API; add the remaining pieces where you need them |
+
+If you want the fewest changes to an existing CodeSandbox SDK integration, **Daytona** maps most closely. If you're consolidating on Together AI, **Together Sandbox** keeps everything in one account.
+
+## Option 1 — Daytona (recommended for feature parity)
+
+[Daytona](https://www.daytona.io/docs/) provides programmatic sandboxes with the closest match to the CodeSandbox SDK feature set. Almost every CodeSandbox capability has a direct equivalent.
+
+### Feature mapping
+
+| CodeSandbox SDK | Daytona |
+| --- | --- |
+| `sandboxes.create()` + `connect()` | `daytona.create()` |
+| `sandboxes.list()` / `get()` | `daytona.list()` / `daytona.get(id)` |
+| Templates / `csb build` | Snapshots + the [declarative builder](https://www.daytona.io/docs/en/declarative-builder/) |
+| `sandboxes.resume/hibernate/shutdown` | `sandbox.start()` / `archive()` / `stop()` |
+| Fork | `sandbox._experimental_fork()` |
+| `updateTier` | `sandbox.resize({ cpu, memory, disk })` |
+| `client.commands` | `sandbox.process.executeCommand()` |
+| `client.interpreters.*` | `sandbox.process.codeRun()` / `codeInterpreter` |
+| `client.fs` | `sandbox.fs` |
+| `client.terminals` (PTY) | PTY support |
+| Git integration | `sandbox.git` |
+| `ports.getPreviewUrl()` + host tokens | `sandbox.getPreviewLink(port)` / `getSignedPreviewUrl()` |
+
+### Installation & client
+
+```bash
+# Before
+npm install @codesandbox/sdk   # auth via CSB_API_KEY
+
+# After
+npm install @daytona/sdk       # auth via DAYTONA_API_KEY
+```
+
+```ts
+// Before — CodeSandbox
+import { CodeSandbox } from '@codesandbox/sdk';
+
+const sdk = new CodeSandbox();
+const sandbox = await sdk.sandboxes.create({ id: 'your-template-id' });
+const client = await sandbox.connect();
+
+const output = await client.commands.run("echo 'Hello World'");
+console.log(output);
+```
+
+```ts
+// After — Daytona
+import { Daytona } from '@daytona/sdk';
+
+const daytona = new Daytona();
+const sandbox = await daytona.create();
+
+const response = await sandbox.process.executeCommand("echo 'Hello World'");
+console.log(response.result);
+```
+
+### Previews
+
+Preview URLs and token auth map directly onto CodeSandbox hosts and host tokens, so you don't have to build a proxy.
+
+```ts
+// Before — CodeSandbox
+const url = client.hosts.getUrl(3000);
+const { token } = await sdk.hosts.createToken(sandbox.id);
+```
+
+```ts
+// After — Daytona
+// Standard preview link — token sent via header
+const preview = await sandbox.getPreviewLink(3000);
+await fetch(preview.url, { headers: { 'x-daytona-preview-token': preview.token } });
+
+// Signed preview URL — token embedded in the URL, time-limited & shareable
+const signed = await sandbox.getSignedPreviewUrl(3000, 3600);
+await fetch(signed.url);
+```
+
+### Fork & snapshots
+
+```ts
+// Fork a sandbox (filesystem + memory), like CodeSandbox fork
+const forked = await sandbox._experimental_fork({ name: 'feature-branch' });
+
+// Create a reusable snapshot, like a CodeSandbox template
+await sandbox._experimental_createSnapshot('my-snapshot');
+```
+
+<Callout>
+Daytona also provides `sandbox.git`, a stateful Python `codeInterpreter`, LSP servers (`createLspServer`), volumes, and a full CLI. See the [Daytona docs](https://www.daytona.io/docs/) for the complete API. The main concept without a one-to-one match is CodeSandbox's per-session/browser-client model — use Daytona preview tokens and your own auth for multi-user access.
+</Callout>
+
+## Option 2 — Together Sandbox
+
+[Together Sandbox](https://github.com/togethercomputer/together-sandbox) (`together-sandbox`) runs on new infrastructure. It supports the core sandbox loop — create a sandbox, run commands, read and write files, build snapshots, watch ports — through a focused API, and adds resumable SSE streaming, a typed error model, and explicit version history. The sections below cover what carries over and which CodeSandbox features you'd add yourself.
+
+Together Sandbox uses a [Together AI](https://www.together.ai) account, so your sandboxes and your model inference live with the same provider. If you're building AI agents or code-execution tools, that means one account and one API key for both running code and calling models — with access to Together AI's open-source models, fine-tuning, and dedicated inference.
+
+Sign up at [together.ai](https://www.together.ai), create an API key, and expose it as `TOGETHER_API_KEY`.
+
+### Features without a direct equivalent
+
+Some CodeSandbox capabilities aren't part of the Together Sandbox TS SDK today. If you use these, here's how to cover them.
+
+| Capability | What to do instead |
+| --- | --- |
+| **Previews / hosts** (`getPreviewUrl`, `hosts.createToken`, privacy modes, custom domains) | Together exposes port discovery (`sandbox.ports.list()`); front the ports with your own proxy for public URLs and access control. |
+| **Browser / Node clients & sessions** (`createSession`, `@codesandbox/sdk/browser`, per-session git & env, reconnect, collaboration) | `TOGETHER_API_KEY` stays server-side; route browser calls through your own backend and scope per-user access there. |
+| **Tasks** (`client.tasks`, `.codesandbox/tasks.json`) | Run dev servers / long-running processes as background `execs`. |
+| **Setup hooks** (`client.setup`, `setupTasks`) | Bake setup into the Dockerfile, or use the boot-then-hibernate `memorySnapshot` flow. |
+| **Git integration** (`connect({ git })`) | Run `git` commands via `execs` inside the sandbox. |
+| **Code interpreters** (`client.interpreters.*`) | Run `node -e` / `python -c` via `execs`. |
+| **Terminals namespace** (`client.terminals`) | Use `execs.create({ pty: true })`; no persistence (`getAll`) or resize. |
+| **OpenTelemetry tracing** (`{ tracer }`) | No equivalent. |
+| **Sandbox `list` / `get` / `listRunning`** | Track your own inventory of which sandboxes exist and are running. |
+| **TTL / idle auto-hibernate** (`hibernationTimeoutSeconds`, `automaticWakeupConfig`) | Drive hibernation from your own server. |
+| **Live tier resize** (`updateTier`), **`restart`**, **`delete`** (non-ephemeral) | Pick the size at create; shutdown + start to restart; use `ephemeral: true` to auto-delete. |
+| **`docker-compose` multi-service** | Bake services into a single image or run them as processes. |
+
+### What changes for the supported core loop
+
+Installation and auth swap the package and env var:
+
+```bash
+# Before
+npm install @codesandbox/sdk   # auth via CSB_API_KEY
+
+# After
+npm install together-sandbox   # auth via TOGETHER_API_KEY (Node 18+)
+```
+
+The main structural change is that **create and start are two steps**: `create()` makes a record (state `created`) and `start()` boots the VM and returns a connected `Sandbox`.
+
+```ts
+// Before — CodeSandbox
+const sdk = new CodeSandbox();
+const sandbox = await sdk.sandboxes.create({ id: 'your-template-id' });
+const client = await sandbox.connect();
+const output = await client.commands.run("echo 'Hello World'");
+```
+
+```ts
+// After — Together Sandbox
+import { TogetherSandbox } from 'together-sandbox';
+
+const sdk = new TogetherSandbox();
+const { id } = await sdk.sandboxes.create({ /* params */ });
+const sandbox = await sdk.sandboxes.start(id);
+const { output } = await sandbox.execs.exec('echo', ["Hello World"]);
+```
+
+The supported namespaces are renamed:
+
+| CodeSandbox | Together Sandbox |
+| --- | --- |
+| `client.commands.run()` | `sandbox.execs.exec()` (and `execs.create/list/get/streamOutput/sendStdin`) |
+| `client.fs.*` | `sandbox.files.*` / `sandbox.directories.*` |
+| `client.ports.*` | `sandbox.ports.list()` / `streamList()` (discovery only) |
+| Templates / `csb build` | `sdk.snapshots.create()` (and the `together-sandbox snapshots create` CLI) |
+| `sandbox.hibernate()` / `shutdown()` | `sandbox.hibernate()` / `shutdown()` (unchanged) |
+
+<Callout type="warning">
+`snapshots.create` is **not idempotent** — exclude it from any retry logic. Context builds also require local Docker in the TS SDK.
+</Callout>
+
+## Need help?
+
+If you run into issues during migration, contact us at [support@codesandbox.io](mailto:support@codesandbox.io).