E2BSandbox

Exécute des commandes dans des Sandboxes cloud E2B isolées. Fournit des environnements sécurisés et éphémères prenant en charge le montage de stockages cloud. Pour plus de détails sur l'interface, consultez l'interface WorkspaceSandbox.

Installation

npm

npm install @mastra/e2b

pnpm

pnpm add @mastra/e2b

Yarn

yarn add @mastra/e2b

Bun

bun add @mastra/e2b

Utilisation

Ajoutez une E2BSandbox à un Workspace et attribuez-la à un 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({
  id: 'dev-agent',
  name: 'dev-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})

Paramètres du constructeur

apiKey?:

string

Clé d'API E2B. Utilise par défaut la variable d'environnement E2B_API_KEY.

timeout?:

number

= 300000 (5 minutes)

Délai d'expiration de l'exécution, en millisecondes

template?:

string | TemplateBuilder | function

Spécification du template de Sandbox. Peut être une chaîne d'identifiant de template, un TemplateBuilder ou une fonction qui personnalise le template par défaut.

env?:

Record<string, string>

Variables d'environnement à définir dans la Sandbox

id?:

string

= Généré automatiquement

Identifiant unique de cette instance de Sandbox

domain?:

string

Domaine d'une instance E2B auto-hébergée. Utilise par défaut la variable d'environnement E2B_DOMAIN.

apiUrl?:

string

URL d'API d'une instance E2B auto-hébergée. Utilise par défaut la variable d'environnement E2B_API_URL.

accessToken?:

string

Token d'accès pour l'authentification. Utilise par défaut la variable d'environnement E2B_ACCESS_TOKEN.

metadata?:

Record<string, unknown>

Métadonnées personnalisées associées à l'instance de Sandbox.

instructions?:

string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)

Instructions personnalisées renvoyées par getInstructions(). Une chaîne remplace entièrement les valeurs par défaut ; une fonction reçoit ces valeurs et peut les étendre ou les personnaliser pour chaque requête. Transmettez une chaîne vide pour supprimer entièrement les instructions.

Propriétés

id:

string

Identifiant de l'instance de Sandbox

name:

string

Nom du Provider ('E2BSandbox')

provider:

string

Identifiant du Provider ('e2b')

status:

ProviderStatus

'pending' | 'initializing' | 'ready' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error'

processes:

E2BProcessManager

Gestionnaire de processus en arrière-plan. Consultez la référence de SandboxProcessManager.

Processus en arrière-plan

E2BSandbox comprend un gestionnaire de processus intégré permettant de lancer et de gérer des processus en arrière-plan. Les processus s'exécutent dans la Sandbox cloud E2B au moyen de la méthode commands.run() du SDK E2B avec 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()

Le gestionnaire de processus E2B permet de se reconnecter aux processus lancés en externe ou avant une reconnexion. Appelez get(pid) avec un PID pour vous connecter à un processus existant :

const handle = await sandbox.processes.get(existingPid)
if (handle) {
  console.log(handle.stdout)
}

Consultez la référence de SandboxProcessManager pour découvrir l'API complète.

Montage d'un Storage cloud

Les Sandboxes E2B peuvent monter des systèmes de fichiers S3, GCS et Azure Blob afin de rendre le Storage cloud accessible sous la forme de répertoires locaux dans la Sandbox. Cela est utile pour :

• Traiter de grands datasets stockés dans des buckets cloud
• Écrire les fichiers de sortie directement dans le Storage cloud
• Partager des données entre les sessions de Sandbox

Utilisation de la configuration mounts

Le moyen le plus simple de monter des systèmes de fichiers consiste à utiliser la configuration mounts du Workspace :

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

Au démarrage de la Sandbox, les systèmes de fichiers sont automatiquement montés aux chemins indiqués. Le code exécuté dans la Sandbox peut alors accéder aux fichiers dans /s3-data et /gcs-data comme s'il s'agissait de répertoires locaux.

Fonctionnement du montage

Les Sandboxes E2B utilisent FUSE (Filesystem in Userspace) pour monter le Storage cloud :

• S3/R2 : monté au moyen de s3fs-fuse
• GCS : monté au moyen de gcsfuse
• Azure Blob : monté au moyen de blobfuse2

La Sandbox E2B installe automatiquement les Tools FUSE requis lors de l'utilisation du montage. Pour des performances optimales, préconstruisez un template personnalisé dans lequel ces Tools sont installés.

Templates personnalisés

Par défaut, lorsqu'aucun template n'est indiqué, E2BSandbox construit automatiquement un template dans lequel s3fs est installé pour prendre en charge le montage S3. Ce template est mis en cache et réutilisé entre les instances de Sandbox.

Pour le montage GCS, gcsfuse est installé automatiquement au moment du montage s'il n'est pas déjà présent. Pour disposer de Tools supplémentaires ou accélérer les démarrages à froid, utilisez des templates personnalisés.

Utilisation d'un template existant

Si vous disposez d'un template préconstruit, transmettez son identifiant :

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

Personnalisation du template par défaut

Transmettez une fonction pour personnaliser le template montable par défaut. Cette fonction reçoit un TemplateBuilder et doit renvoyer le template modifié :

const workspace = new Workspace({
  sandbox: new E2BSandbox({
    template: base =>
      base
        .aptInstall(['ffmpeg', 'imagemagick', 'poppler-utils'])
        .pipInstall(['pandas', 'numpy'])
        .npmInstall(['sharp']),
  }),
})

Le Template Builder prend en charge le chaînage de méthodes avec des opérations telles que :

• aptInstall(packages) - Installe des packages système
• pipInstall(packages) - Installe des packages Python
• npmInstall(packages) - Installe des packages Node.js
• runCmd(command) - Exécute des commandes shell
• setEnvs(vars) - Définit des variables d'environnement
• copy(src, dest) - Copie des fichiers dans le template

Consultez la documentation des templates E2B pour obtenir la liste complète des méthodes disponibles.

Préconstruction des templates

Le template par défaut est construit lors de la première utilisation, puis mis en cache. Pour accélérer les démarrages à froid ou inclure la prise en charge de GCS, vous pouvez préconstruire un 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,
})

