@e2b/ai-sdk-sandbox weekly downloads statistics

AI SDK - E2B Sandbox

This package is experimental and targets AI SDK 7 (now stable).

Run your agent's code inside E2B sandboxes from the AI SDK. It's the E2B counterpart to @ai-sdk/sandbox-vercel. Drop it into a HarnessAgent, or hand a session straight to your AI SDK tools.

For how the harness itself works, see the AI SDK harness docs.

Setup

npm i @e2b/ai-sdk-sandbox

Set E2B_API_KEY (or pass apiKey in the settings). Calling createE2BSandbox() doesn't reach E2B on its own. The sandbox is created when you call createSession().

Usage

import { createE2BSandbox } from '@e2b/ai-sdk-sandbox';

const e2bSandbox = createE2BSandbox({ template: 'base' });

const sandboxSession = await e2bSandbox.createSession();
// restricted() returns the same sandbox narrowed to the tool-safe surface
// (file I/O, run, spawn) with no lifecycle or network controls — this is what
// you hand an AI SDK tool's execute().
const restrictedSandboxSession = sandboxSession.restricted();

await restrictedSandboxSession.writeTextFile({ path: 'hello.txt', content: 'hi' });

const { stdout } = await restrictedSandboxSession.run({ command: 'cat hello.txt' });
console.log(stdout); // "hi"

await sandboxSession.stop();

restricted() gives you an Experimental_SandboxSession: the same underlying sandbox, narrowed to the tool-facing surface (file I/O, run, spawn), just a view with the infra bits (ports, getPortEndpoint, setNetworkPolicy, stop) removed. That's the security boundary: code you hand the restricted view can't stop the box or change its network policy. Pass it to an AI SDK tool's execute() via experimental_sandbox; the full session stays with the harness. (See the harness docs for the restricted() contract.)

Settings

Everything goes in the object you pass to createE2BSandbox(...):

const e2bSandbox = createE2BSandbox({
  template: 'base',                                // any E2B SandboxOpts
  envs: { NODE_ENV: 'production' },
  timeoutMs: 10 * 60 * 1000,                       // optional; defaults to 30 min
  ports: [3000],                                   // provider option
  setupCommands: ['sudo npm install -g pnpm@9'],   // provider option
});

Any of E2B's [SandboxOpts](https://e2b.dev/docs) (template, envs, metadata, network, and so on) are forwarded straight through. The provider adds two more options that aren't part of E2B's SDK:

option	default	what it does
ports	[]	Ports to advertise on session.ports. The harness bridge binds to the first one. E2B can reach any listening port through getHost, so this is really just the list it advertises.
setupCommands	[]	Commands to run once on a fresh sandbox, before the harness bootstraps. For example, ['sudo npm install -g pnpm@9'] to add pnpm for the claude-code/codex adapters.

Already have a sandbox? Pass it as sandbox to reuse it (handy when you want to share one across sessions). The provider won't touch its lifecycle, so stop() and destroy() become no-ops and cleanup stays yours.

import { createE2BSandbox } from '@e2b/ai-sdk-sandbox';
import { Sandbox } from 'e2b';

const e2bSandbox = createE2BSandbox({
  sandbox: await Sandbox.create({ template: 'base' }),
});

Mid-session network policy

You can tighten or loosen outbound access on a sandbox that's already running:

await sandboxSession.setNetworkPolicy?.({
  mode: 'custom',
  allowedHosts: ['api.example.com'],
  deniedCIDRs: ['169.254.169.254/32'],
});

Request transformations and credential brokering

setRequestTransformations() replaces the managed rules, addRequestTransformations() adds without replacing. Headers in transform.headers are injected by E2B's egress proxy after the request leaves the sandbox, so real credentials never enter it — harness adapters use this automatically for their model API keys. E2B matches rules by host: a path matcher is applied host-wide, and method/queryString/headers matchers are rejected rather than silently widened. E2B allows one transform rule per host, so multiple transformations for the same host are merged into one rule (later headers override earlier ones). Rules match the host exactly (a rule for example.com does not cover www.example.com) and the egress proxy transforms HTTPS requests only. Network policies remain authoritative over which hosts can be reached. See examples/request-transformations.ts for a live end-to-end check.

Running an agent (Claude Code, Codex)

const agent = new HarnessAgent({
  harness: createClaudeCode(),
  sandbox: createE2BSandbox({
    template: 'pnpm-base', // base image + pnpm + 2GB, built via build-template.ts
    ports: [4000],
  }),
});

One thing to know about templates: the claude-code adapter installs its own pinned CLI and bridge inside the sandbox with pnpm (it doesn't use a system claude). That install pulls claude-code's ~238 MB native binary, and pnpm staging it peaks around 1.5 GB — so the sandbox needs pnpm and ~2 GB of RAM. E2B RAM is fixed at template-build time (you can't set it per sandbox), so build a 2 GB template with pnpm baked in via examples/build-template.ts and pass its name. A full, runnable version lives in examples/harness.ts.

Good to know…