E2BSandbox

Executes commands in isolated E2B cloud sandboxes. Provides secure, ephemeral environments with support for mounting cloud storage.

info

For interface details, see WorkspaceSandbox interface.

Installation

npm install @mastra/e2b

Usage

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-5',
  workspace,
});

Constructor parameters

apiKey?:

string

E2B API key. Falls back to E2B_API_KEY environment variable.

timeout?:

number

= 300000 (5 minutes)

Execution timeout in milliseconds

template?:

string | TemplateBuilder | function

Sandbox template specification. Can be a template ID string, a TemplateBuilder, or a function that customizes the default template.

env?:

Record<string, string>

Environment variables to set in the sandbox

runtimes?:

SandboxRuntime[]

= ['node', 'python', 'bash']

Supported runtimes

id?:

string

= Auto-generated

Unique identifier for this sandbox instance

domain?:

string

Domain for self-hosted E2B. Falls back to E2B_DOMAIN env var.

apiUrl?:

string

API URL for self-hosted E2B. Falls back to E2B_API_URL env var.

accessToken?:

string

Access token for authentication. Falls back to E2B_ACCESS_TOKEN env var.

Properties

id:

string

Sandbox instance identifier

name:

string

Provider name ('E2BSandbox')

provider:

string

Provider identifier ('e2b')

status:

ProviderStatus

'pending' | 'initializing' | 'ready' | 'error'

supportsMounting:

boolean

Always true - E2B sandboxes support mounting cloud filesystems

Methods

start()

Initialize and start the sandbox. Creates the E2B sandbox instance and mounts any configured filesystems.

await sandbox.start();

Called automatically on first command execution or by workspace.init().

stop()

Stop the sandbox and release resources.

await sandbox.stop();

destroy()

Clean up sandbox resources completely.

await sandbox.destroy();

executeCommand(command, args?, options?)

Execute a shell command in the sandbox.

const result = await sandbox.executeCommand('ls', ['-la']);
const npmResult = await sandbox.executeCommand('npm', ['install', 'lodash'], {
  timeout: 60000,
  cwd: '/app',
});

Parameters:

command:

string

Command to execute

args?:

string[]

Command arguments

options.timeout?:

number

Execution timeout in milliseconds

options.cwd?:

string

Working directory for the command

options.env?:

Record<string, string>

Additional environment variables

options.onStdout?:

(data: string) => void

Callback for stdout streaming

options.onStderr?:

(data: string) => void

Callback for stderr streaming

canMount(filesystem)

Check if a filesystem can be mounted into this sandbox.

const canMount = sandbox.canMount(s3Filesystem);
// true for S3Filesystem and GCSFilesystem

mount(filesystem, mountPath)

Mount a filesystem into the sandbox at the specified path.

await sandbox.mount(s3Filesystem, '/mnt/data');

unmount(mountPath)

Unmount a previously mounted filesystem.

await sandbox.unmount('/mnt/data');

getMounts()

Get a list of currently mounted filesystems.

const mounts = await sandbox.getMounts();
// [{ path: '/mnt/data', filesystem: 's3' }]

getInfo()

Get sandbox status and resource information.

const info = await sandbox.getInfo();
// { id: '...', name: 'E2BSandbox', provider: 'e2b', status: 'ready', supportsMounting: true }

Mounting Cloud Storage

E2B sandboxes can mount S3 or GCS filesystems, making cloud storage accessible as local directories inside the sandbox. This is useful for:

• Processing large datasets stored in cloud buckets
• Writing output files directly to cloud storage
• Sharing data between sandbox sessions

Using the mounts config

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.

How mounting works

E2B sandboxes use FUSE (Filesystem in Userspace) to mount cloud storage:

• S3/R2: Mounted via s3fs-fuse
• GCS: Mounted via gcsfuse

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.

Custom Templates

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.

Using an existing template

If you have a pre-built template, pass its ID:

const workspace = new Workspace({
  sandbox: new E2BSandbox({
    id: 'dev-sandbox',
    template: 'my-custom-template',
  }),
});

Customizing the default 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 packages
• pipInstall(packages) - Install Python packages
• npmInstall(packages) - Install Node.js packages
• runCmd(command) - Run shell commands
• setEnvs(vars) - Set environment variables
• copy(src, dest) - Copy files into the template

See E2B's template documentation for the full list of available methods.

Pre-building templates

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.

Related

• WorkspaceSandbox interface
• LocalSandbox reference
• S3Filesystem reference
• GCSFilesystem reference
• Workspace overview