E2B sandbox adapter for SandAgent
npm install @sandagent/sandbox-e2bE2B 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).
@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
``bash`
npm install @sandagent/sandbox-e2b @sandagent/sdk
You'll also need an E2B API key. Sign up at e2b.dev to get one.
`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' },
});
`
`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',
});
`
`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;
}
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
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',
});
`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)
});
`
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,
},
});
- 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.
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.
Apache-2.0