Pour accélérer les démarrages à froid avec GCS, préinstallez gcsfuse dans un template personnalisé :

const workspace = new Workspace({
  sandbox: new E2BSandbox({
    id: 'dev-sandbox',
    template: base => base.aptInstall(['gcsfuse']),
  }),
})

Cette opération est facultative : gcsfuse est installé automatiquement au moment du montage s'il n'est pas présent.

Utilisation avec Code Mode

Code Mode permet à un Agent d'écrire un programme TypeScript unique qui orchestre ses Tools. Comme E2B exécute ce programme dans une micro-VM distante, il a besoin d'un transport qui écrit le programme dans le système de fichiers de la Sandbox plutôt que dans celui de l'hôte. @mastra/e2b fournit E2BCodeModeTransport à cet effet. Transmettez-le comme deuxième argument de createCodeMode :

import { createCodeMode } from '@mastra/core/tools'
import { E2BSandbox, E2BCodeModeTransport } from '@mastra/e2b'

const { tool, instructions } = createCodeMode(
  {
    tools: { getWeather, getForecast },
    sandbox: new E2BSandbox({ timeout: 60_000 }),
  },
  new E2BCodeModeTransport(),
)

E2BCodeModeTransport démarre automatiquement la Sandbox si elle ne s'exécute pas, supprime TypeScript sur l'hôte au moyen d'esbuild (afin de fonctionner quelle que soit la version de Node de la Sandbox), exécute node dans la VM, puis nettoie les fichiers du programme. Le StdioCodeModeTransport par défaut de @mastra/core fonctionne uniquement avec les Sandboxes qui partagent le système de fichiers de l'hôte, telles que LocalSandbox.

Voir aussi

• Référence de SandboxProcessManager
• Interface WorkspaceSandbox
• Référence de LocalSandbox
• Référence de S3Filesystem
• Référence de GCSFilesystem
• Référence d'Azure Blob Filesystem
• Présentation de Workspace