> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# E2BSandbox

Exécute des commandes dans des Sandboxes cloud [E2B](https://e2b.dev) 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](https://mastra.zisheng.pro/fr/reference/workspace/sandbox).

## Installation

**npm**:

```bash
npm install @mastra/e2b
```

**pnpm**:

```bash
pnpm add @mastra/e2b
```

**Yarn**:

```bash
yarn add @mastra/e2b
```

**Bun**:

```bash
bun add @mastra/e2b
```

## Utilisation

Ajoutez une `E2BSandbox` à un Workspace et attribuez-la à un Agent :

```typescript
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`): Délai d'expiration de l'exécution, en millisecondes (Default: `300000 (5 minutes)`)

**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`): Identifiant unique de cette instance de Sandbox (Default: `Généré automatiquement`)

**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`.

```typescript
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 :

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

Consultez la [référence de `SandboxProcessManager`](https://mastra.zisheng.pro/fr/reference/workspace/process-manager) 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 :

```typescript
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](https://github.com/s3fs-fuse/s3fs-fuse)
- **GCS** : monté au moyen de [gcsfuse](https://github.com/GoogleCloudPlatform/gcsfuse)
- **Azure Blob** : monté au moyen de [blobfuse2](https://github.com/Azure/azure-storage-fuse)

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 :

```typescript
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é :

```typescript
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](https://e2b.dev/docs/template/defining-template) 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 :

```typescript
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é :

```typescript
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](https://mastra.zisheng.pro/fr/docs/agents/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` :

```typescript
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](https://mastra.zisheng.pro/fr/reference/workspace/process-manager)
- [Interface WorkspaceSandbox](https://mastra.zisheng.pro/fr/reference/workspace/sandbox)
- [Référence de LocalSandbox](https://mastra.zisheng.pro/fr/reference/workspace/local-sandbox)
- [Référence de S3Filesystem](https://mastra.zisheng.pro/fr/reference/workspace/s3-filesystem)
- [Référence de GCSFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/gcs-filesystem)
- [Référence d'Azure Blob Filesystem](https://mastra.zisheng.pro/fr/reference/workspace/azure-blob-filesystem)
- [Présentation de Workspace](https://mastra.zisheng.pro/fr/docs/workspace/overview)