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

# LocalSandbox

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

Exécute des commandes sur le système local. Pour en savoir plus sur l’interface, consultez l’[interface WorkspaceSandbox](https://mastra.zisheng.pro/fr/reference/workspace/sandbox).

## Utilisation

Ajoutez un `LocalSandbox` à un Workspace et attribuez-le à un Agent. L’Agent peut alors exécuter des commandes shell dans le cadre de ses tâches :

```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',
    env: {
      NODE_ENV: 'development',
    },
  }),
})

const agent = new Agent({
  id: 'dev-agent',
  model: 'openai/gpt-5.6-sol',
  workspace,
})

// The agent now has the execute_command tool available
const response = await agent.generate('Run npm install')
```

### Comportement de démarrage automatique

`LocalSandbox` démarre automatiquement lors de la première exécution d’une commande s’il n’est pas déjà en cours d’exécution. Vous pouvez également démarrer explicitement le Sandbox en appelant `workspace.init()` au démarrage de l’application afin d’éviter la latence de la première commande.

## Paramètres du constructeur

**id** (`string`): Identifiant unique de cette instance de Sandbox (Default: `Généré automatiquement`)

**workingDirectory** (`string`): Répertoire d’exécution des commandes. La valeur par défaut est .sandbox/ dans process.cwd() pour assurer l’isolation vis-à-vis des profils Seatbelt. (Default: `process.cwd()/.sandbox/`)

**env** (`NodeJS.ProcessEnv`): Variables d’environnement à définir. PATH est inclus par défaut, sauf s’il est remplacé.

**timeout** (`number`): Délai d’expiration par défaut des opérations, en millisecondes (Default: `30000`)

**isolation** (`'none' | 'seatbelt' | 'bwrap'`): Backend de Sandbox natif du système d’exploitation. 'seatbelt' pour macOS, 'bwrap' pour Linux. (Default: `'none'`)

**instructions** (`string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)`): Instructions personnalisées qui remplacent les instructions par défaut renvoyées par getInstructions(). Transmettez une chaîne pour les remplacer intégralement, ou une fonction pour les étendre avec un accès au requestContext actuel afin de les personnaliser pour chaque requête.

**nativeSandbox** (`NativeSandboxConfig`): Configuration du Sandbox natif (voir NativeSandboxConfig ci-dessous).

## `NativeSandboxConfig`

Options de configuration du Sandbox natif du système d’exploitation (utilisées avec `isolation: 'seatbelt'` ou `'bwrap'`).

**allowNetwork** (`boolean`): Autorise l’accès au réseau depuis les commandes exécutées dans le Sandbox. (Default: `false`)

**readOnlyPaths** (`string[]`): Chemins supplémentaires auxquels autoriser l’accès en lecture seule (les chemins système sont toujours lisibles).

**readWritePaths** (`string[]`): Chemins supplémentaires auxquels autoriser l’accès en lecture-écriture en dehors du répertoire du Workspace.

**seatbeltProfilePath** (`string`): Chemin vers un fichier de profil Seatbelt personnalisé (macOS uniquement). Si vous avez écrit ce fichier, il est utilisé exactement tel quel : Mastra n’y ajoute pas les chemins montés, le profil doit donc déjà autoriser chacun des chemins que vous montez. Si le fichier n’existe pas, un profil par défaut est généré et écrit à cet emplacement ; ce profil généré autorise les chemins montés. Mastra marque les profils qu’il génère afin qu’une exécution ultérieure les régénère au lieu de les considérer comme les vôtres. Pour modifier un profil généré et conserver vos changements, supprimez son commentaire de marquage : le fichier sera alors considéré comme le vôtre et les chemins montés n’y seront plus ajoutés.

**bwrapArgs** (`string[]`): Arguments supplémentaires à transmettre à bwrap (Linux uniquement).

**allowSystemBinaries** (`boolean`): Autorise l’accès en lecture aux chemins standard des binaires système (/bin, /usr/bin, etc.). (Default: `true`)

## Propriétés

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

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

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

**status** (`ProviderStatus`): 'starting' | 'running' | 'stopped' | 'error'

**workingDirectory** (`string`): Répertoire de travail configuré

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

## Résolution des chemins

### Chemins relatifs et contexte d’exécution

Lorsque vous utilisez un chemin relatif pour `workingDirectory`, il est résolu à partir de `process.cwd()`. Dans les projets Mastra, le répertoire de travail actuel varie selon la façon dont vous exécutez votre code :

| Contexte       | Répertoire de travail                                   | `./workspace` est résolu en     |
| -------------- | ------------------------------------------------------- | ------------------------------- |
| `mastra dev`   | `./src/mastra/public/`                                  | `./src/mastra/public/workspace` |
| `mastra start` | `./.mastra/output/`                                     | `./.mastra/output/workspace`    |
| Script direct  | Emplacement depuis lequel vous avez exécuté la commande | Par rapport à cet emplacement   |

Cela peut prêter à confusion lorsqu’un même chemin relatif est résolu vers des emplacements différents.

### Recommandation : utiliser des chemins absolus

Pour obtenir des chemins cohérents dans tous les contextes d’exécution, utilisez une variable d’environnement contenant un chemin absolu :

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

const sandbox = new LocalSandbox({
  workingDirectory: process.env.WORKSPACE_PATH!,
})
```

Définissez `WORKSPACE_PATH` dans votre environnement sur un chemin absolu tel que `/home/user/my-project/workspace`. Ainsi, les commandes s’exécutent depuis un répertoire constant, quelle que soit la façon dont vous lancez votre code.

## Processus en arrière-plan

`LocalSandbox` comprend un gestionnaire de processus intégré permettant de lancer et de gérer des processus en arrière-plan. Ceux-ci s’exécutent en tant que processus enfants sur la machine locale à l’aide de `child_process.spawn`.

```typescript
const sandbox = new LocalSandbox({ workingDirectory: './workspace' })
await sandbox.start()

// Spawn a background process
const handle = await sandbox.processes.spawn('node server.js')

// Read output, send stdin, kill
console.log(handle.stdout)
await handle.sendStdin('input\n')
await handle.kill()
```

Lorsque l’isolation native est activée (`seatbelt` ou `bwrap`), les processus lancés sont eux aussi encapsulés avec le même backend d’isolation.

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

## Méthodes statiques

### `detectIsolation()`

Détecte le meilleur backend d’isolation disponible pour la plateforme actuelle.

```typescript
const detection = LocalSandbox.detectIsolation()
// { backend: 'seatbelt', available: true, message: 'Seatbelt available on macOS' }
```

## Isolation de l’environnement

Par défaut, `LocalSandbox` n’inclut que `PATH` dans l’environnement. Les commandes peuvent ainsi s’exécuter sans exposer accidentellement les clés d’API et les secrets.

```typescript
// Default: only PATH is available (commands work, secrets protected)
const secureSandbox = new LocalSandbox({
  workingDirectory: './workspace',
})

// Explicit: pass specific variables
const sandbox = new LocalSandbox({
  workingDirectory: './workspace',
  env: {
    NODE_ENV: 'development',
    API_URL: 'https://api.example.com',
  },
})

// Full access (use with caution)
const devSandbox = new LocalSandbox({
  workingDirectory: './workspace',
  env: process.env,
})
```

## Sandbox natif du système d’exploitation

`LocalSandbox` prend en charge le Sandbox natif au niveau du système d’exploitation pour renforcer la sécurité :

- **macOS** : utilise Seatbelt (`sandbox-exec`) pour isoler le système de fichiers et le réseau
- **Linux** : utilise Bubblewrap (`bwrap`) pour isoler les espaces de noms

```typescript
// Detect the best available backend for this platform
const detection = LocalSandbox.detectIsolation()
console.log(detection)
// { backend: 'seatbelt', available: true, message: '...' }

// Enable native sandboxing
const sandbox = new LocalSandbox({
  workingDirectory: './workspace',
  isolation: 'seatbelt', // or 'bwrap' on Linux
  nativeSandbox: {
    allowNetwork: false, // Block network access (default)
    readWritePaths: ['/tmp/extra'], // Additional writable paths
  },
})
```

Lorsque l’isolation est activée :

- Les écritures de fichiers sont limitées au répertoire du Workspace (et aux chemins configurés)
- Les lectures de fichiers sont autorisées partout (nécessaire pour les binaires système)
- L’accès au réseau est bloqué par défaut
- L’isolation des processus empêche toute incidence sur le système hôte

### Emplacement du profil de Sandbox

Lors de l’utilisation de l’isolation Seatbelt sur macOS, `LocalSandbox` génère un fichier de profil dans un dossier `.sandbox-profiles/` situé dans `process.cwd()`, séparément du répertoire de travail :

```text
project/
├── .sandbox/                      # Default working directory (sandboxed)
│   └── ... files created by sandbox
├── .sandbox-profiles/             # Seatbelt profiles (outside sandbox)
│   └── seatbelt-a1b2c3d4.sb       # Hash based on workspace + config
└── ... your project files
```

Le nom du fichier de profil est un hachage du chemin du Workspace et de la configuration. Les Sandbox ayant des paramètres identiques partagent donc le même profil, tandis que les configurations différentes disposent de fichiers distincts. Cela évite les collisions lorsque plusieurs Sandbox s’exécutent simultanément.

Cette séparation empêche les processus exécutés dans le Sandbox de lire ou de modifier leurs propres profils de sécurité. Le profil est créé au démarrage du Sandbox, puis supprimé lors de sa destruction.

## 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)
- [Classe Workspace](https://mastra.zisheng.pro/fr/reference/workspace/workspace-class)
- [Vue d’ensemble du Workspace](https://mastra.zisheng.pro/fr/docs/workspace/overview)