Install

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.

Sandbox SDK is one npm package. The core has no runtime dependencies. E2B, Daytona, Freestyle, Superserve, Boat, and Sandboxer need nothing else, because their adapters call the provider’s HTTP API directly. Vercel, Upstash Box, Railway, Tenki, boxd, and agentOS need that provider’s official SDK installed next to it, and you only install the ones you use.

1. Install the package

npm install @opencoredev/sandbox-sdk

pnpm add @opencoredev/sandbox-sdk

yarn add @opencoredev/sandbox-sdk

bun add @opencoredev/sandbox-sdk

That is enough for the Memory provider, which runs in your process, and for Local, which needs Docker running on the same machine.

2. Add a provider SDK, if needed

E2B, Daytona, Freestyle, Superserve, Boat, and Sandboxer need no extra package. For the providers that wrap an SDK, install it next to Sandbox SDK. The adapter loads it the first time that provider does something, so a provider you never call costs nothing. Peer packages lists the package and version range for each one.

npm install @vercel/sandbox

pnpm add @vercel/sandbox

yarn add @vercel/sandbox

bun add @vercel/sandbox

3. Add an agent framework (optional)

Agent tools live on their own subpaths and need their framework and zod. Skip this if you aren’t giving a model tools.

These are optional peer dependencies. Importing the package root never loads them.

Requirements

• Node 22 or newer, or Bun 1.3 or newer.
• ESM only. Use import, not require.
• TypeScript is optional. Types ship with the package.
• A server. Provider keys must never reach a browser bundle, so call the SDK from a route handler, a server action, a worker, or a script.

Bundling

You don’t need a bundler: Node and Bun run the package from node_modules. If your platform bundles server code anyway, as Next.js, Convex, and AWS Lambda builds do, mark the SDK and any provider SDKs you use as external so they load from node_modules at runtime:

esbuild server.ts --bundle --platform=node --format=esm --outfile=dist/server.mjs \
  --external:@opencoredev/sandbox-sdk --external:@vercel/sandbox

In Next.js, use serverExternalPackages, as the Next.js page shows. In Convex, list the packages under node.externalPackages in convex.json.

When the packages have to go inside the bundle, for example because the deployment ships no node_modules, build an ESM bundle with a require shim. Some provider SDKs are CommonJS and call require for Node built-ins, which an ESM bundle doesn’t define. Without the shim, the first provider call fails with Dynamic require of "node:fs" is not supported.

esbuild server.ts --bundle --platform=node --format=esm --outfile=dist/server.mjs \
  --banner:js='import { createRequire } from "node:module"; const require = createRequire(import.meta.url);'

A CommonJS bundle (--format=cjs) needs no shim. Minifying is fine in either format.

What the package exports

Next: the Quickstart.