opencoredev/sandbox-sdk
opencoredev/sandbox-sdk has 115 GitHub stars and 14 forks. GitHot measured +1 stars in 24 hours and +8 in 7 days. Last checked 2026-11-15 15:53 UTC. Last push 2026-11-14.
What you can do
- Run a command, stream its output, time it out - box.run("npm test"), box.$`git checkout ${branch}`
- Read, write, edit and search files - box.files.write(), read(), edit(), search(), upload()
- Start a dev server and wait until it answers - box.start("npm run dev", { ready: { port: 3000 } })
- Get a URL for a port - box.preview(3000)
Measured star growth
- in 24h
- +1
- in 7 days
- +8
- in 15 days
- Update delayed
- in 1 month
- Update delayed
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
One TypeScript API for running code in sandboxes. Write it once, run it on E2B, Daytona, Vercel Sandbox, Upstash Box, Railway, Tenki, Freestyle, Docker, and more.
Developer ToolsREADME.md
OriginalDocs · Quickstart · Providers · npm · Changelog
Sandbox SDK gives your server-side TypeScript one API for creating sandboxes, running commands, editing files and serving previews. The same code runs on 11 cloud providers, including E2B, Daytona, Vercel Sandbox and Upstash Box, or in Docker on your own machine. Switching providers means changing one import.
[!NOTE] Coming from 0.2? 1.0 changes the API. Upgrade from 0.2 walks through each change.
Install
npm install @opencoredev/sandbox-sdk
It needs Node.js 22+ or Bun 1.3+. Each provider's own SDK is an optional peer, so you install only the ones you use, such as npm install e2b.
Quickstart
This runs with no account and no Docker. memory() is an in-process fake sandbox for trying the API and for tests.
import { createSandbox } from "@opencoredev/sandbox-sdk";
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 machine, swap the provider. Nothing else changes.
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.stdout); // "hello from the sandbox\n"
await using deletes a sandbox created without a key when the scope ends, even if your code throws. With a key, it calls close() and leaves the sandbox running; call destroy() when you are done with it. A command that exits non-zero resolves with ok: false instead of throwing.
What a sandbox can do
| Task | API |
|---|---|
| Run a command, stream its output, time it out | box.run("npm test"), box.$`git checkout ${branch}` |
| Read, write, edit and search files | box.files.write(), read(), edit(), search(), upload() |
| Start a dev server and wait until it answers | box.start("npm run dev", { ready: { port: 3000 } }) |
| Get a URL for a port | box.preview(3000) |
| Clone, commit and push without leaking tokens | box.git.clone(), commit(), push() |
| Pause, resume and snapshot | box.pause(), box.resume(), box.snapshot() |
| Find the same sandbox on the next request | createSandbox(provider, { key: "user:123" }) |
Pause and snapshot exist only on providers that support them, and TypeScript knows which ones do. Every failure is a SandboxError with a code you can branch on. The package README covers the full API.
Give an agent a sandbox
sandboxTools turns a sandbox into tools an agent can call: run, read_file, write_file, edit_file, and background process control. Secrets you register never reach the model.
This example uses the AI SDK and E2B. Install them next to the SDK:
npm install ai zod e2b
The model string goes through the Vercel AI Gateway, so set AI_GATEWAY_API_KEY on your server along with E2B_API_KEY. Any AI SDK provider works in its place.
import { generateText, stepCountIs } from "ai";
import { createSandbox } from "@opencoredev/sandbox-sdk";
import { sandboxTools } from "@opencoredev/sandbox-sdk/ai";
import { e2b } from "@opencoredev/sandbox-sdk/e2b";
await using box = await createSandbox(e2b());
await box.git.clone("https://github.com/opencoredev/sandbox-sdk", { dir: "app", depth: 1 });
const { text } = await generateText({
model: "anthropic/claude-opus-5-5",
tools: sandboxTools(box, { root: "/workspace/app" }),
stopWhen: stepCountIs(20),
prompt: "Run the tests and fix the first failure.",
});
The same tools come for Mastra (/mastra), the OpenAI Agents SDK (/openai) and any other framework (/tools). See agent tools for the options.
Providers
| Provider | Import | Install |
|---|---|---|
| E2B | @opencoredev/sandbox-sdk/e2b |
e2b |
| Daytona | @opencoredev/sandbox-sdk/daytona |
@daytonaio/sdk |
| Vercel Sandbox | @opencoredev/sandbox-sdk/vercel |
@vercel/sandbox |
| Upstash Box | @opencoredev/sandbox-sdk/upstash |
@upstash/box |
| Railway | @opencoredev/sandbox-sdk/railway |
railway |
| Tenki | @opencoredev/sandbox-sdk/tenki |
@tenkicloud/sandbox |
| boxd | @opencoredev/sandbox-sdk/boxd |
@boxd-sh/sdk |
| Freestyle | @opencoredev/sandbox-sdk/freestyle |
freestyle |
| Superserve | @opencoredev/sandbox-sdk/superserve |
@superserve/sdk |
| Boat | @opencoredev/sandbox-sdk/boat |
@boatdev/sdk |
| Sandboxer | @opencoredev/sandbox-sdk/sandboxer |
@boatdev/sdk |
| Docker on your machine | @opencoredev/sandbox-sdk/local |
nothing; needs Docker running |
| agentOS | @opencoredev/sandbox-sdk/agentos |
@rivet-dev/agentos-core |
| Memory, for tests | @opencoredev/sandbox-sdk/memory |
nothing |
Compare providers for credentials, capabilities and preview rules. To add your own, implement Provider from @opencoredev/sandbox-sdk/provider and test it with runConformance from @opencoredev/sandbox-sdk/testing.
Guides
- Docker sandbox for AI agents in TypeScript: run an agent's commands in a container, lock it down, then move to a cloud provider.
- E2B self-hosted: E2B Embed, or Docker instead: run E2B on your own machine, or the same sandbox code in Docker.
- E2B SDK and API in TypeScript, with examples: the
e2bpackage, E2B's REST API, and the same task on Daytona.
More on the blog.
Repository
| Path | What it holds |
|---|---|
packages/sdk |
The @opencoredev/sandbox-sdk package |
examples |
Runnable examples, starting with getting-started |
bench |
The provider benchmark harness |
apps/docs |
The documentation site |
apps/web |
The landing page, and the logo and social images in apps/web/brand |
docs |
The 1.0 design spec and provider reference notes |
EARLY_ACCESS.md has per-provider setup and known limits. Release steps are in RELEASING.md. Report bugs in issues.
License
MIT © OpenCore