AppleContainerSandbox

Exécute des commandes dans des conteneurs Linux OCI locaux via l’interface en ligne de commande 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.

Installation

npm

npm install @mastra/apple-container

pnpm

pnpm add @mastra/apple-container

Yarn

yarn add @mastra/apple-container

Bun

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 :

container system start

Utilisation

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

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

= Généré automatiquement

Identifiant unique de cette instance de Sandbox.

name?:

string

= L’`id` du Sandbox

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.

image?:

string

= 'node:22-slim'

Image OCI à utiliser pour le conteneur.

command?:

string[]

= ['sleep', 'infinity']

Commande d’initialisation du conteneur. Elle doit maintenir le conteneur actif pour l’exécution de commandes basée sur exec.

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

= false

Active Rosetta dans le conteneur.

readonlyRootfs?:

boolean

= false

Monte le système de fichiers racine du conteneur en lecture seule.

ssh?:

boolean

= false

Transmet le socket de l’agent SSH de l’hôte.

init?:

boolean

= true

Active le processus init d’Apple dans le conteneur.

virtualization?:

boolean

= false

Expose les capacités de virtualisation au conteneur.

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

= false

Ne configure pas DNS dans le conteneur.

labels?:

Record<string, string>

Étiquettes de conteneur supplémentaires. Les étiquettes Mastra (mastra.sandbox, mastra.sandbox.id) sont toujours incluses.

workingDir?:

string

= '/workspace'

Répertoire de travail dans le conteneur.

timeout?:

number

= 300000 (5 minutes)

Délai d’expiration par défaut des commandes, en millisecondes.

deleteOnDestroy?:

boolean

= true

Supprime le conteneur Apple lorsque le Sandbox est détruit. Lorsque cette valeur est false, destroy arrête le conteneur à la place.

containerBinary?:

string

= 'container'

Chemin ou nom de l’interface en ligne de commande de conteneurs Apple.

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 :

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 :

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 :

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é.

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 :

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

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

Pages associées

• Interface WorkspaceSandbox
• Référence DockerSandbox
• Référence LocalSandbox
• Présentation de Workspace