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.
UtilisationLien direct vers 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 :
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 automatiqueLien direct vers 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 constructeurLien direct vers Paramètres du constructeur
id?:
workingDirectory?:
env?:
timeout?:
isolation?:
instructions?:
nativeSandbox?:
NativeSandboxConfigLien direct vers nativesandboxconfig
Options de configuration du Sandbox natif du système d’exploitation (utilisées avec isolation: 'seatbelt' ou 'bwrap').
allowNetwork?:
readOnlyPaths?:
readWritePaths?:
seatbeltProfilePath?:
bwrapArgs?:
allowSystemBinaries?:
PropriétésLien direct vers Propriétés
id:
name:
provider:
status:
workingDirectory:
processes:
Résolution des cheminsLien direct vers Résolution des chemins
Chemins relatifs et contexte d’exécutionLien direct vers 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 absolusLien direct vers 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 :
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-planLien direct vers 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.
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 pour découvrir l’API complète.
Méthodes statiquesLien direct vers Méthodes statiques
detectIsolation()Lien direct vers detectisolation
Détecte le meilleur backend d’isolation disponible pour la plateforme actuelle.
const detection = LocalSandbox.detectIsolation()
// { backend: 'seatbelt', available: true, message: 'Seatbelt available on macOS' }
Isolation de l’environnementLien direct vers 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.
// 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’exploitationLien direct vers 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
// 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 SandboxLien direct vers 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 :
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.