docs/src/content/en/reference/workspace/e2b-sandbox.mdx
Executes commands in isolated E2B cloud sandboxes. Provides secure, ephemeral environments with support for mounting cloud storage.
:::info
For interface details, see WorkspaceSandbox interface.
:::
npm install @mastra/e2b
Add an E2BSandbox to a workspace and assign it to an agent:
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { E2BSandbox } from '@mastra/e2b'
const workspace = new Workspace({
sandbox: new E2BSandbox({
id: 'dev-sandbox',
timeout: 60_000, // 60 second timeout (default: 5 minutes)
}),
})
const agent = new Agent({
name: 'dev-agent',
model: 'anthropic/claude-opus-4-6',
workspace,
})
<PropertiesTable content={[ { name: 'apiKey', type: 'string', description: 'E2B API key. Falls back to E2B_API_KEY environment variable.', isOptional: true, }, { name: 'timeout', type: 'number', description: 'Execution timeout in milliseconds', isOptional: true, defaultValue: '300000 (5 minutes)', }, { name: 'template', type: 'string | TemplateBuilder | function', description: 'Sandbox template specification. Can be a template ID string, a TemplateBuilder, or a function that customizes the default template.', isOptional: true, }, { name: 'env', type: 'Record<string, string>', description: 'Environment variables to set in the sandbox', isOptional: true, }, { name: 'id', type: 'string', description: 'Unique identifier for this sandbox instance', isOptional: true, defaultValue: 'Auto-generated', }, { name: 'domain', type: 'string', description: 'Domain for self-hosted E2B. Falls back to E2B_DOMAIN env var.', isOptional: true, }, { name: 'apiUrl', type: 'string', description: 'API URL for self-hosted E2B. Falls back to E2B_API_URL env var.', isOptional: true, }, { name: 'accessToken', type: 'string', description: 'Access token for authentication. Falls back to E2B_ACCESS_TOKEN env var.', isOptional: true, }, ]} />
<PropertiesTable content={[ { name: 'id', type: 'string', description: 'Sandbox instance identifier', }, { name: 'name', type: 'string', description: "Provider name ('E2BSandbox')", }, { name: 'provider', type: 'string', description: "Provider identifier ('e2b')", }, { name: 'status', type: 'ProviderStatus', description: "'pending' | 'initializing' | 'ready' | 'error'", }, { name: 'supportsMounting', type: 'boolean', description: 'Always true - E2B sandboxes support mounting cloud filesystems', }, { name: 'processes', type: 'E2BProcessManager', description: 'Background process manager. See SandboxProcessManager reference.', }, ]} />
E2BSandbox includes a built-in process manager for spawning and managing background processes. Processes run in the E2B cloud sandbox using the E2B SDK's commands.run() with background: true.
const sandbox = new E2BSandbox({ id: 'dev-sandbox' })
await sandbox.start()
// Spawn a background process
const handle = await sandbox.processes.spawn('node server.js', {
env: { PORT: '3000' },
onStdout: data => console.log(data),
})
// Interact with the process
console.log(handle.stdout)
await handle.sendStdin('input\n')
await handle.kill()
The E2B process manager supports reconnecting to processes that were spawned externally or before a reconnection. Call get(pid) with a PID to connect to an existing process:
const handle = await sandbox.processes.get(existingPid)
if (handle) {
console.log(handle.stdout)
}
See SandboxProcessManager reference for the full API.
E2B sandboxes can mount S3 or GCS filesystems, making cloud storage accessible as local directories inside the sandbox. This is useful for:
The simplest way to mount filesystems is through the workspace mounts config:
import { Workspace } from '@mastra/core/workspace'
import { S3Filesystem } from '@mastra/s3'
import { GCSFilesystem } from '@mastra/gcs'
import { E2BSandbox } from '@mastra/e2b'
const workspace = new Workspace({
mounts: {
'/s3-data': new S3Filesystem({
bucket: 'my-s3-bucket',
region: 'us-east-1',
accessKeyId: process.env.AWS_ACCESS_KEY_ID,
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
}),
'/gcs-data': new GCSFilesystem({
bucket: 'my-gcs-bucket',
projectId: 'my-project',
credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
}),
},
sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
})
When the sandbox starts, the filesystems are automatically mounted at the specified paths. Code running in the sandbox can then access files at /s3-data and /gcs-data as if they were local directories.
E2B sandboxes use FUSE (Filesystem in Userspace) to mount cloud storage:
The E2B sandbox automatically installs the required FUSE tools when mounting is used. For best performance, pre-build a custom template with the tools installed.
By default, when no template is specified, E2BSandbox automatically builds a template with s3fs installed for S3 mounting support. This template is cached and reused across sandbox instances.
For GCS mounting, gcsfuse is automatically installed at mount time if not already present. For additional tools or faster cold starts, use custom templates.
If you have a pre-built template, pass its ID:
const workspace = new Workspace({
sandbox: new E2BSandbox({
id: 'dev-sandbox',
template: 'my-custom-template',
}),
})
Pass a function to customize the default mountable template. The function receives a TemplateBuilder and should return the modified template:
const workspace = new Workspace({
sandbox: new E2BSandbox({
template: base =>
base
.aptInstall(['ffmpeg', 'imagemagick', 'poppler-utils'])
.pipInstall(['pandas', 'numpy'])
.npmInstall(['sharp']),
}),
})
The template builder supports method chaining with operations like:
aptInstall(packages) - Install system packagespipInstall(packages) - Install Python packagesnpmInstall(packages) - Install Node.js packagesrunCmd(command) - Run shell commandssetEnvs(vars) - Set environment variablescopy(src, dest) - Copy files into the templateSee E2B's template documentation for the full list of available methods.
The default template is built on first use and cached. For faster cold starts or to include GCS support, you can pre-build a template:
import { createDefaultMountableTemplate } from '@mastra/e2b'
import { Template } from 'e2b'
// Get the default mountable template (includes s3fs)
const { template, id } = createDefaultMountableTemplate()
// Build and save to E2B
const result = await Template.build(template, id)
console.log('Template ID:', result.templateId)
// Use this ID in your E2BSandbox config for instant startup
const sandbox = new E2BSandbox({
template: result.templateId,
})
For faster GCS cold starts, pre-install gcsfuse in a custom template:
const workspace = new Workspace({
sandbox: new E2BSandbox({
id: 'dev-sandbox',
template: base => base.aptInstall(['gcsfuse']),
}),
})
This is optional—gcsfuse is installed automatically at mount time if not present.