diff --git a/packages/projects-docs/pages/sdk/_meta.json b/packages/projects-docs/pages/sdk/_meta.json index 3bccad91..b05b5469 100644 --- a/packages/projects-docs/pages/sdk/_meta.json +++ b/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", diff --git a/packages/projects-docs/pages/sdk/migration-guide.mdx b/packages/projects-docs/pages/sdk/migration-guide.mdx new file mode 100644 index 00000000..1ac6e952 --- /dev/null +++ b/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. + + +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. + + +## 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'); +``` + + +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. + + +## 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) | + + +`snapshots.create` is **not idempotent** — exclude it from any retry logic. Context builds also require local Docker in the TS SDK. + + +## Need help? + +If you run into issues during migration, contact us at [support@codesandbox.io](mailto:support@codesandbox.io).