# Sandbox SDK

> Sandboxes for your agents and your users. Any provider, one line. One TypeScript API over Docker, agentOS, E2B, Vercel Sandbox, Daytona, Upstash Box, Railway, Boat, Sandboxer, Tenki, Superserve, boxd, and Freestyle, called with your own keys.

**When to use Sandbox SDK.** Use it when server-side TypeScript (Node 22+ or Bun 1.3+) needs an isolated Linux machine to:

- give an AI agent tools to run commands, read and edit files, and start dev servers (AI SDK, Mastra, or the OpenAI Agents SDK);
- run code a user or a model wrote, such as an AI app builder with a live preview;
- keep one long-lived sandbox per user or project and find it again by key;
- switch between Docker or agentOS on your own machine, E2B, Vercel Sandbox, Daytona, Upstash Box, Railway, Boat, Sandboxer, Tenki, Superserve, boxd, and Freestyle without rewriting code;
- test all of the above offline with the in-process `memory()` provider.

It is not a hosted service: it calls each provider's HTTP API or SDK with your keys, and nothing runs between you and the provider. It does not run in the browser, since provider keys must stay on a server. It is not an isolation layer of its own: the provider supplies the security boundary.

**How an agent should use it.**

1. Install the package: `npm i @opencoredev/sandbox-sdk` or `bun add @opencoredev/sandbox-sdk`. E2B, Daytona, Freestyle, Superserve, Boat, and Sandboxer need nothing else. For Vercel, Upstash Box, Railway, Tenki, boxd, or agentOS, install that provider's SDK next to it (`@vercel/sandbox`, `@upstash/box`, `railway`, `@tenkicloud/sandbox`, `@boxd-sh/sdk`, or `@rivet-dev/agentos-core`).
2. Start with `memory()` from `@opencoredev/sandbox-sdk/memory` (no machine, no keys), then `local()` from `/local` (Docker), following the [Quickstart](https://sandbox-sdk.app/docs/getting-started/quickstart).
3. Create sandboxes with `createSandbox(provider, options)` and `await using`. Pass `key` to get the same sandbox back on the next request.
4. A non-zero exit code is a result, not an error: check `result.ok`. The SDK throws only `SandboxError`; branch on `error.code` ([errors](https://sandbox-sdk.app/docs/reference/errors)).
5. Check an option against the [capability matrix](https://sandbox-sdk.app/docs/reference/capabilities) before using it. An option a provider can't enforce fails with `unsupported` instead of being ignored.
6. For agent tools, import `sandboxTools` from `/ai`, `/mastra`, or `/openai` ([agent tools](https://sandbox-sdk.app/docs/reference/agent-tools)).

Source: [github.com/opencoredev/sandbox-sdk](https://github.com/opencoredev/sandbox-sdk). Package: [@opencoredev/sandbox-sdk on npm](https://www.npmjs.com/package/@opencoredev/sandbox-sdk).

## Docs

- [Overview](https://sandbox-sdk.app/docs): Sandboxes for your agents and your users. Any provider, one line. Sandbox SDK is one TypeScript API over Docker, E2B, Vercel Sandbox, Daytona, and ten more providers.
- [Install](https://sandbox-sdk.app/docs/getting-started/installation): Install Sandbox SDK, plus the provider SDK for Vercel, Upstash, Railway, Tenki, boxd, or agentOS if you use one. Requirements, optional packages, and where your keys must stay.
- [Quickstart](https://sandbox-sdk.app/docs/getting-started/quickstart): Run your first sandbox in memory with no account and no Docker, then run the same code in a real Linux container, then on a cloud provider.
- [Choose a provider](https://sandbox-sdk.app/docs/getting-started/choose-a-provider): Decide where your sandboxes run. Start with Local or Memory while you build, then pick E2B, Vercel Sandbox, or Daytona based on what your app needs.
- [Upgrade from 0.2](https://sandbox-sdk.app/docs/upgrade-from-0-2): Move code from Sandbox SDK 0.2 to 1.0. Covers createSandbox, run, files, processes, ports, snapshots, the local provider, and removed providers.

## Providers

- [Compare providers](https://sandbox-sdk.app/docs/providers): Compare Local with Docker or agentOS, E2B, Vercel Sandbox, Daytona, Upstash Box, Railway, Boat, Sandboxer, Tenki, Superserve, boxd, Freestyle, and Memory side by side. Factories, credentials, and what each one is best for.
- [Local](https://sandbox-sdk.app/docs/providers/local): Run sandboxes as Docker containers on your own machine. No account or key. Exact keys, pause, image snapshots, size presets, and loopback previews.
- [Rivet agentOS](https://sandbox-sdk.app/docs/providers/agentos): Run command and file tasks locally in V8 and WebAssembly, without Docker or a cloud account. Exact in-process keys and host allow lists.
- [E2B](https://sandbox-sdk.app/docs/providers/e2b): Run sandboxes as E2B microVMs. Pause with memory intact, snapshots, network allow lists, and a hard lifetime a reconnect can't extend.
- [Vercel Sandbox](https://sandbox-sdk.app/docs/providers/vercel): Run sandboxes on Vercel Sandbox microVMs. Exact keys, OIDC auth inside Vercel, pinned images, session lifetimes, vCPU sizing, native network policies, and up to 15 declared preview ports.
- [Daytona](https://sandbox-sdk.app/docs/providers/daytona): Run sandboxes on Daytona. Exact machine sizes, idle auto-stop, wall-clock lifetimes, network allow lists, snapshots, and token-protected previews.
- [Upstash Box](https://sandbox-sdk.app/docs/providers/upstash): Run durable or ephemeral cloud containers on Upstash Box. Size presets, native network policies, filesystem snapshots, and bearer-protected previews.
- [Railway](https://sandbox-sdk.app/docs/providers/railway): Run ephemeral Linux VMs on Railway. Streaming commands, filesystem checkpoints, idle destruction, and public previews on declared ports.
- [Boat](https://sandbox-sdk.app/docs/providers/boat): Run persistent Ubuntu VMs for long-running agents on Boat. Size presets, durable background processes, and cookie-authenticated previews.
- [Sandboxer](https://sandbox-sdk.app/docs/providers/sandboxer): Run Ubuntu microVMs on Sandboxer in two regions. Size presets, pause and resume, named snapshots, and cookie-authenticated previews.
- [Tenki](https://sandbox-sdk.app/docs/providers/tenki): Run coding agents on full Tenki Linux VMs. Memory pause, disk and memory snapshots, exact sizes, network allow lists, and a hard lifetime.
- [Superserve](https://sandbox-sdk.app/docs/providers/superserve): Run Firecracker microVMs on Superserve. Pause and resume, snapshots, egress allow lists, secret bindings, and HTTPS previews.
- [boxd](https://sandbox-sdk.app/docs/providers/boxd): Persistent, isolated Linux machines through the official boxd SDK. Memory pause, snapshots, fixed-ratio sizes, egress allow lists, lifetimes, persistent disks, and public HTTPS previews.
- [Freestyle](https://sandbox-sdk.app/docs/providers/freestyle): Run persistent Linux VMs on Freestyle. Default-deny outbound networking, memory pause and snapshots, second-level timeouts, and public HTTPS previews.
- [Memory](https://sandbox-sdk.app/docs/providers/memory): An in-process fake provider for unit tests. Files in a map, a small shell with handlers you can extend, fake preview URLs, and no network.
- [Write a provider](https://sandbox-sdk.app/docs/providers/custom): Adapt any sandbox service to Sandbox SDK. Implement a small set of primitives from /provider, then check your adapter with runConformance from /testing.

## Integrations

- [Integrations](https://sandbox-sdk.app/docs/integrations): Use Sandbox SDK with agent frameworks (AI SDK, Mastra, OpenAI Agents SDK) and web frameworks (Next.js, Hono). Each page shows the wiring and where keys stay.

### Agent frameworks

- [AI SDK](https://sandbox-sdk.app/docs/integrations/ai-sdk): Give an AI SDK agent sandbox tools with sandboxTools from @opencoredev/sandbox-sdk/ai. Works with generateText, streamText, and useChat, and streams command output.
- [Mastra](https://sandbox-sdk.app/docs/integrations/mastra): Give a Mastra agent sandbox tools with sandboxTools from @opencoredev/sandbox-sdk/mastra. A tool map for new Agent, with abort support.
- [OpenAI Agents](https://sandbox-sdk.app/docs/integrations/openai-agents): Give an OpenAI Agents SDK agent sandbox tools with sandboxTools from @opencoredev/sandbox-sdk/openai. A strict tool array for new Agent.

### Web frameworks

- [Next.js](https://sandbox-sdk.app/docs/integrations/nextjs): Use Sandbox SDK from Next.js App Router route handlers and server actions. Keep one sandbox per project, stream command output, and reap with a cron route.
- [Hono](https://sandbox-sdk.app/docs/integrations/hono): Use Sandbox SDK from Hono routes on Node or Bun. Keep one sandbox per project, stream command output with hono/streaming, and return preview URLs.

## Guides

- [Give your agent a sandbox](https://sandbox-sdk.app/docs/guides/give-your-agent-a-sandbox): Hand an AI SDK, Mastra, or OpenAI Agents SDK agent ready-made sandbox tools with sandboxTools, see what the model gets back, and limit what it can touch.
- [Build an AI app builder](https://sandbox-sdk.app/docs/guides/build-an-ai-app-builder): Build a Next.js chat where a model writes an app inside a per-project sandbox and the user sees a live preview. Uses the AI SDK and Vercel Sandbox.
- [One sandbox per user](https://sandbox-sdk.app/docs/guides/per-user-sandboxes): Give each user or project a sandbox that is still there on their next request, from any server. Use a key, run setup once, reattach to processes, and avoid races.
- [Dev servers and previews](https://sandbox-sdk.app/docs/guides/dev-servers-and-previews): Start a dev server in a sandbox, wait until it answers, show its preview URL to a user, follow its logs, and restart it after a resume, on every provider.
- [Testing with memory()](https://sandbox-sdk.app/docs/guides/testing-with-memory): Test code that uses sandboxes without Docker or cloud keys. memory() is an in-process fake with files, scripted commands, processes, and fake preview URLs.
- [Machine size and network](https://sandbox-sdk.app/docs/guides/machine-size-and-network): Pick a CPU and memory size for a sandbox, and limit which hosts it can reach. Both fail at creation when the provider can't enforce them.
- [Clean up sandboxes](https://sandbox-sdk.app/docs/guides/cleanup): Stop paying for sandboxes nobody uses. Pick the right limits for your provider, schedule a reaper, scope it with labels, and check what is still running.

## Concepts

- [How it works](https://sandbox-sdk.app/docs/concepts/how-it-works): What happens between your code and a sandbox. The core, provider adapters, provider APIs and SDKs, where state lives, and why options fail instead of being ignored.
- [Sandboxes and keys](https://sandbox-sdk.app/docs/concepts/sandboxes-and-keys): Create a sandbox, give it a key so you get the same one back next time, and reattach to it from any server process.
- [Running commands](https://sandbox-sdk.app/docs/concepts/running-commands): Run shell commands, stream their output, and build commands safely with the $ tag. Covers defaults, timeouts, and what a result contains.
- [Processes and previews](https://sandbox-sdk.app/docs/concepts/processes-and-previews): Start long-running processes like dev servers, wait until they are ready, read their logs with cursors, reattach by name, and get preview URLs.
- [Files and git](https://sandbox-sdk.app/docs/concepts/files-and-git): Read, write, and edit files in a sandbox, move folders in and out, search, watch for changes, see what changed since creation, and use git with tokens kept out of logs.
- [Lifecycle and cleanup](https://sandbox-sdk.app/docs/concepts/lifecycle-and-cleanup): Close or destroy sandboxes, set idle and lifetime limits, pause and snapshot where supported, and reap sandboxes your app forgot.

## Reference

- [Sandbox API](https://sandbox-sdk.app/docs/reference/sandbox): Every export of @opencoredev/sandbox-sdk and every member of a sandbox handle, with parameters, defaults, and return types.
- [Native API](https://sandbox-sdk.app/docs/reference/native): Call any provider endpoint the SDK doesn't wrap with box.native.request and box.native.fetch, use the official SDK on demand with box.native.sdk, and make account-level calls with provider.api.
- [Agent tools](https://sandbox-sdk.app/docs/reference/agent-tools): sandboxTools for the AI SDK, Mastra, and the OpenAI Agents SDK. Tool list, parameters, output format, and options.
- [Errors](https://sandbox-sdk.app/docs/reference/errors): SandboxError, its codes, and when each one happens. A non-zero exit code is never an error.
- [Capabilities](https://sandbox-sdk.app/docs/reference/capabilities): The full capability matrix. Which options and methods each provider accepts, the exact limits, how TypeScript gates optional methods, and how to check at runtime.
- [Benchmarks](https://sandbox-sdk.app/docs/reference/benchmarks): Measure cold start, command latency, file transfer, previews, and SDK overhead on each provider with the bun bench harness in the repo.
- [Security](https://sandbox-sdk.app/docs/reference/security): What Sandbox SDK protects and what it leaves to the provider. Trust boundaries, keys, secret redaction, network policy, agent tool limits, previews, and reporting a vulnerability.
- [FAQ](https://sandbox-sdk.app/docs/reference/faq): Answers to common questions about Sandbox SDK. Pricing, providers, keys, browsers, edge runtimes, Docker, failures, and how it compares to calling a provider directly.

## Agent skills

- [sandbox-sdk](https://sandbox-sdk.app/docs/.well-known/agent-skills/sandbox-sdk/SKILL.md): Read the Sandbox SDK docs instead of answering from memory. Sandboxes for your agents and your users. Any provider, one line. One TypeScript API over Docker, agentOS, E2B, Vercel Sandbox, Daytona, Upstash Box, Railway, Boat, Sandboxer, Tenki, Superserve, boxd, and Freestyle, called with your own keys. Use when a task involves Sandbox SDK: how it works, how to set it up or configure it, or its API.

## Agent resources

- [llms-full.txt](https://sandbox-sdk.app/docs/llms-full.txt): The full Markdown of every page in one file.
- [Page Markdown](https://sandbox-sdk.app/docs/index.md): Append `.md` to any page URL to fetch that page as raw Markdown.
- [JSON API](https://sandbox-sdk.app/docs/api/docs/pages.json): Page index of the JSON docs API; each entry links the page's JSON and Markdown forms. Described by the OpenAPI document at https://sandbox-sdk.app/docs/openapi.json.
- [Agent skills](https://sandbox-sdk.app/docs/.well-known/agent-skills/index.json): Agent Skills discovery index of the skills this site publishes.
- [API catalog](https://sandbox-sdk.app/docs/.well-known/api-catalog): RFC 9727 linkset of the APIs documented here.
- [AI catalog](https://sandbox-sdk.app/docs/.well-known/ai-catalog.json): ARD manifest of the agent-facing resources on this site (MCP server, skills, APIs).
- [agent-readability.json](https://sandbox-sdk.app/docs/agent-readability.json): Manifest of every agent-facing artifact on this site.
- [Sitemap](https://sandbox-sdk.app/docs/sitemap.xml): Every indexable page URL with its last-modified date.