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

# DockerSandbox

Exécute des commandes dans des conteneurs Docker sur la machine locale. Utilise des conteneurs de longue durée avec `docker exec` pour exécuter les commandes. Cible le développement local, le CI/CD, les déploiements isolés du réseau et les scénarios sensibles aux coûts où des Sandboxes cloud sont inutiles. 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/docker
```

**pnpm**:

```bash
pnpm add @mastra/docker
```

**Yarn**:

```bash
yarn add @mastra/docker
```

**Bun**:

```bash
bun add @mastra/docker
```

Nécessite l'exécution de [Docker Engine](https://docs.docker.com/engine/install/) sur la machine hôte.

## Utilisation

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

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { DockerSandbox } from '@mastra/docker'

const workspace = new Workspace({
  sandbox: new DockerSandbox({
    image: 'node:22-slim',
  }),
})

const agent = new Agent({
  id: 'dev-agent',
  name: 'dev-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})
```

## Paramètres du constructeur

**id** (`string`): Identifiant unique de cette instance de Sandbox. Utilisé pour la reconnexion fondée sur les labels. (Default: `Généré automatiquement`)

**name** (`string`): Nom d'affichage du conteneur transmis à Docker sous la forme --name. Les caractères ne figurant pas dans \[a-zA-Z0-9\_.-] sont remplacés par - et un préfixe est ajouté si le résultat ne commence pas par un caractère alphanumérique. (Default: ``Le `id` de la Sandbox``)

**image** (`string`): Image Docker à utiliser pour le conteneur. (Default: `'node:22-slim'`)

**command** (`string[]`): Commande d'entrypoint du conteneur. Doit maintenir le conteneur actif pour l'exécution de commandes fondée sur exec. (Default: `['sleep', 'infinity']`)

**env** (`Record<string, string>`): Variables d'environnement à définir dans le conteneur.

**volumes** (`Record<string, string>`): Bind mounts de l'hôte vers le conteneur. Les clés sont les chemins de l'hôte et les valeurs ceux du conteneur.

**network** (`string`): Réseau Docker à rejoindre.

**privileged** (`boolean`): Exécute en mode privilégié. (Default: `false`)

**memory** (`number`): Limite de mémoire en octets. Docker considère 0 comme illimité. Correspond à Docker HostConfig.Memory.

**memorySwap** (`number`): Mémoire totale avec swap, en octets. Correspond à Docker HostConfig.MemorySwap.

**cpuShares** (`number`): Poids relatif des parts de CPU. Correspond à Docker HostConfig.CpuShares.

**cpuQuota** (`number`): Quota de CPU en microsecondes par période. Correspond à Docker HostConfig.CpuQuota.

**cpuPeriod** (`number`): Période du CPU en microsecondes. Correspond à Docker HostConfig.CpuPeriod.

**pidsLimit** (`number`): Nombre maximal d'identifiants de processus dans le conteneur. Correspond à Docker HostConfig.PidsLimit.

**readonlyRootfs** (`boolean`): Monte le système de fichiers racine du conteneur en lecture seule. Correspond à Docker HostConfig.ReadonlyRootfs.

**capDrop** (`string[]`): Fonctionnalités Linux à supprimer. Utilisez \['ALL'] pour toutes les supprimer avant d'en ajouter certaines. Correspond à Docker HostConfig.CapDrop.

**capAdd** (`string[]`): Fonctionnalités Linux à rajouter après la suppression, telles que NET\_BIND\_SERVICE. Correspond à Docker HostConfig.CapAdd.

**securityOpt** (`string[]`): Options de sécurité Docker, telles que \['no-new-privileges:true']. Correspond à Docker HostConfig.SecurityOpt.

**ulimits** (`Array<{ name: string; soft: number; hard: number }>`): Entrées ulimit du conteneur. Correspond à Docker HostConfig.Ulimits.

