@sandagent/sandbox-e2b

E2B sandbox adapter for SandAgent - run agents in secure cloud sandboxes.

Use E2B as the execution environment for SandAgent (isolated cloud sandbox with optional persistence and reuse).

Overview

@sandagent/sandbox-e2b provides an E2B-based sandbox implementation for SandAgent. E2B offers secure, isolated cloud environments with:

- Fast startup times
- Persistent storage (up to 30 days when paused)
- Sandbox reuse by name
- Support for custom templates

Installation

``bash
npm install @sandagent/sandbox-e2b @sandagent/sdk
`

You'll also need an E2B API key. Sign up at e2b.dev to get one.

Quick Start

`typescript
import { E2BSandbox } from '@sandagent/sandbox-e2b';
import { SandAgent } from '@sandagent/manager';

// Create sandbox adapter
// Runner is automatically downloaded from npm if runnerBundlePath is not provided
const sandbox = new E2BSandbox({
apiKey: process.env.E2B_API_KEY!,
template: 'base', // E2B template ID
env: {
ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
},
});

// Use with SandAgent
const agent = new SandAgent({
sandbox,
runner: {
kind: 'claude-agent-sdk',
model: 'claude-sonnet-4-20250514',
outputFormat: 'stream',
},
env: {
ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
},
});

const stream = await agent.stream({
messages: [{ role: 'user', content: 'Hello!' }],
workspace: { path: '/workspace' },
});
`

Usage with AI Provider

`typescript
import { createSandAgent } from '@sandagent/sdk';
import { E2BSandbox } from '@sandagent/sandbox-e2b';
import { generateText } from 'ai';

// Runner is automatically downloaded from npm
const sandagent = createSandAgent({
sandbox: new E2BSandbox({
apiKey: process.env.E2B_API_KEY!,
}),
env: {
ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
},
});

const { text } = await generateText({
model: sandagent('sonnet'),
prompt: 'Create a hello world program',
});
`

Configuration Options

$3

`typescript
interface E2BSandboxOptions {
// Required: E2B API key (or set E2B_API_KEY env var)
apiKey?: string;

// E2B template to use (default: "base")
template?: string;

// Sandbox timeout in seconds (default: 3600 = 1 hour)
// Hobby tier: max 1 hour, Pro tier: max 24 hours
timeout?: number;

// Path to runner bundle.mjs (optional)
// If not provided, automatically downloads @sandagent/runner-cli from npm
runnerBundlePath?: string;

// Path to template directory to upload
templatesPath?: string;

// Sandbox name for reuse (optional)
// If provided, will try to find existing sandbox by name
name?: string;

// Environment variables for the sandbox
env?: Record;

// Agent template (default, coder, analyst, researcher)
agentTemplate?: string;

// Working directory inside sandbox (default: '/workspace')
workdir?: string;
}
`

Sandbox Reuse

E2B supports sandbox persistence and reuse:

`typescript
const sandbox = new E2BSandbox({
apiKey: process.env.E2B_API_KEY!,
name: 'my-project-sandbox', // Unique name for this sandbox
// runnerBundlePath is optional - runner is auto-downloaded from npm
});

// First call: creates new sandbox
await sandbox.attach();

// Later calls: reuses existing sandbox by name
await sandbox.attach();
`

E2B Limitations (Beta):
- Sandbox can be paused for up to 30 days
- Continuous runtime limits:
- Hobby tier: max 1 hour
- Pro tier: max 24 hours
- See: https://e2b.dev/docs/sandbox/persistence

Advanced Usage

$3

Upload your own templates to the sandbox:

`typescript
const sandbox = new E2BSandbox({
apiKey: process.env.E2B_API_KEY!,
// runnerBundlePath is optional - runner is auto-downloaded from npm
templatesPath: './templates/coder', // Upload custom template files
agentTemplate: 'coder',
});
`

$3

`typescript
// Development sandbox
const devSandbox = new E2BSandbox({
apiKey: process.env.E2B_API_KEY!,
name: 'dev-sandbox',
});

// Production sandbox
const prodSandbox = new E2BSandbox({
apiKey: process.env.E2B_API_KEY!,
name: 'prod-sandbox',
timeout: 86400, // 24 hours (Pro tier)
});
`

Environment Variables

The sandbox accepts environment variables that will be available to all commands:

`typescript
const sandbox = new E2BSandbox({
apiKey: process.env.E2B_API_KEY!,
env: {
ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
GITHUB_TOKEN: process.env.GITHUB_TOKEN,
DATABASE_URL: process.env.DATABASE_URL,
},
});
`

Requirements

- Node.js 20+
- E2B API key (get one at e2b.dev)
- @sandagent/manager package

Note: @sandagent/runner-cli is automatically downloaded from npm when the sandbox initializes. You don't need to install it locally unless you want to use a custom bundle.

API Reference

$3

Implements the SandboxAdapter interface from @sandagent/manager`.

#### Methods

attach(): Promise

Attaches to an E2B sandbox. If a name is provided and a sandbox with that name exists, connects to it. Otherwise, creates a new sandbox.

getHandle(): SandboxHandle | null

Returns the current sandbox handle if attached, null otherwise.

getEnv(): Record

Returns the environment variables configured for this sandbox.

getAgentTemplate(): string

Returns the agent template name.

getWorkdir(): string

Returns the working directory path.

License

Apache-2.0