@opencoredev/sandbox-sdk 0.2.0 → 1.0.0-beta.0

package/CHANGELOG.md

@@ -1,17 +1,38 @@
-## @opencoredev/sandbox-sdk@0.2.0
+# Changelog
 
-- Add Ascii Box and Railway Sandbox provider adapters, package exports, capabilities, examples,
-  live-test entry points, and provider documentation.
-- Normalize HTTP response status codes from provider SDK errors.
+## 1.0.0-beta.0
 
-## @opencoredev/sandbox-sdk@0.1.1
+First preview of the 1.0 rewrite, published under the `next` tag. The SDK was rewritten from scratch; most of the 0.2 surface changed. The API may still change before 1.0.0. The [upgrade guide](https://github.com/opencoredev/sandbox-sdk/blob/main/apps/docs/content/upgrade-from-0-2.mdx) maps every 0.2 call to its 1.0 form.
 
-- Add `Symbol.asyncDispose` to `Sandbox` so `await using` provides automatic cleanup.
+### Unreleased
 
-## @opencoredev/sandbox-sdk@0.1.0
+- Provider options now use `baseUrl` instead of `boxd.baseURL`, `daytona.apiUrl`, and `boat.apiUrl`; `tenki.apiKey` replaces `authToken`, and `boat.machine` replaces `type`. Old names remain deprecated aliases until 1.0.0. When both are supplied, the new name wins.
+- Added the Sandboxer provider at `@opencoredev/sandbox-sdk/sandboxer`. It shares Boat's API transport, including deferred workspace setup, and adds pause and resume, named snapshots, cookie-authenticated previews, and a `region` option (`us-east` or `eu-central`, default `SANDBOXER_REGION`, else nearest).
+- Provider option hovers document defaults and environment variables. All provider subpaths export a named provider type. Missing-credential errors explain the next step; E2B checks its key on first use and reads environment values set after factory construction.
 
-### Initial release
+### Breaking changes since 0.2.0
 
-- Run one TypeScript sandbox API across Local, E2B, Daytona, Vercel Sandbox, and Upstash Box.
-- Use normalized files, commands, processes, ports, snapshots, and provider capabilities.
-- Integrate sandbox sessions with AI SDK, Harness, Eve, and Mastra.
+- `createSandbox(provider, options?)` takes the provider as its first argument instead of `createSandbox({ provider })`. The `cwd` option is gone; every sandbox starts in `/workspace`.
+- `stop()` is split into `destroy()`, which deletes the sandbox, and `close()`, which detaches and leaves it running. `await using` calls `close()` for keyed sandboxes and `destroy()` otherwise.
+- `run` results: `success` is now `ok`, `timeout` is `timeoutMs` (default 120 s), and a timeout resolves with `timedOut: true` instead of throwing. The `{ command, args }` form is replaced by the `` box.$`...` `` tag.
+- `files.text(path)` is now `files.read(path)`; bytes come from `files.read(path, { as: "bytes" })`. `files.mkdir` is gone (`write` creates parents). `write` accepts only strings and `Uint8Array`.
+- `processes.start` is now `box.start(command, { name })`. `output()` is replaced by `lines()` and `logs()`, `kill()` by `stop()`, and process stdin writes are removed.
+- `ports.expose` is now `box.preview(port)`, which returns `url` plus any required `headers`.
+- `snapshots.*` is now `box.snapshot()` and `createSandbox(provider, { from: id })`.
+- `local()` runs a Docker container from `node:22-bookworm` instead of a bundled AgentOS VM. AgentOS moved to the optional `/agentos` entry.
+- `sandbox.raw` is now `box.native`.
+- Removed: the Ascii Box provider, the `/eve` integration, and the helpers `withSandbox`, `supports`, `requireCapability`, `capabilityMode`, `isSandboxError`, and `redactSensitive`. Use `await using`, `box.capabilities.has(...)`, and `error instanceof SandboxError`.
+- Node.js 22+ or Bun 1.3+ is required. The package is ESM only.
+
+### Highlights
+
+- Thirteen providers behind one API: E2B, Daytona, Vercel, Upstash Box (durable and ephemeral), Railway, Tenki, boxd, Freestyle, Superserve, Boat, Local (Docker), agentOS, and an in-memory fake for tests.
+- Typed capabilities: `pause`, `snapshot`, and `terminal` exist on the sandbox type only when the provider supports them. Options a provider cannot enforce fail with `unsupported` instead of being dropped.
+- Keys: `createSandbox(provider, { key })` returns the same sandbox on every call, with an optional `locator` for your own store.
+- Secrets passed as `secrets` are redacted from command output, logs, errors, and agent tool results, including after reconnecting.
+- Durable named background processes with readiness checks (`port`, `http`, or `log`) and resumable log cursors that survive a server restart.
+- Files: `edit`, `search`, `watch`, `upload`/`download`, and `mark`/`changes` diffs, plus `box.git` with token-safe `clone` and `push`.
+- Agent tools for AI SDK (`/ai`), Mastra (`/mastra`), and OpenAI Agents (`/openai`), with output budgets, a `root` path guard, and a `beforeRun` command hook.
+- `SandboxError` with 15 stable codes, a `retryable` flag, and a `hint` for every code.
+- Zero runtime dependencies. The root entry is under 8 KB minified, and provider SDKs load only on first use.
+- A shared conformance suite (`/testing`) that every adapter, including third-party ones, can run.

package/README.md

@@ -1,49 +1,374 @@
-<p align="center">
-  <img alt="Sandbox SDK with supported provider logos" src="https://raw.githubusercontent.com/opencoredev/sandbox-sdk/main/Background-with-text.png" width="820" />
-</p>
+# Sandbox SDK
 
-Run the same TypeScript sandbox code on Local, E2B, Daytona, Vercel Sandbox, Upstash Box, Ascii Box, or Railway Sandboxes.
+One TypeScript API for running code in a sandbox. The same `createSandbox`, `run`, `files`, `start`, and `preview` calls work on E2B, Daytona, Vercel, Upstash Box, Railway, Tenki, boxd, Freestyle, Superserve, Boat, Sandboxer, Docker on your machine, and an in-process fake for tests. Changing provider means changing one import.
+
+> **1.0 beta.** This is `1.0.0-beta.0` of the 1.0 rewrite, published under the `next` tag. The API can still change before 1.0.0. `latest` is still 0.2.
 
 ## Install
 
-```bash
-bun add @opencoredev/sandbox-sdk
+```sh
+npm install @opencoredev/sandbox-sdk@next
 ```
 
-Node.js 22 or 24 is supported. Bun 1.3 or newer is also supported.
+Then add the peer package for each provider you use (see [Providers](#providers)), for example `npm install e2b`. Provider packages are optional peers, so you only download the ones you need. The core has no runtime dependencies.
+
+Requires Node.js 22+ or Bun 1.3+, ESM only. The examples use `await using`, which runs natively on Node.js 24 and Bun. On Node.js 22, compile with TypeScript (target ES2022 or lower) or call `box.destroy()` yourself.
 
 ## Quickstart
 
+This runs with no account and no Docker. The `memory` provider is an in-process fake with a small shell (`echo`, `cat`, `printf`, `sleep`, `ls`, `printenv`):
+
 ```ts
 import { createSandbox } from "@opencoredev/sandbox-sdk";
-import { local } from "@opencoredev/sandbox-sdk/local";
+import { memory } from "@opencoredev/sandbox-sdk/memory";
+
+await using box = await createSandbox(memory());
+
+await box.files.write("hello.txt", "hello from the sandbox\n");
+const result = await box.run("cat hello.txt");
+console.log(result.ok, result.stdout); // true "hello from the sandbox\n"
+```
+
+For a real Linux sandbox, swap the provider. Nothing else changes:
 
-await using sandbox = await createSandbox({ provider: local() });
-console.log((await sandbox.run("node --version")).stdout);
+```ts
+import { createSandbox } from "@opencoredev/sandbox-sdk";
+import { e2b } from "@opencoredev/sandbox-sdk/e2b";
+
+// Reads E2B_API_KEY from the environment. Run `npm install e2b` first.
+await using box = await createSandbox(e2b());
+
+await box.files.write("hello.py", "print('hello from the sandbox')");
+const result = await box.run("python3 hello.py");
+console.log(result.ok, result.stdout);
 ```
 
-`await using` stops the sandbox automatically when its scope exits, including when an operation throws.
+`await using` deletes the sandbox when the scope ends, even if your code throws. A command that exits non-zero resolves with `ok: false`; it never throws.
+
+## Switch providers with one variable
+
+Pick the provider from an environment variable and keep the sandbox code identical. Each adapter loads through a dynamic `import()`, so only the provider you pick needs its peer package installed. At runtime that holds as written. For the TypeScript compiler, the switch still reaches every listed adapter's declarations, and those reference their peer's types. Set `"skipLibCheck": true` in `tsconfig.json` (most templates already do), or install the peers you list as devDependencies, otherwise `tsc` reports TS2307 for the ones you left out.
+
+```ts
+import { createSandbox, type Sandbox } from "@opencoredev/sandbox-sdk";
+import type { Provider } from "@opencoredev/sandbox-sdk/provider";
 
-Node.js 24 and Bun run this syntax directly. On Node.js 22, compile TypeScript to ES2022 or use the callback-style `withSandbox()` helper.
+async function loadProvider(name: string): Promise<Provider> {
+  switch (name) {
+    case "memory": return (await import("@opencoredev/sandbox-sdk/memory")).memory();
+    case "local": return (await import("@opencoredev/sandbox-sdk/local")).local();
+    case "e2b": return (await import("@opencoredev/sandbox-sdk/e2b")).e2b();
+    case "daytona": return (await import("@opencoredev/sandbox-sdk/daytona")).daytona();
+    case "vercel": return (await import("@opencoredev/sandbox-sdk/vercel")).vercel();
+    case "upstash": return (await import("@opencoredev/sandbox-sdk/upstash")).upstash();
+    default: throw new Error(`Unknown SANDBOX_PROVIDER "${name}"`);
+  }
+}
+
+// Portable code takes the base `Sandbox` type: only the methods every provider has.
+async function greet(box: Sandbox): Promise<string> {
+  await box.files.write("greeting.txt", `hello from ${box.provider}\n`);
+  return (await box.run("cat greeting.txt")).stdout.trim();
+}
+
+await using box = await createSandbox(await loadProvider(process.env.SANDBOX_PROVIDER ?? "memory"));
+console.log(await greet(box));
+```
+
+`SANDBOX_PROVIDER=local` runs it in Docker; `SANDBOX_PROVIDER=e2b` runs it on E2B. The repository has a runnable version with every provider and an exhaustive switch in `examples/getting-started`.
+
+Two things differ between providers and are worth checking before you go multi-provider:
+
+- **Optional methods.** `pause`/`resume` and `snapshot` exist only on providers that support them. See [Pause, resume, and snapshots](#pause-resume-and-snapshots) for how this works with a runtime-selected provider.
+- **Create options.** `size`, `network`, `from`, `timeoutMs`, and `idleTimeoutMs` fail with `unsupported` on providers that cannot enforce them. Provider-agnostic code should leave them out or catch that code.
 
 ## Providers
 
-| Provider                                                        | Runtime                 | Best for                                |
-| --------------------------------------------------------------- | ----------------------- | --------------------------------------- |
-| [Local](https://sandbox-sdk.app/docs/providers/local)           | AgentOS VM              | Development, CI, and self-hosting       |
-| [E2B](https://sandbox-sdk.app/docs/providers/e2b)               | Hosted Linux sandbox    | Coding agents and isolated jobs         |
-| [Daytona](https://sandbox-sdk.app/docs/providers/daytona)       | Cloud workspace         | Persistent projects and GPUs            |
-| [Vercel Sandbox](https://sandbox-sdk.app/docs/providers/vercel) | Hosted Linux sandbox    | Coding agents and persistent workspaces |
-| [Upstash Box](https://sandbox-sdk.app/docs/providers/upstash)   | Durable cloud container | Serverless agents and long-lived state  |
-| [Ascii Box](https://sandbox-sdk.app/docs/providers/box)         | Persistent cloud VM     | Full VMs and protected app previews     |
-| [Railway](https://sandbox-sdk.app/docs/providers/railway)       | Ephemeral cloud VM      | Durable jobs and private networking     |
+Import each provider from its own subpath. The root entry never loads a provider SDK, and constructing a factory performs no I/O.
+
+| Provider | Import from | Factory | Credentials (env) | Peer package | Capabilities | Previews |
+| --- | --- | --- | --- | --- | --- | --- |
+| [E2B](https://sandbox-sdk.app/docs/providers/e2b) | `/e2b` | `e2b()` | `E2B_API_KEY` | `e2b` | pause, snapshot, network-policy | any port |
+| [Daytona](https://sandbox-sdk.app/docs/providers/daytona) | `/daytona` | `daytona()` | `DAYTONA_API_KEY` (optional `DAYTONA_API_URL`, `DAYTONA_TARGET`) | `@daytonaio/sdk` | snapshot, size, network-policy | any port; private sandboxes need `preview.headers` |
+| [Vercel](https://sandbox-sdk.app/docs/providers/vercel) | `/vercel` | `vercel()` | `VERCEL_OIDC_TOKEN`, or `VERCEL_TOKEN` + `VERCEL_TEAM_ID` + `VERCEL_PROJECT_ID` | `@vercel/sandbox` | pause, snapshot, size, network-policy | declare in `ports` (max 15) |
+| [Upstash Box](https://sandbox-sdk.app/docs/providers/upstash) | `/upstash` | `upstash()` | `UPSTASH_BOX_API_KEY` (optional `UPSTASH_BOX_BASE_URL`) | `@upstash/box` | pause, snapshot, size, network-policy; no pause with `ephemeral: true` | any port; bearer token in `preview.headers` unless `public: true` |
+| [Railway](https://sandbox-sdk.app/docs/providers/railway) | `/railway` | `railway()` | `RAILWAY_API_TOKEN`, `RAILWAY_ENVIRONMENT_ID` | `railway` | snapshot | declare in `ports` (max 10) |
+| [Tenki](https://sandbox-sdk.app/docs/providers/tenki) | `/tenki` | `tenki()` | `TENKI_AUTH_TOKEN` or `TENKI_API_KEY` | `@tenkicloud/sandbox` | pause, snapshot, size, network-policy | any port; URL may expire (`preview.expiresAt`) |
+| boxd | `/boxd` | `boxd()` | `BOXD_API_KEY` (optional `BOXD_BASE_URL`) | `@boxd-sh/sdk` | pause, snapshot, size | one port at a time; the URL follows the last port requested |
+| Freestyle | `/freestyle` | `freestyle()` | `FREESTYLE_API_KEY` | `freestyle` | pause, snapshot, network-policy | any port |
+| Superserve | `/superserve` | `superserve()` | `SUPERSERVE_API_KEY` | `@superserve/sdk` | pause, snapshot | any port; token in `preview.headers` |
+| Boat | `/boat` | `boat()` | `BOAT_API_KEY` (optional `BOAT_API_BASE`) | `@boatdev/sdk` | size | any port; cookie in `preview.headers` |
+| Sandboxer | `/sandboxer` | `sandboxer({ region })` | `SANDBOXER_API_KEY` (optional `SANDBOXER_REGION`: `us-east`, `eu-central`) | `@boatdev/sdk` | pause, snapshot, size | any port; private URL, send `preview.headers` |
+| [Local (Docker)](https://sandbox-sdk.app/docs/providers/local) | `/local` | `local()` | none; needs a running Docker Engine (`DOCKER_HOST` or `/var/run/docker.sock`) | none | pause, snapshot, size, network-policy (`"none"` only, no allow-lists) | declare in `ports` (default `[3000]`); URL is `http://127.0.0.1:<port>` |
+| [agentOS](https://sandbox-sdk.app/docs/providers/agentos) | `/agentos` | `agentos()` | none | `@rivet-dev/agentos-core` | network-policy | none; no background processes either |
+| Memory | `/memory` | `memory()` | none | none | network-policy | fake `*.memory.invalid` URL; never fetch it |
+
+Capability meanings: `pause` adds `box.pause()` and `box.resume()`, `snapshot` adds `box.snapshot()` and `createSandbox(provider, { from })`, `size` allows the `size` option, and `network-policy` allows `network: "none"` or `{ allow: [...] }`. The SDK also defines `terminal` (`box.terminal()`, an interactive PTY), but no built-in provider supports it yet.
+
+Every factory also accepts its credential as an option, such as `e2b({ apiKey })` or `railway({ token, environmentId })`. Endpoints use `baseUrl` (boxd, Daytona, Tenki, Upstash, Boat), and Boat's default machine size uses `machine`:
+
+```ts
+import { boat } from "@opencoredev/sandbox-sdk/boat";
+import { boxd } from "@opencoredev/sandbox-sdk/boxd";
+import { daytona } from "@opencoredev/sandbox-sdk/daytona";
+import { tenki } from "@opencoredev/sandbox-sdk/tenki";
+
+const providers = [
+  boxd({ baseUrl: "https://boxd.sh:9443" }),
+  daytona({ baseUrl: "https://app.daytona.io/api" }),
+  boat({ baseUrl: "https://boat.dev/api/v1", machine: "small" }),
+  tenki({ apiKey: process.env.TENKI_API_KEY }),
+];
+```
+
+The old names (`boxd.baseURL`, `daytona.apiUrl`, `boat.apiUrl`, `tenki.authToken`, and `boat.type`) still work as deprecated aliases until 1.0.0. When both names are set, the new name wins.
+
+## Core API
+
+### Create, reconnect, clean up
+
+```ts
+import { connectSandbox, createSandbox } from "@opencoredev/sandbox-sdk";
+import { e2b } from "@opencoredev/sandbox-sdk/e2b";
+
+const box = await createSandbox(e2b(), {
+  key: "user:123", // the same key returns the same sandbox
+  env: { NODE_ENV: "development" },
+  secrets: { GITHUB_TOKEN: "ghp_example" }, // redacted from all output and errors
+  network: { allow: ["registry.npmjs.org"] },
+  timeoutMs: 30 * 60_000, // hard lifetime, where the provider supports it
+});
+
+await box.close(); // detach; the sandbox keeps running
+const again = await connectSandbox(e2b(), box.id);
+await again.destroy(); // delete it
+```
+
+`await using box = await createSandbox(...)` disposes the handle when the scope ends:
+
+- Without a `key`, it calls `destroy()` and the sandbox is deleted.
+- With a `key`, it calls `close()`, so the sandbox survives for the next request with that key.
+
+Use `listSandboxes(provider)` and `reapSandboxes(provider, { olderThanMs })` to find and delete sandboxes this SDK created, such as ones a crashed process never cleaned up.
+
+### Run commands and stream output
+
+```ts
+const result = await box.run("npm test", { cwd: "app" });
+if (!result.ok) console.log(result.exitCode, result.output);
+
+const branch = "feature/login";
+await box.$`git checkout ${branch}`; // interpolated values are shell-quoted
+
+const install = box.run("npm install");
+for await (const chunk of install) process.stdout.write(chunk.text); // chunk.stream is "stdout" or "stderr"
+const { ok, durationMs } = await install; // the same handle, now finished
+```
+
+`run` returns a lazy handle: nothing starts until you `await` it or iterate it. Commands start in `/workspace` and keep up to 1 MB per stream (`maxOutputBytes`); older output is dropped and `truncated` is set. `stdout` and `stderr` are separate strings, and `output` interleaves them in arrival order.
+
+### Timeouts and cancellation
+
+```ts
+const slow = await box.run("sleep 600", { timeoutMs: 5_000 });
+console.log(slow.ok, slow.timedOut, slow.exitCode); // false true null
+
+const chained = await box.run("npm test").cwd("app").timeout(60_000);
+
+const controller = new AbortController();
+const pending = box.run("npm run build", { signal: controller.signal });
+controller.abort();
+console.log((await pending).ok); // false; an aborted run also reports timedOut: true
+```
+
+- Commands time out after 120 seconds unless you pass `timeoutMs` or chain `.timeout(ms)`. A timeout or an abort kills the command's process group and resolves with `ok: false`, `exitCode: null`, and `timedOut: true`. It does not throw.
+- `createSandbox(provider, { signal })` rejects with `SandboxError` code `aborted`. A sandbox that arrives after the abort is destroyed for you.
+- `start(..., { readyTimeoutMs })` bounds readiness (default 60 seconds), and `preview(port, { waitMs })` waits for a 2xx.
+- `timeoutMs` and `idleTimeoutMs` on `createSandbox` set the sandbox's own lifetime, not a command timeout. A hard lifetime (`timeoutMs`) works on E2B, Daytona (one minute or more), Tenki, Freestyle, Local, and Memory. An idle timeout (`idleTimeoutMs`) works on Daytona, Railway, Freestyle, Local, and Memory. Every other provider rejects them with `unsupported`.
+
+### Files
+
+```ts
+await box.files.write({ "app/package.json": "{}", "app/index.js": "console.log(1)" });
+const text = await box.files.read("app/index.js");
+const bytes = await box.files.read("app/index.js", { as: "bytes" });
+await box.files.edit("app/index.js", { find: "console.log(1)", replace: "console.log(2)" });
+const matches = await box.files.search("console.log", { path: "app" });
+const entries = await box.files.list("app", { recursive: true });
+await box.files.upload("./local-project", "app", { ignore: ["node_modules"] });
+const diff = await box.files.changes({ since: await box.files.mark() });
+```
+
+Relative paths resolve against `/workspace`. `read` returns a string unless you pass `{ as: "bytes" }`. A missing path fails with `file_not_found`. `edit` fails with `edit_not_found` or `edit_not_unique` unless the text matches exactly once.
+
+### Background processes
+
+```ts
+const dev = await box.start("npm run dev", { name: "dev", ready: { port: 3000 } });
+console.log(dev.ready, dev.status); // true "running"
+
+const { text } = await box.process("dev").logs();
+await dev.stop();
+```
+
+`start` returns once the process is ready. Readiness is one of:
+
+- `{ port: 3000 }`: the port's preview URL answers with a 2xx.
+- `{ http: { port: 3000, path: "/health" } }`: that path answers with a 2xx.
+- `{ log: /listening/ }`: a log line matches.
+
+Without `ready`, `start` returns as soon as the process launches. If the process exits first, `start` fails with `process_exited` and includes the exit code and log tail. Readiness gives up after `readyTimeoutMs` (default 60 seconds) with `timeout`.
+
+The name is the process's durable ID (1 to 128 letters, digits, `-`, `_`). It is optional: without one, `start` derives a stable name from the command, such as `npm-1a2b3c4d`, and returns it as `dev.name`. Any client can find it again with `box.process("dev")`, even after your server restarts. `box.processes()` lists them, and a handle has `logs()`, `lines()`, `stop()`, `restart()`, and `wait()`.
+
+### Previews
+
+```ts
+import { createSandbox } from "@opencoredev/sandbox-sdk";
+import { local } from "@opencoredev/sandbox-sdk/local";
+
+await using box = await createSandbox(local(), { ports: [3000] });
+await box.start("python3 -m http.server 3000", { name: "web", ready: { port: 3000 } });
+
+const preview = await box.preview(3000);
+const response = await fetch(preview.url, { headers: preview.headers });
+console.log(preview.url, response.status); // http://127.0.0.1:<port>/ 200
+```
+
+Always send `preview.headers`. Daytona (private sandboxes), Upstash, Superserve, Boat, and Sandboxer put the access token there, and those providers reject requests without it. Local, Vercel, and Railway only route ports you declared with `createSandbox(provider, { ports })`, so pass `ports` in provider-agnostic code; the other providers ignore it. Servers must listen on `0.0.0.0`, not `localhost`.
+
+### Pause, resume, and snapshots
+
+```ts
+import { createSandbox } from "@opencoredev/sandbox-sdk";
+import { e2b } from "@opencoredev/sandbox-sdk/e2b";
+
+await using box = await createSandbox(e2b());
+const snap = await box.snapshot();
+await using copy = await createSandbox(e2b(), { from: snap.id });
+
+await box.pause();
+await box.resume();
+```
+
+These methods are gated in the types by the provider's capability union. With a concrete provider, a missing method is a compile error:
+
+```ts
+import { createSandbox } from "@opencoredev/sandbox-sdk";
+import { boat } from "@opencoredev/sandbox-sdk/boat";
+
+await using box = await createSandbox(boat());
+// @ts-expect-error Boat has no snapshot capability, so the method does not exist.
+await box.snapshot();
+```
+
+When you pick the provider at runtime, as in [Switch providers](#switch-providers-with-one-variable), the provider's type is the wide `Provider`, so the SDK cannot know which methods exist. `pause`, `resume`, `snapshot`, and `terminal` are then optional on the sandbox, and calling one directly is a compile error. `hasCapability` checks at runtime and narrows the type:
+
+```ts
+import { hasCapability } from "@opencoredev/sandbox-sdk";
+
+if (hasCapability(box, "snapshot")) {
+  const { id } = await box.snapshot();
+  console.log(`saved ${id}`);
+}
+```
+
+`box.capabilities.has("snapshot")` gives the same answer as a boolean, but it cannot narrow `box`, so use `hasCapability` before calling the method.
+
+### Git
+
+```ts
+await box.git.clone("https://github.com/opencoredev/sandbox-sdk", { dir: "repo", depth: 1 });
+await box.git.commit("repo", { message: "Update docs", all: true });
+await box.git.push("repo", { token: process.env.GITHUB_TOKEN });
+```
+
+Tokens reach git through a temporary credential helper, never argv, env, or shell history, and are redacted from output. Git must be installed in the sandbox image; the memory provider has no git.
+
+### Errors
+
+```ts
+import { SandboxError } from "@opencoredev/sandbox-sdk";
+
+try {
+  await box.files.read("missing.txt");
+} catch (error) {
+  if (!(error instanceof SandboxError)) throw error;
+  console.error(error.code, error.message, error.hint, error.retryable);
+}
+```
+
+The SDK only throws `SandboxError`. A non-zero exit, a command timeout, or an aborted `run` is a result, not an error. `hint` is the next step on its own, `retryable` says whether the same call can succeed again, and `provider` and `sandboxId` say where it happened. Secrets are redacted from every field.
+
+| `code` | Meaning |
+| --- | --- |
+| `auth` | Credentials are missing or rejected. |
+| `not_found` | The sandbox no longer exists, or this handle was closed. |
+| `quota` | A provider limit or billing stopped the request. Usually retryable. |
+| `unavailable` | The provider is down or unreachable. Usually retryable. |
+| `unsupported` | The provider cannot do what was asked: `size`, `network`, a lifetime option, an undeclared preview port. |
+| `timeout` | A provider operation or a readiness check took too long. |
+| `aborted` | Your `AbortSignal` fired during `createSandbox`. |
+| `outcome_unknown` | The request may or may not have happened. Check state before retrying. |
+| `process_exited` | A background process exited before it was ready. |
+| `port_not_ready` | A preview did not answer with a 2xx before `waitMs` ran out. |
+| `edit_not_found`, `edit_not_unique` | `files.edit` matched zero times or more than once. |
+| `file_not_found` | The path does not exist. |
+| `invalid_argument` | The input is invalid. Retrying will not help. |
+| `provider` | Any other provider or adapter failure. Read `message` and `cause`. |
+
+## Give an agent a sandbox
+
+Install `zod` and your agent framework, then pass the tools to your agent:
+
+```ts
+import { generateText, stepCountIs } from "ai";
+import { sandboxTools } from "@opencoredev/sandbox-sdk/ai";
+
+const { text } = await generateText({
+  model: "anthropic/claude-opus-5-5",
+  tools: sandboxTools(box, { root: "/workspace/app" }),
+  stopWhen: stepCountIs(20),
+  prompt: "Add a /health route to the Express app and run its tests.",
+});
+```
+
+| Framework | Import | Returns |
+| --- | --- | --- |
+| AI SDK 7 | `@opencoredev/sandbox-sdk/ai` | tool map for `generateText` / `streamText` |
+| Mastra 1.78+ | `@opencoredev/sandbox-sdk/mastra` | tool map for `new Agent({ tools })` |
+| OpenAI Agents 0.20+ | `@opencoredev/sandbox-sdk/openai` | tool array for `new Agent({ tools })` |
+| Anything else | `@opencoredev/sandbox-sdk/tools` | `createSandboxTools` and Zod `toolSchemas` |
+
+The default tools are `run`, `read_file`, `write_file`, `edit_file`, `start_process`, `process_logs`, and `stop_process`. Opt into `search`, `list_files`, `changes`, or `preview` with `allow`. Results are compact and capped for model context, and registered secrets never reach the model. Use `beforeRun` to deny or rewrite commands. `root` limits file paths, but it is not a security boundary; the sandbox is.
+
+## Performance
+
+The SDK aims for near-zero overhead on top of each provider's own API. The root entry is under 8 KB minified, providers load on first use, and `createSandbox` adds no provider calls beyond the create itself unless you pass `secrets`, `from`, or `trackChanges: true` (one exec each).
+
+Time the SDK adds on top of each provider's own SDK, as median milliseconds. "Cold" is `createSandbox` plus the first `box.run("true")`, compared with the provider SDK's create plus its own exec. "Run" is a warm `run("true")` on an existing sandbox. Negative numbers and small differences are within provider noise.
+
+| Provider | Create | Cold: create to first command | Warm `run` |
+| --- | ---: | ---: | ---: |
+| E2B | +24 | +52 | +8 |
+| Daytona | ±0 | ±0 | +38 |
+| Upstash Box | +27 | +69 | +15 |
+| Freestyle | ±0 | +51 | +23 |
+| Tenki | ±0 | +119 | +15 |
+| Superserve | ±0 | +73 | +9 |
+| boxd | +272 | +370 | +52 |
+
+boxd has no native metadata field, so a sandbox created with labels or a `key` writes its ownership record with one extra request before `createSandbox` returns. The other providers send labels with the create call itself and run any guest setup inside your first command.
 
-Local is included. Cloud providers use their official SDKs and credentials.
+Measured on 2026-10-22 from one Linux host with `bench/scripts/sdk-overhead.ts`, 5 to 8 cold samples and 10 warm samples per provider. See the `bench/` directory in the repository to reproduce.
 
-## Documentation
+## More
 
-Setup, usage, integrations, and API reference are available at [sandbox-sdk.app/docs](https://sandbox-sdk.app/docs).
+- [Documentation](https://sandbox-sdk.app/docs): guides, provider pages, and the [error reference](https://sandbox-sdk.app/docs/reference/errors).
+- Write your own provider: implement `Provider` from `@opencoredev/sandbox-sdk/provider` and test it with `runConformance` from `@opencoredev/sandbox-sdk/testing`.
+- [Report an issue](https://github.com/opencoredev/sandbox-sdk/issues).
+- [Changelog](./CHANGELOG.md).
 
 ## License
 
-[MIT](./LICENSE) © OpenCore
+MIT

package/dist/ai.d.ts

@@ -0,0 +1,5 @@
+import { type Tool } from "ai";
+import type { Sandbox } from "./types.js";
+import { type SandboxToolsOptions, type ToolResult, type ToolParameters } from "./tools.js";
+export type { SandboxToolsOptions } from "./tools.js";
+export declare function sandboxTools(box: Sandbox, options?: SandboxToolsOptions): Record<string, Tool<ToolParameters, ToolResult, Record<string, never>>>;

package/dist/ai.js

@@ -0,0 +1 @@
+import{k}from"./chunk-t5vr9nd8.js";import{w}from"./chunk-v6y7eqxw.js";import"./chunk-cwx6cc31.js";import{tool as u}from"ai";function b(p,m){return Object.fromEntries(w(p,m).map((o)=>[o.name,u({description:o.description,inputSchema:o.inputSchema,async*execute(e,s){let r=new AbortController,c=s.abortSignal?AbortSignal.any([r.signal,s.abortSignal]):r.signal,n=new k,a=n.stream(),l=a.next(),i=o.execute(e,(t)=>n.emit({stream:t.stream,text:t.text}),c).finally(()=>n.end());try{while(!0){let t=await l;if(t.done)break;yield{text:t.value.text},l=a.next()}yield await i}finally{r.abort(),await i,await a.return(void 0)}},toModelOutput:({output:e})=>({type:"text",value:e.text})})]))}export{b as sandboxTools};

package/dist/chunk-59t3rqja.js

@@ -0,0 +1,2 @@
+import{e,l,r}from"./chunk-gc8zdxyb.js";var h=new WeakMap,O=(n,t)=>h.get(n)?.get(t);function M(n,t,a){let i=h.get(n);if(!i)i=new Map,h.set(n,i);if(i.delete(t),i.set(t,a),i.size>256){let o=i.keys().next().value;if(o!==void 0)i.delete(o)}}function L(n,t){h.get(n)?.delete(t)}function v(n,t){let a=h.get(n);if(!a)return;for(let[i,o]of a)if(o===t)a.delete(i)}function T(n,t){return n.capabilities.has(t)}var _={"sandbox-sdk":"1"},R=new WeakMap;function j(n,t){for(let a of Object.keys({...t.env,...t.secrets}))if(!/^[A-Za-z_][A-Za-z0-9_]*$/.test(a))r("Invalid environment variable name");for(let a of n.capabilities)if(a==="pause"&&(!n.pause||!n.resume)||a==="snapshot"&&!n.snapshot||a==="terminal"&&!n.terminal)throw new e("Invalid adapter capabilities. A declared method is missing. Fix the adapter contract.",{code:"provider"});if(t.size!==void 0&&!n.capabilities.has("size"))throw new e("Creation refused. Provider cannot enforce size. Choose a provider with size support.",{code:"unsupported"});if(t.network!==void 0&&t.network!=="all"&&!n.capabilities.has("network-policy"))throw new e("Creation refused. Provider cannot enforce network policy. Choose a provider with network-policy support.",{code:"unsupported"});if(t.from!==void 0&&!n.capabilities.has("snapshot"))throw new e("Creation refused. Provider cannot restore snapshots. Choose a provider with snapshot support.",{code:"unsupported"});if(t.keyMode==="exact"&&n.keyMode!=="exact"&&!t.locator?.withLock)throw new e("Exact key mode unavailable. Two-function locator storage cannot enforce distributed uniqueness. Supply locator.withLock or use an exact provider.",{code:"unsupported"});for(let a of t.ports??[])if(!Number.isInteger(a)||a<1||a>65535)r("Invalid port");for(let a of[t.timeoutMs,t.idleTimeoutMs])if(a!==void 0&&(!Number.isFinite(a)||a<=0))r("Timeouts must be positive milliseconds")}async function p(n,t={}){let a=new l;a.add(Object.values(t.secrets??{}));async function i(){let u;try{if(j(n,t),t.signal?.aborted)throw new e("Creation aborted. Signal was already aborted. Retry with a fresh signal.",{code:"aborted"});let c;if(t.key){let x=await t.locator?.get(t.key)??O(n,t.key);if(x)try{c=await n.connect(x)}catch(k){if(!(k instanceof e)||k.code!=="not_found")throw k;L(n,t.key)}c??=await n.find(t.key)}let m=!c;if(!c){let{secrets:x,locator:k,keyMode:A,trackChanges:H,...F}=t,C=n.create({...F,env:{...t.env,...x},labels:{...t.labels,..._}}).catch(async(b)=>{if(t.key&&n.keyMode==="exact"&&!t.signal?.aborted){let w=await n.find(t.key);if(w)return m=!1,w}throw b});if(t.signal){let b=t.signal,w=()=>{},K=new Promise((P,z)=>{if(w=()=>z(new e("Creation aborted. The signal was cancelled. Any late sandbox will be destroyed.",{code:"aborted"})),b.addEventListener("abort",w,{once:!0}),b.aborted)w()}),B=C.then(async(P)=>{if(b.aborted){if(m)await n.destroy(P.id);throw new e("Creation aborted. Late sandbox destroyed. Retry with a fresh signal.",{code:"aborted"})}return P});try{c=await Promise.race([B,K])}finally{b.removeEventListener("abort",w)}}else c=await C;if(m)u=c}if(t.signal?.aborted){if(u)await n.destroy(u.id);throw u=void 0,new e("Creation aborted. Sandbox arrived after cancellation and was destroyed. Retry with a fresh signal.",{code:"aborted"})}if(t.key)await t.locator?.set(t.key,c.id),M(n,t.key,c.id);let{makeHandle:I}=await import("./chunk-hjzhc3qg.js");return await I(n,c,m,t,a)}catch(c){if(u)v(n,u.id),await n.destroy(u.id).catch(()=>{});throw a.error(c,n.name)}}if(!t.key)return i();let o=R.get(n);if(!o)o=new Map,R.set(n,o);let s=o.get(t.key)??Promise.resolve(),{key:f,locator:y}=t,d=s.catch(()=>{}).then(()=>t.keyMode==="exact"&&n.keyMode==="best-effort"&&y?.withLock?y.withLock(f,i):i());o.set(t.key,d);try{return await d}finally{if(o.get(t.key)===d)o.delete(t.key)}}async function g(n,t,a={}){let i=new l;i.add(Object.values(a.secrets??{}));try{j(n,a);let o=await n.connect(t),{makeHandle:s}=await import("./chunk-hjzhc3qg.js");return await s(n,o,!1,{...a,key:o.key},i)}catch(o){throw i.error(o,n.name,t)}}async function S(n,t={}){try{return(await n.list({...t.labels,..._})).filter((a)=>a.labels["sandbox-sdk"]==="1")}catch(a){throw new l().error(a,n.name)}}async function E(n,t={}){if(t.olderThanMs!==void 0&&(!Number.isFinite(t.olderThanMs)||t.olderThanMs<0))r("olderThanMs must be non-negative");let a=t.idleOnly?(await import("./chunk-md6fmprc.js")).isRunActive:()=>!1,i=0;try{for(let o of await S(n,t))if(Date.now()-o.createdAt>=(t.olderThanMs??0)){if(t.idleOnly){if(a(n.name,o.id))continue;let s;try{let f=await n.connect(o.id),{makeHandle:y}=await import("./chunk-hjzhc3qg.js");s=await y(n,f,!1,{},new l,!1)}catch(f){if(f instanceof e&&f.code==="not_found"){i++;continue}throw f}try{let[f,y]=await Promise.all([s.processes(),s.files.list("/tmp/.sandbox-sdk/runs").catch(async(d)=>{if(d instanceof e&&(["file_not_found","not_found"].includes(d.code)||d.code==="provider"&&!await s.files.exists("/tmp/.sandbox-sdk/runs")))return[];throw d})]);if(f.some((d)=>d.status==="running"||d.status==="starting")||y.length>0)continue}finally{await s.close()}}if(a(n.name,o.id))continue;v(n,o.id);try{await n.destroy(o.id)}catch(s){if(!(s instanceof e)||s.code!=="not_found")throw s}i++}return i}catch(o){throw new l().error(o,n.name)}}
+export{v,T,p,g,S,E};

package/dist/chunk-cwx6cc31.js

@@ -0,0 +1,2 @@
+import{f}from"./chunk-t5vr9nd8.js";import{stripVTControlCharacters as u}from"node:util";var i=new WeakMap;function C(s,r){i.set(s,r)}function p(s){let r=i.get(s);if(!r)throw Error("Unknown sandbox handle. Secret redaction cannot be guaranteed. Use createSandbox or connectSandbox.");return r}function _(s,r){return p(s).text(u(r))}function P(s,r){let n={stdout:"plain",stderr:"plain"},c=f(p(s),r,!0);return{push(a){let t=n[a.stream],o="";for(let e of a.text)switch(t){case"plain":if(e==="\x1B")t="escape";else if(e==="›")t="csi";else if("˜žŸ".includes(e))t="string";else o+=e;break;case"escape":t=e==="["?"csi":"]PX^_".includes(e)?"string":e>=" "&&e<="/"?"escape":"plain";break;case"csi":if(e>="@"&&e<="~")t="plain";break;case"string":if(e==="\x07"||e==="œ")t="plain";else if(e==="\x1B")t="string_escape";break;case"string_escape":t=e==="\\"?"plain":"string";break;default:return t}if(n[a.stream]=t,o)c.push({stream:a.stream,text:o})},flush(){c.flush()}}}
+export{C,_,P};

package/dist/chunk-exv1kf89.js

@@ -0,0 +1,60 @@
+import{e}from"./chunk-gc8zdxyb.js";var a=(o)=>`'${o.replaceAll("'","'\\''")}'`,n=(o,...s)=>`python3 -c ${a(o)} ${s.map(a).join(" ")}`,d=`def stdin_file():
+ try: return os.fdopen(os.memfd_create('sandbox-sdk-stdin'),'w+b')
+ except (AttributeError,OSError):
+  import tempfile
+  return tempfile.TemporaryFile()
+class Process:
+ def __init__(self,v,env,stdin,session=False):
+  if not all(hasattr(os,name) for name in ['posix_spawn','waitstatus_to_exitcode']):
+   self.legacy(v,env,stdin,session); return
+  directory=os.open('.',os.O_RDONLY)
+  r,w=os.pipe(); e,x=os.pipe()
+  try:
+   os.chdir(v['cwd'])
+   error=FileNotFoundError(2,os.strerror(2),'sh')
+   signals=[getattr(signal,s) for s in ['SIGPIPE','SIGXFZ','SIGXFSZ'] if hasattr(signal,s)]
+   for path in os.get_exec_path(env):
+    try:
+     self.pid=os.posix_spawn(os.path.join(path,'sh'),['sh','-c',v['command']],env,file_actions=[(os.POSIX_SPAWN_DUP2,stdin.fileno(),0),(os.POSIX_SPAWN_DUP2,w,1),(os.POSIX_SPAWN_DUP2,x,2)],setsid=session,setsigdef=signals)
+     break
+    except (FileNotFoundError,NotADirectoryError): pass
+    except OSError as failure:
+     if failure.errno==38: raise NotImplementedError()
+     error=failure
+   else: raise error
+  except NotImplementedError:
+   os.close(r); os.close(e)
+   self.legacy(v,env,stdin,session); return
+  except BaseException:
+   os.close(r); os.close(e); raise
+  finally:
+   os.fchdir(directory); os.close(directory); os.close(w); os.close(x)
+  self.stdout=os.fdopen(r,'rb',buffering=0); self.stderr=os.fdopen(e,'rb',buffering=0)
+  self.code=None
+ def legacy(self,v,env,stdin,session):
+  import subprocess
+  self.child=subprocess.Popen(['sh','-c',v['command']],cwd=v['cwd'],env=env,stdin=stdin,stdout=subprocess.PIPE,stderr=subprocess.PIPE,start_new_session=session)
+  self.pid=self.child.pid; self.stdout=self.child.stdout; self.stderr=self.child.stderr
+ def poll(self):
+  if hasattr(self,'child'): return self.child.poll()
+  if self.code is None:
+   pid,status=os.waitpid(self.pid,os.WNOHANG)
+   if pid: self.code=os.waitstatus_to_exitcode(status)
+  return self.code
+ def wait(self):
+  if hasattr(self,'child'): return self.child.wait()
+  if self.code is None: self.code=os.waitstatus_to_exitcode(os.waitpid(self.pid,0)[1])
+  return self.code
+`,c=(o,s,f="provider")=>new e(`${s}. Check the ${o.name} sandbox before retrying.`,{code:f,provider:o.name}),y=`import os,sys,json,stat
+p=sys.argv[1]
+def info(p):
+ s=os.lstat(p)
+ return dict(path=p,type='symlink' if stat.S_ISLNK(s.st_mode) else 'directory' if stat.S_ISDIR(s.st_mode) else 'file',size=s.st_size,modifiedAt=s.st_mtime*1000)
+try: print(json.dumps([info(os.path.join(p,n)) for n in os.listdir(p)] if sys.argv[2]=='list' else info(p)))
+except FileNotFoundError: print('SDK_FILE_NOT_FOUND')`;function u(o,s){if(!s||typeof s!=="object"||!("path"in s)||typeof s.path!=="string"||!("type"in s)||s.type!=="file"&&s.type!=="directory"&&s.type!=="symlink"||!("size"in s)||typeof s.size!=="number"||!("modifiedAt"in s)||typeof s.modifiedAt!=="number")throw c(o,"Invalid file metadata");return{path:s.path,type:s.type,size:s.size,modifiedAt:s.modifiedAt}}function h(o,s){let f=async(t,r,i)=>{let l=await o(t),p=await l.raw(n(y,r,i));if(p.trim()==="SDK_FILE_NOT_FOUND")throw c(l,"File does not exist","file_not_found");let m=JSON.parse(p);return{g:l,value:m}};return{writeCreatesParents:!0,readRange:(t,r,i)=>s(t,async()=>(await o(t)).read(r,i)),read:(t,r)=>s(t,async()=>(await o(t)).read(r)),write:(t,r,i)=>s(t,async()=>{let l=await o(t);try{await s(t,()=>l.upload(r,i))}catch(p){if(!(p instanceof e)||!["not_found","file_not_found"].includes(p.code))throw p;await l.raw(n("import os,sys; os.makedirs(os.path.dirname(sys.argv[1]),exist_ok=True)",r)),await l.upload(r,i)}}),stat:(t,r)=>s(t,async()=>{let{g:i,value:l}=await f(t,r,"stat");return u(i,l)}),list:(t,r)=>s(t,async()=>{let{g:i,value:l}=await f(t,r,"list");if(!Array.isArray(l))throw c(i,"Invalid directory listing");return l.map((p)=>u(i,p))}),mkdir:(t,r)=>s(t,async()=>{await(await o(t)).raw(n("import os,sys; os.makedirs(sys.argv[1],exist_ok=True)",r))}),remove:(t,r,i)=>s(t,async()=>{await(await o(t)).raw(n(`import os,sys,shutil
+p=sys.argv[1]
+if os.path.isdir(p) and not os.path.islink(p):
+ if sys.argv[2]=='true': shutil.rmtree(p)
+ else: os.rmdir(p)
+else: os.unlink(p)`,r,String(i.recursive)))})}}
+export{a,n,d,h};

package/dist/chunk-gc8zdxyb.js

@@ -0,0 +1,2 @@
+var s={auth:"Set the provider's API key environment variable or pass it to the provider factory.",not_found:"Create a new sandbox, or pass a key to createSandbox so it recreates one for you.",quota:"Wait and retry, destroy unused sandboxes with reapSandboxes, or raise the provider plan.",unavailable:"Retry with backoff. Check the provider's status page if it persists.",unsupported:"Remove the option or choose a provider that supports it. Check box.capabilities.",timeout:"Retry, or raise the relevant timeout option.",aborted:"Retry with a fresh AbortSignal if you still need the result.",outcome_unknown:"Check the sandbox state before retrying. If in doubt, destroy it.",process_exited:"Read the exit code and log tail in the message, fix the command, and start it again.",port_not_ready:"Check that the server listens on 0.0.0.0 and the right port, then read its logs.",edit_not_found:"Read the file again and use text that is in it.",edit_not_unique:"Add surrounding lines to find so it matches exactly once.",file_not_found:"Check the path. Relative paths resolve against /workspace.",invalid_argument:"Fix the input. Retrying the same call will not help.",provider:"Read the message and cause. Report it if it looks like an SDK bug."};class e extends Error{code;retryable;hint;provider;sandboxId;constructor(t,n){super(t,{cause:n.cause});this.name="SandboxError",this.code=n.code,this.retryable=n.retryable??!1,this.hint=n.hint??s[n.code]??s.provider,this.provider=n.provider??"unknown",this.sandboxId=n.sandboxId}}class l{values=new Set;add(t){for(let n of t)if(n)this.values.add(n)}text(t){for(let n of[...this.values].sort((a,o)=>o.length-a.length))t=t.split(n).join("[REDACTED]");return t}get secrets(){return[...this.values].sort((t,n)=>n.length-t.length)}get maxLength(){return Math.max(1,...[...this.values].map((t)=>t.length))}error(t,n,a){let o=t instanceof Error?t.message:String(t),d=t instanceof e?o:`${o}. Provider request failed. Check the provider settings and retry.`,i=t instanceof e?t:{code:"provider"};return new e(this.text(d),{code:i.code,retryable:i.retryable,hint:this.text(i.hint??s[i.code]??s.provider),provider:n,sandboxId:a,cause:t instanceof Error&&t.cause!==void 0?this.text(String(t.cause instanceof Error?t.cause.message:t.cause)):void 0})}}function r(t){throw new e(`${t}. The request is invalid. Check the supplied options.`,{code:"invalid_argument"})}
+export{e,l,r};