**tmpfs** (`Record<string, string>`): Chemins et options de montage tmpfs. Correspond à Docker HostConfig.Tmpfs.

**workingDir** (`string`): Répertoire de travail dans le conteneur. (Default: `'/workspace'`)

**labels** (`Record<string, string>`): Labels supplémentaires du conteneur. Les labels Mastra (mastra.sandbox, mastra.sandbox.id) sont toujours inclus.

**timeout** (`number`): Délai d'expiration par défaut des commandes, en millisecondes. (Default: `300000 (5 minutes)`)

**dockerOptions** (`Docker.DockerOptions`): Options de connexion dockerode transmises telles quelles pour les chemins de socket personnalisés, les hôtes distants ou les certificats TLS.

**instructions** (`string | function`): Instructions personnalisées qui remplacent les instructions par défaut renvoyées par getInstructions(). Transmettez une chaîne vide pour supprimer les instructions.

## Propriétés

**id** (`string`): Identifiant de l'instance de Sandbox.

**name** (`string`): Nom du Provider ('DockerSandbox').

**provider** (`string`): Identifiant du Provider ('docker').

**status** (`ProviderStatus`): 'pending' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error'

**container** (`Container`): Instance Container dockerode sous-jacente. Lève SandboxNotReadyError si la Sandbox n'a pas été démarrée.

**processes** (`DockerProcessManager`): Gestionnaire de processus en arrière-plan. Consultez la référence de SandboxProcessManager.

## Processus en arrière-plan

`DockerSandbox` 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 le conteneur au moyen de `docker exec`.

```typescript
const sandbox = new DockerSandbox({ 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()
```

