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

# ModalSandbox

Exécute des commandes dans des sandboxes cloud [Modal](https://modal.com) isolées. Fournit des environnements sécurisés et éphémères reposant sur l'infrastructure de Modal. 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/modal
```

**pnpm**:

```bash
pnpm add @mastra/modal
```

**Yarn**:

```bash
yarn add @mastra/modal
```

**Bun**:

```bash
bun add @mastra/modal
```

## Utilisation

Ajoutez une `ModalSandbox` à un Workspace et attribuez-la à un agent :

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { ModalSandbox } from '@mastra/modal'

const workspace = new Workspace({
  sandbox: new ModalSandbox({
    id: 'dev-sandbox',
    baseImage: 'ubuntu:22.04',
    timeoutMs: 60_000,
  }),
})

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

## Authentification

Définissez les identifiants Modal à l'aide de variables d'environnement ou des options du constructeur :

```bash
MODAL_TOKEN_ID=ak-...
MODAL_TOKEN_SECRET=as-...
```

Ou transmettez-les directement :

```typescript
const sandbox = new ModalSandbox({
  tokenId: process.env.MODAL_TOKEN_ID,
  tokenSecret: process.env.MODAL_TOKEN_SECRET,
})
```

Obtenez vos identifiants depuis le [tableau de bord Modal](https://modal.com/settings/tokens).

## Paramètres du constructeur

**id** (`string`): Identifiant ou nom unique de cette sandbox. Utilisé comme nom de sandbox Modal afin de pouvoir s'y reconnecter lors des appels ultérieurs à start(). (Default: `Généré automatiquement`)

**appName** (`string`): Nom de l'application Modal à associer aux sandboxes. (Default: `'mastra'`)

**baseImage** (`string`): Image Docker à utiliser pour la sandbox. (Default: `'ubuntu:22.04'`)

**timeoutMs** (`number`): Durée de vie maximale en temps réel, en millisecondes. La sandbox est arrêtée lorsque ce délai expire, quelle que soit son activité. Le maximum autorisé par Modal est de 24 heures (86\_400\_000). (Default: `300000 (5 minutes)`)

**env** (`Record<string, string>`): Variables d'environnement intégrées à la sandbox lors de sa création.

**workdir** (`string`): Répertoire de travail par défaut dans la sandbox.

**tokenId** (`string`): Identifiant du jeton Modal. Utilise la variable d'environnement MODAL\_TOKEN\_ID à défaut.

**tokenSecret** (`string`): Secret du jeton Modal. Utilise la variable d'environnement MODAL\_TOKEN\_SECRET à défaut.

**instructions** (`string | function`): Instructions personnalisées renvoyées par getInstructions(). Transmettez une chaîne pour remplacer entièrement les instructions par défaut, ou une fonction pour les étendre.

**onStart** (`function`): Hook de cycle de vie appelé une fois que la sandbox atteint l'état d'exécution.

**onStop** (`function`): Hook de cycle de vie appelé avant l'arrêt de la sandbox.

**onDestroy** (`function`): Hook de cycle de vie appelé avant la destruction de la sandbox.

## Propriétés

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

**name** (`string`): Nom du Provider ('ModalSandbox')

**provider** (`string`): Identifiant du Provider ('modal')

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

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

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

## Cycle de vie de la sandbox

- **`_start()`** : tente de se reconnecter à une sandbox en cours d'exécution. Si aucune n'est trouvée, crée une sandbox à partir du snapshot le plus récent (s'il en existe un provenant d'un précédent appel à `_stop()`), ou à partir de baseImage.
- **`_stop()`** : crée un snapshot du système de fichiers, puis arrête la sandbox. Le snapshot est conservé en mémoire dans la même instance pour les prochains démarrages.
- **`_destroy()`** : arrête la sandbox et supprime tout snapshot.

```typescript
const sandbox = new ModalSandbox({
  id: 'dev-sandbox',
  baseImage: 'ubuntu:22.04',
  timeoutMs: 300_000,
})

await sandbox._start()
await sandbox.processes.spawn('npm install')
await sandbox._stop()
await sandbox._start()
```

## Processus d'arrière-plan

`ModalSandbox` comprend un gestionnaire de processus intégré permettant de lancer et de gérer des processus d'arrière-plan. Chaque appel à `spawn()` crée un nouveau `ContainerProcess` par l'intermédiaire de l'API `Sandbox.exec()` du SDK Modal.

```typescript
const sandbox = new ModalSandbox({ id: 'dev-sandbox' })
await sandbox._start()

// Spawn a background process
const handle = await sandbox.processes.spawn('node script.js', {
  env: { PORT: '3000' },
  onStdout: data => console.log(data),
})

// Wait for the process to complete
const result = await handle.wait()
console.log(result.exitCode)

// Kill the process
await handle.kill()
```

> **Remarque:** `sendStdin()` n'est pas pris en charge. Le SDK JS de Modal n'expose pas stdin sur `Sandbox.exec()`.

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

## Ressources associées

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