@opencoredev/sandbox-sdk weekly downloads statistics

Sandbox SDK

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.

Coming from 0.2? 1.0 changes the API. Upgrade from 0.2 walks through each change.

Install

npm install @opencoredev/sandbox-sdk

That is the whole install for E2B, Daytona, Freestyle, Superserve, Boat, and Sandboxer, which call the provider's HTTP API directly. Vercel, Upstash Box, Railway, Tenki, boxd, and agentOS also need the provider's package, for example npm install @vercel/sandbox. The peer packages table lists every one. Those 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):

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 sandbox, 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. No other package needed.
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 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, if it has one. 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.

import { createSandbox, type Sandbox } from "@opencoredev/sandbox-sdk";
import type { Provider } from "@opencoredev/sandbox-sdk/provider";

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 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

Import each provider from its own subpath. The root entry never loads a provider SDK, and constructing a factory performs no I/O. The capability matrix lists each provider's peer package, capabilities, limits, and preview behavior, and a script checks it against this package's source.…