Consultez la [référence de `SandboxProcessManager`](https://mastra.zisheng.pro/fr/reference/workspace/process-manager) pour découvrir l'API complète.

## Variables d'environnement

Définissez les variables d'environnement au niveau du conteneur avec `env`. Des variables propres à chaque commande peuvent également être transmises lors du lancement des processus :

```typescript
const sandbox = new DockerSandbox({
  image: 'node:22-slim',
  env: {
    NODE_ENV: 'production',
    DATABASE_URL: 'postgres://localhost:5432/mydb',
  },
})
```

## Montages bind

Montez des répertoires de l'hôte dans le conteneur au moyen de l'option `volumes` :

```typescript
const sandbox = new DockerSandbox({
  image: 'node:22-slim',
  volumes: {
    '/my/project': '/workspace/project',
    '/shared/data': '/data',
  },
})
```

Les bind mounts sont appliqués lors de la création du conteneur. Les chemins de l'hôte doivent exister avant le démarrage de la Sandbox.

## Renforcement

Utilisez les options de ressources et de renforcement propres à Docker pour limiter le conteneur d'une Sandbox. L'exemple suivant limite la mémoire et le nombre de processus, ainsi que le CPU à un seul cœur au moyen de valeurs `cpuPeriod` et `cpuQuota` identiques. Il supprime les fonctionnalités Linux et rend le système de fichiers racine accessible en lecture seule, avec `/tmp` monté comme espace de travail inscriptible :

```typescript
const sandbox = new DockerSandbox({
  image: 'node:22-slim',
  memory: 512 * 1024 * 1024,
  memorySwap: 512 * 1024 * 1024,
  cpuPeriod: 100_000,
  cpuQuota: 100_000,
  pidsLimit: 256,
  readonlyRootfs: true,
  capDrop: ['ALL'],
  capAdd: ['NET_BIND_SERVICE'],
  securityOpt: ['no-new-privileges:true'],
  ulimits: [{ name: 'nofile', soft: 1024, hard: 2048 }],
  tmpfs: {
    '/tmp': 'rw,noexec,nosuid,size=64m',
  },
})
```

Ces options correspondent directement aux champs Docker `HostConfig` et ne sont pas définies si vous ne les transmettez pas.

Examinez ces compromis avant d'activer le renforcement :

- `readonlyRootfs` : les installations de packages dans le conteneur et les Tools qui écrivent en dehors des chemins montés peuvent échouer. Ajoutez des entrées `tmpfs` pour les chemins de travail inscriptibles tels que `/tmp`, et montez des tmpfs ou des volumes pour les caches des gestionnaires de packages tels que `~/.npm` si nécessaire.
- `capDrop` : la suppression de toutes les fonctionnalités désactive les commandes qui ont besoin de fonctionnalités Linux, notamment `ping` et les opérations de montage. Les Tools reposant sur FUSE sont également désactivés. Rajoutez uniquement les fonctionnalités nécessaires à votre charge de travail.
- `memory` : Docker considère `0` comme illimité. Omettez `memory` ou transmettez `0` uniquement lorsque vous ne souhaitez pas limiter la mémoire.
- `memorySwap` : le comportement de la mémoire et du swap Docker dépend de la configuration de l'hôte et du daemon Docker. Lorsque vous définissez `memory` sans `memorySwap`, Docker autorise par défaut un swap pouvant atteindre deux fois la limite de mémoire. Définissez `memorySwap` sur la même valeur que `memory` pour désactiver le swap du conteneur ; Docker accepte également `-1` pour un swap illimité.
- `pidsLimit` : des valeurs très faibles peuvent perturber les charges `docker exec`, car chaque commande lance des processus supplémentaires dans le conteneur de longue durée.
- `privileged` : les conteneurs privilégiés contournent les contrôles de fonctionnalités et d'options de sécurité. Ne combinez pas `privileged: true` avec des options de fonctionnalité ou de sécurité sauf si la charge de travail l'exige.
- Reconnexion : `DockerSandbox` réutilise un conteneur existant lorsque l'identifiant de la Sandbox correspond et avertit si les valeurs de renforcement `HostConfig` inspectées diffèrent. Détruisez et recréez la Sandbox pour appliquer les nouvelles options de renforcement. Docker peut normaliser les valeurs inspectées et la modification de `memorySwap` lors d'une reconnexion peut déclencher un avertissement si le conteneur d'origine utilisait le comportement de swap par défaut de Docker.
- Docker Desktop : les limites de ressources s'appliquent dans la machine virtuelle Docker Desktop sous macOS et Windows ; les ressources attribuées à la VM peuvent donc limiter celles reçues par les conteneurs.

## Reconnexion

`DockerSandbox` peut se reconnecter aux conteneurs existants en faisant correspondre les labels. Lors de l'appel à `start()`, il recherche un conteneur dont le label `mastra.sandbox.id` correspond à l'identifiant de la Sandbox. S'il en trouve un :

- Un conteneur en cours d'exécution est réutilisé directement.
- Un conteneur arrêté est redémarré.

```typescript
// First run — creates a new container
const sandbox = new DockerSandbox({ id: 'persistent-sandbox' })
await sandbox._start()

// Later — reconnects to the existing container
const sandbox2 = new DockerSandbox({ id: 'persistent-sandbox' })
await sandbox2._start()
```

## Options de connexion Docker

Connectez-vous à des hôtes Docker distants ou utilisez des chemins de socket personnalisés au moyen de `dockerOptions` :

```typescript
// Remote Docker host
const sandbox = new DockerSandbox({
  dockerOptions: {
    host: '192.168.1.100',
    port: 2376,
    ca: fs.readFileSync('ca.pem'),
    cert: fs.readFileSync('cert.pem'),
    key: fs.readFileSync('key.pem'),
  },
})

// Custom socket path
const sandbox = new DockerSandbox({
  dockerOptions: {
    socketPath: '/var/run/docker.sock',
  },
})
```

## 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 d'E2BSandbox](https://mastra.zisheng.pro/fr/reference/workspace/e2b-sandbox)
- [Présentation de Workspace](https://mastra.zisheng.pro/fr/docs/workspace/overview)