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

# Sandbox

**Ajouté dans :** `@mastra/core@1.1.0`

Les Providers de Sandbox permettent aux Agents d’exécuter des commandes shell. Lorsque vous configurez un Sandbox dans un Workspace, les Agents peuvent exécuter des commandes dans le cadre de leurs tâches.

Un Provider de Sandbox exécute les commandes dans un environnement contrôlé :

- **Exécution de commandes** : exécute des commandes shell avec des arguments
- **Processus en arrière-plan** : lance des processus de longue durée, comme des serveurs de développement et des observateurs de fichiers
- **Répertoire de travail** : exécute les commandes depuis un répertoire précis
- **Variables d’environnement** : contrôle les variables disponibles
- **Délais d’expiration** : empêche les commandes longues de rester bloquées
- **Isolation** : propose une isolation facultative au niveau du système d’exploitation pour renforcer la sécurité

> **📹 À regarder:** Regardez la [présentation des Sandboxes distants de Mastra](https://www.youtube.com/watch?v=Ix2X-sjVXjw) pour découvrir comment ils fournissent aux Agents un ordinateur isolé dans lequel travailler.

## Providers pris en charge

- [`LocalSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/local-sandbox) : exécute les commandes sur la machine locale
- [`AgentCoreRuntimeSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/agentcore-runtime-sandbox) : exécute les commandes dans des sessions AWS Bedrock AgentCore Runtime
- [`AppleContainerSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/apple-container-sandbox) : exécute les commandes dans des conteneurs Linux OCI locaux au moyen de la CLI `container` d’Apple
- [`BlaxelSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/blaxel-sandbox) : exécute les commandes dans des Sandboxes cloud Blaxel isolés
- [`DaytonaSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/daytona-sandbox) : exécute les commandes dans des Sandboxes cloud Daytona isolés
- [`DockerSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/docker-sandbox) : exécute les commandes dans des conteneurs Docker de longue durée sur la machine locale
- [`E2BSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/e2b-sandbox) : exécute les commandes dans des Sandboxes cloud E2B isolés
- [`ModalSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/modal-sandbox) : exécute les commandes dans des Sandboxes cloud Modal isolés
- [`PlatformSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/platform-sandbox) : exécute les commandes dans un Sandbox associé à un environnement de la plateforme Mastra
- [`RailwaySandbox`](https://mastra.zisheng.pro/fr/reference/workspace/railway-sandbox) : exécute les commandes dans des Sandboxes cloud Railway isolés et éphémères
- [`VercelSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/vercel-sandbox) : exécute les commandes dans une microVM Firecracker Vercel Sandbox éphémère
- [`VercelServerlessSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/vercel-serverless) : exécute les commandes sous forme de fonctions serverless Vercel sans état

## Utilisation de base

Créez un Workspace doté d’un Sandbox et attribuez-le à un Agent. Celui-ci peut alors exécuter des commandes shell :

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
  }),
  sandbox: new LocalSandbox({
    workingDirectory: './workspace',
  }),
})

const agent = new Agent({
  id: 'dev-agent',
  model: 'openai/gpt-5.6-sol',
  instructions: 'You are a helpful development assistant.',
  workspace,
})

// The agent now has the execute_command tool available
const response = await agent.generate('Run `ls -la` in the workspace directory')
```

Consultez la [référence de `LocalSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/local-sandbox) pour découvrir les options de configuration, notamment l’isolation de l’environnement et le Sandbox natif du système d’exploitation.

## Sandbox dynamique

L’option `sandbox` accepte une fonction de résolution à la place d’une instance statique. Cette fonction reçoit `requestContext` et renvoie un Sandbox pour chaque requête. Un même Workspace peut ainsi fournir différents Sandboxes selon l’identité, le rôle ou le locataire de l’appelant.

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace, LocalSandbox } from '@mastra/core/workspace'

const workspace = new Workspace({
  sandbox: ({ requestContext }) => {
    const userId = requestContext.get('user-id') as string
    return new LocalSandbox({
      workingDirectory: `/workspaces/${userId}`,
    })
  },
})

const agent = new Agent({
  id: 'multi-tenant-agent',
  model: 'your-provider/your-model',
  workspace,
})
```

Chaque requête résout son propre Sandbox au moment de l’exécution du Tool :

```typescript
import { RequestContext } from '@mastra/core/request-context'

// User Alice — commands run in /workspaces/alice
const aliceCtx = new RequestContext([['user-id', 'alice']])
await agent.generate('List files in cwd', { requestContext: aliceCtx })

// User Bob — commands run in /workspaces/bob
const bobCtx = new RequestContext([['user-id', 'bob']])
await agent.generate('List files in cwd', { requestContext: bobCtx })
```

Par défaut, les instructions du Workspace décrivent le Sandbox d’exécution à l’aide d’un texte indicatif stable. Consultez la section [Instructions du Workspace](#workspace-instructions) pour inclure des informations concrètes propres à chaque requête.

La fonction de résolution peut également être asynchrone, par exemple pour rechercher la configuration d’un locataire dans une base de données :

```typescript
const workspace = new Workspace({
  sandbox: async ({ requestContext }) => {
    const tenant = await db.getTenant(requestContext.get('tenant-id'))
    return new LocalSandbox({ workingDirectory: tenant.workspacePath })
  },
})
```

### Responsabilité du cycle de vie

Lorsque le Sandbox est une instance statique, `workspace.init()` appelle sa méthode `start()` et `workspace.destroy()` appelle sa méthode `destroy()`. Avec une fonction de résolution, le Workspace ne possède aucune instance à gérer lors de sa construction : l’appelant est responsable du cycle de vie du Sandbox renvoyé.

La fonction de résolution doit renvoyer un Sandbox prêt à l’emploi, soit déjà démarré, soit capable de traiter des appels sans démarrage explicite. L’appelant est également responsable du moment où les Sandboxes renvoyés sont nettoyés.

Le nettoyage peut être effectué par requête, locataire ou utilisateur. Il peut également s’inscrire dans un pool de Sandboxes de longue durée. `workspace.destroy()` ne détruit pas les Sandboxes renvoyés par la fonction de résolution.

> **Remarque:** Les fonctions de résolution de `sandbox` sont incompatibles avec `mounts` et `lsp: true`. Ces deux options nécessitent une instance concrète de Sandbox lors de la construction. Les combiner avec une fonction de résolution lève donc une erreur `INVALID_CONFIG` pour `mounts`, ou désactive LSP en affichant un avertissement pour `lsp: true`.

### Enregistrement des Tools

Avec un Sandbox statique, le Workspace examine l’instance pour déterminer les Tools à enregistrer. Avec une fonction de résolution, le Workspace suppose que toutes les fonctionnalités sont disponibles et enregistre `execute_command` (avec la prise en charge de `background`), `get_process_output` et `kill_process`. Si le Sandbox résolu n’implémente pas une fonctionnalité, l’environnement d’exécution lève une erreur `SandboxFeatureNotSupportedError` explicite.

### Continuité des processus en arrière-plan

Les processus en arrière-plan peuvent survivre à un seul appel de Tool. `get_process_output` et `kill_process` doivent donc atteindre le même Sandbox que celui qui a démarré le processus. Par défaut, un Sandbox résolu est mis en cache pour chaque requête. Pour assurer la continuité entre les requêtes de suivi, par exemple lors d’un tour ultérieur de la conversation, définissez `sandboxCacheKey` sur un identifiant stable. Le Sandbox résolu est alors mis en cache selon cette clé plutôt que selon la requête :

```typescript
const workspace = new Workspace({
  sandbox: ({ requestContext }) => resolveSandbox(requestContext),
  sandboxCacheKey: ({ requestContext }) => requestContext.get('thread-id') as string,
})
```

Sans `sandboxCacheKey`, la fonction de résolution doit elle-même renvoyer le même Sandbox pour les appels de suivi qui partagent un locataire, un utilisateur ou une session.

Lorsqu’un Sandbox mis en cache n’est plus nécessaire, détruisez-le dans votre propre code de gestion du cycle de vie, puis appelez `workspace.clearSandboxCache(cacheKey)` pour supprimer l’entrée du cache du Workspace. Appelez `workspace.clearSandboxCache()` pour supprimer toutes les entrées de Sandbox indexées par une clé.

### Instructions du Workspace

Les instructions du Workspace décrivent l’environnement dans le message système de l’Agent. Avec une fonction de résolution de Sandbox, le Workspace n’appelle pas cette fonction pour construire les instructions. Il émet un texte indicatif stable : la construction du prompt ne provisionne donc jamais un Sandbox appartenant à l’appelant, et le message système reste cohérent entre les requêtes, ce qui préserve l’efficacité du cache des prompts.

Pour inclure des informations concrètes sur le Sandbox propres à chaque requête, définissez `instructions.dynamicSandbox` sur `'resolve'` :

```typescript
const workspace = new Workspace({
  sandbox: ({ requestContext }) => resolveSandbox(requestContext),
  instructions: { dynamicSandbox: 'resolve' },
})
```

`'resolve'` appelle la fonction de résolution à chaque requête, ce qui peut provisionner le Sandbox et rend le message système propre à la requête. Vous pouvez plutôt transmettre une fonction afin de renvoyer un texte personnalisé à partir de `requestContext` sans résoudre le Sandbox :

```typescript
const workspace = new Workspace({
  sandbox: ({ requestContext }) => resolveSandbox(requestContext),
  instructions: {
    dynamicSandbox: ({ requestContext }) =>
      `Sandbox scoped to tenant ${requestContext.get('tenant-id')}.`,
  },
})
```

## Tools des Agents

Lorsque vous configurez un Sandbox dans un Workspace, les Agents reçoivent le Tool `execute_command` pour exécuter des commandes shell.

Si votre Provider de Sandbox prend en charge l’exécution de processus en arrière-plan, le Tool `execute_command` accepte également `background: true` pour démarrer des processus de longue durée, et deux Tools supplémentaires sont enregistrés :

| Tool                 | Description                                                                                                                                                                                                       |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `execute_command`    | Exécute une commande shell. Renvoie stdout, stderr et le code de sortie. Prend en charge `background: true` pour lancer un processus de longue durée et renvoyer un PID.                                          |
| `get_process_output` | Récupère stdout, stderr et l’état d’un processus en arrière-plan à partir de son PID. Prend en charge `tail` pour limiter le nombre de lignes renvoyées et `wait: true` pour bloquer jusqu’à la fin du processus. |
| `kill_process`       | Arrête un processus en arrière-plan à partir de son PID. Renvoie la sortie récente.                                                                                                                               |

Ces Tools sont enregistrés automatiquement. Consultez la [référence de la classe Workspace](https://mastra.zisheng.pro/fr/reference/workspace/workspace-class) pour obtenir la liste complète de leurs noms.

## Callbacks des processus en arrière-plan

Lorsque des Agents démarrent des processus en arrière-plan au moyen du Tool `execute_command`, vous pouvez recevoir des callbacks de cycle de vie pour stdout, stderr et la fin du processus. Configurez-les au moyen de l’option `backgroundProcesses` du Tool `execute_command` :

```typescript
import { Workspace, LocalSandbox, WORKSPACE_TOOLS } from '@mastra/core/workspace'

const workspace = new Workspace({
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  tools: {
    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
      backgroundProcesses: {
        onStdout: (data, { pid }) => console.log(`[${pid}] ${data}`),
        onStderr: (data, { pid }) => console.error(`[${pid}] ${data}`),
        onExit: ({ pid, exitCode }) => console.log(`Process ${pid} exited: ${exitCode}`),
      },
    },
  },
})
```

Ces callbacks sont déclenchés pour tous les processus en arrière-plan démarrés par l’Agent au moyen du Tool `execute_command`.

### Signal d’abandon

Par défaut, les processus en arrière-plan héritent du signal d’abandon de l’Agent et sont arrêtés lorsque celui-ci se déconnecte. Contrôlez ce comportement avec l’option `abortSignal` :

- **`undefined`** (par défaut) : utilise le signal d’abandon de l’Agent
- **`AbortSignal`** : utilise un signal personnalisé
- **`null` ou `false`** : désactive l’abandon ; les processus persistent après l’arrêt de l’Agent

```typescript
import { Workspace, LocalSandbox, WORKSPACE_TOOLS } from '@mastra/core/workspace'

const workspace = new Workspace({
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  tools: {
    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
      backgroundProcesses: {
        abortSignal: null, // Processes survive agent disconnection
      },
    },
  },
})
```

Utilisez `null` ou `false` pour les Sandboxes cloud, par exemple E2B, Daytona ou Modal, dans lesquels les processus doivent survivre à l’Agent.

> **Remarque:** Pour découvrir l’API complète de `SandboxProcessManager`, notamment le lancement programmatique de processus, la lecture de leur sortie et l’envoi de données à stdin, consultez la [référence de `SandboxProcessManager`](https://mastra.zisheng.pro/fr/reference/workspace/process-manager).

## Voir aussi

- [Référence de `SandboxProcessManager`](https://mastra.zisheng.pro/fr/reference/workspace/process-manager)
- [Référence de `AgentCoreRuntimeSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/agentcore-runtime-sandbox)
- [Référence de `AppleContainerSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/apple-container-sandbox)
- [Référence de `DaytonaSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/daytona-sandbox)
- [Référence de `E2BSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/e2b-sandbox)
- [Référence de `LocalSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/local-sandbox)
- [Référence de `ModalSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/modal-sandbox)
- [Référence de `VercelSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/vercel-sandbox)
- [Référence de `VercelServerlessSandbox`](https://mastra.zisheng.pro/fr/reference/workspace/vercel-serverless)
- [Présentation de Workspace](https://mastra.zisheng.pro/fr/docs/workspace/overview)
- [Système de fichiers](https://mastra.zisheng.pro/fr/docs/workspace/filesystem)