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

# AppleContainerSandbox

Exécute des commandes dans des conteneurs Linux OCI locaux via l’interface en ligne de commande [`container`](https://github.com/apple/container) d’Apple. Le Provider démarre un conteneur de longue durée et utilise `container exec` pour les commandes de Workspace. Pour en savoir plus sur l’interface, consultez [l’interface WorkspaceSandbox](https://mastra.zisheng.pro/fr/reference/workspace/sandbox).

## Installation

**npm**:

```bash
npm install @mastra/apple-container
```

**pnpm**:

```bash
pnpm add @mastra/apple-container
```

**Yarn**:

```bash
yarn add @mastra/apple-container
```

**Bun**:

```bash
bun add @mastra/apple-container
```

Nécessite un Mac Apple silicon exécutant macOS 26 ou une version ultérieure, avec l’interface en ligne de commande `container` d’Apple installée. Démarrez le système de conteneurs avant d’utiliser le Provider :

```bash
container system start
```

## Utilisation

Ajoutez un `AppleContainerSandbox` à un Workspace et attribuez-le à un Agent :

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { AppleContainerSandbox } from '@mastra/apple-container'

const workspace = new Workspace({
  sandbox: new AppleContainerSandbox({
    image: 'node:22-slim',
    volumes: {
      '/Users/me/project': '/workspace',
    },
    workingDir: '/workspace',
  }),
})

const agent = new Agent({
  id: 'dev-agent',
  name: 'Dev Agent',
  instructions: 'You are a coding assistant working in this workspace.',
  model: 'anthropic/claude-sonnet-4-6',
  workspace,
})

const response = await agent.generate('Run `node --version`.')
console.log(response.text)
```

## Paramètres du constructeur

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

**name** (`string`): Nom du conteneur Apple transmis à container run --name. Les caractères hors de \[a-zA-Z0-9\_.-] sont remplacés par - et le résultat reçoit un préfixe s’il ne commence pas par un caractère alphanumérique. (Default: ``L’`id` du Sandbox``)

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

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

**env** (`Record<string, string>`): Variables d’environnement à définir dans le conteneur et lors des exécutions de commandes.

**volumes** (`Record<string, string>`): Montages liés de l’hôte vers le conteneur. Les clés sont des chemins hôte, les valeurs sont des chemins de conteneur.

**mounts** (`string[]`): Spécifications brutes de container run --mount.

**network** (`string`): Spécification d’attachement réseau du conteneur Apple.

**publishedPorts** (`string[]`): Spécifications de publication de ports transmises avec --publish.

**publishedSockets** (`string[]`): Spécifications de publication de sockets transmises avec --publish-socket.

**cpus** (`number | string`): Nombre de processeurs à allouer.

**memory** (`string`): Allocation de mémoire, par exemple '1G'.

**platform** (`string`): Plateforme OCI, par exemple 'linux/arm64'.

**arch** (`string`): Architecture de l’image lors de la sélection d’une image multi-architecture.

**os** (`string`): Système d’exploitation de l’image lors de la sélection d’une image multiplateforme.

**rosetta** (`boolean`): Active Rosetta dans le conteneur. (Default: `false`)

**readonlyRootfs** (`boolean`): Monte le système de fichiers racine du conteneur en lecture seule. (Default: `false`)

**ssh** (`boolean`): Transmet le socket de l’agent SSH de l’hôte. (Default: `false`)

**init** (`boolean`): Active le processus init d’Apple dans le conteneur. (Default: `true`)

**virtualization** (`boolean`): Expose les capacités de virtualisation au conteneur. (Default: `false`)

**capAdd** (`string[]`): Capacités Linux à ajouter.

**capDrop** (`string[]`): Capacités Linux à supprimer.

**tmpfs** (`string[]`): Chemins de destination tmpfs transmis avec --tmpfs, par exemple /tmp.

**dns** (`string[]`): Adresses IP des serveurs de noms DNS.

**dnsSearch** (`string[]`): Domaines de recherche DNS.

**noDns** (`boolean`): Ne configure pas DNS dans le conteneur. (Default: `false`)

**labels** (`Record<string, string>`): Étiquettes de conteneur supplémentaires. Les étiquettes Mastra (mastra.sandbox, mastra.sandbox.id) sont toujours incluses.

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

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

**deleteOnDestroy** (`boolean`): Supprime le conteneur Apple lorsque le Sandbox est détruit. Lorsque cette valeur est false, destroy arrête le conteneur à la place. (Default: `true`)

**containerBinary** (`string`): Chemin ou nom de l’interface en ligne de commande de conteneurs Apple. (Default: `'container'`)

**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 ('AppleContainerSandbox').

**provider** (`string`): Identifiant du Provider ('apple-container').

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

**containerId** (`string`): ID du conteneur Apple lorsqu’il est connu ; sinon, nom de conteneur configuré.

## Variables d’environnement

Définissez des variables d’environnement au niveau du conteneur avec `env`. Des variables d’environnement par commande peuvent également être transmises via les options de `executeCommand` :

```typescript
const sandbox = new AppleContainerSandbox({
  image: 'node:22-slim',
  env: {
    NODE_ENV: 'development',
  },
})

await sandbox.executeCommand('node', ['-e', 'console.log(process.env.TASK_ID)'], {
  env: { TASK_ID: '42' },
})
```

## Montages liés

Montez des répertoires hôte dans le conteneur à l’aide de l’option `volumes` :

```typescript
const sandbox = new AppleContainerSandbox({
  image: 'node:22-slim',
  volumes: {
    '/Users/me/project': '/workspace/project',
    '/Users/me/.npm': '/root/.npm',
  },
})
```

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

## Options de ressources et de plateforme

Les options de l’interface en ligne de commande de conteneurs Apple peuvent être transmises au constructeur :

```typescript
const sandbox = new AppleContainerSandbox({
  image: 'node:22-slim',
  volumes: {
    '/Users/me/project': '/workspace',
  },
  cpus: 2,
  memory: '2G',
  platform: 'linux/arm64',
  readonlyRootfs: true,
  tmpfs: ['/tmp'],
})
```

Ces options ne sont appliquées que lors de la création d’un nouveau conteneur. Si le Sandbox se reconnecte à un conteneur existant portant le même nom, détruisez puis recréez le Sandbox pour appliquer les options d’exécution modifiées. L’option `--tmpfs` d’Apple n’accepte que les chemins de conteneur, tels que `/tmp` ; elle n’accepte pas les spécifications d’options de style Docker comme `/tmp:rw,size=256m`. Lorsque `readonlyRootfs` est activé, assurez-vous que `workingDir` pointe vers un chemin fourni par l’image ou par un montage lié. Un tmpfs accessible en écriture est également pris en charge.

## Modèle de sécurité

`AppleContainerSandbox` exécute des conteneurs locaux via le service `container` Apple de l’hôte. Considérez les options du constructeur comme une configuration côté serveur de confiance :

- `volumes`, `mounts` et `publishedSockets` peuvent exposer des chemins hôte au code conteneurisé.
- `publishedPorts` peut exposer des services du conteneur sur l’hôte ou le réseau. Liez-les à `127.0.0.1` lorsque seul un accès local est prévu.
- `ssh` transmet le socket de l’agent SSH de l’hôte.
- `capAdd` et `virtualization` peuvent étendre les capacités du code conteneurisé.
- `containerBinary` est une porte de sortie réservée au constructeur pour du code de confiance et ne fait pas partie du schéma sérialisable du Provider d’éditeur.

Utilisez les montages et capacités les plus restreints dont votre charge de travail a besoin. Les conteneurs existants ne sont reconnectés que s’ils portent des étiquettes Mastra de propriété correspondant à l’ID du Sandbox. Les conteneurs créés par ce Provider incluent également une étiquette de hachage de configuration ; lorsque cette étiquette est présente, la reconnexion échoue si des options d’exécution immuables, telles que l’image, la commande, les montages, les ports, les capacités ou le répertoire de travail, ont changé.

## Limitations

`AppleContainerSandbox` implémente l’exécution de commandes Workspace au premier plan avec `executeCommand()`. Il n’expose pas encore de `SandboxProcessManager` pour les processus d’arrière-plan ou les sessions LSP.

Les délais d’expiration des commandes sont appliqués à l’intérieur du conteneur afin que les commandes expirées soient nettoyées par l’environnement d’exécution du conteneur. Les signaux d’abandon annulent le chemin d’attente de l’interface en ligne de commande de l’hôte et ne doivent pas remplacer les délais d’expiration des commandes lorsque le nettoyage dans le conteneur est important.

## Reconnexion

`AppleContainerSandbox` se reconnecte en inspectant un conteneur portant le nom configuré. Lorsque `start()` est appelé :

- Un conteneur en cours d’exécution est réutilisé.
- Un conteneur arrêté est redémarré.
- Un conteneur absent est créé à partir de l’image configurée.
- Un conteneur portant le nom configuré, mais dépourvu d’étiquettes Mastra de propriété correspondantes, échoue au lieu d’être géré.
- Un conteneur appartenant à Mastra dont l’étiquette de hachage de configuration ne correspond pas aux options d’exécution immuables échoue au lieu d’être réutilisé.

```typescript
const sandbox = new AppleContainerSandbox({ id: 'persistent-sandbox' })
await sandbox.start()

const sandbox2 = new AppleContainerSandbox({ id: 'persistent-sandbox' })
await sandbox2.start()
```

## Provider d’éditeur

Enregistrez le Provider auprès de `MastraEditor` pour hydrater les configurations de Sandbox stockées :

```typescript
import { MastraEditor } from '@mastra/editor'
import { appleContainerSandboxProvider } from '@mastra/apple-container'

const editor = new MastraEditor({
  sandboxes: {
    [appleContainerSandboxProvider.id]: appleContainerSandboxProvider,
  },
})
```

## Pages associées

- [Interface WorkspaceSandbox](https://mastra.zisheng.pro/fr/reference/workspace/sandbox)
- [Référence DockerSandbox](https://mastra.zisheng.pro/fr/reference/workspace/docker-sandbox)
- [Référence LocalSandbox](https://mastra.zisheng.pro/fr/reference/workspace/local-sandbox)
- [Présentation de Workspace](https://mastra.zisheng.pro/fr/docs/workspace/overview)