DockerSandbox
Exécute des commandes dans des conteneurs Docker sur la machine locale. Utilise des conteneurs de longue durée avec docker exec pour exécuter les commandes. Cible le développement local, le CI/CD, les déploiements isolés du réseau et les scénarios sensibles aux coûts où des Sandboxes cloud sont inutiles. Pour plus de détails sur l'interface, consultez l'interface WorkspaceSandbox.
InstallationLien direct vers Installation
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/docker
pnpm add @mastra/docker
yarn add @mastra/docker
bun add @mastra/docker
Nécessite l'exécution de Docker Engine sur la machine hôte.
UtilisationLien direct vers Utilisation
Ajoutez une DockerSandbox à un Workspace et attribuez-la à un Agent :
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { DockerSandbox } from '@mastra/docker'
const workspace = new Workspace({
sandbox: new DockerSandbox({
image: 'node:22-slim',
}),
})
const agent = new Agent({
id: 'dev-agent',
name: 'dev-agent',
model: 'anthropic/claude-opus-4-7',
workspace,
})
Paramètres du constructeurLien direct vers Paramètres du constructeur
id?:
name?:
--name. Les caractères ne figurant pas dans [a-zA-Z0-9_.-] sont remplacés par - et un préfixe est ajouté si le résultat ne commence pas par un caractère alphanumérique.image?:
command?:
env?:
volumes?:
network?:
privileged?:
memory?:
memorySwap?:
cpuQuota?:
cpuPeriod?:
pidsLimit?:
readonlyRootfs?:
capDrop?:
capAdd?:
securityOpt?:
ulimits?:
tmpfs?:
workingDir?:
labels?:
timeout?:
dockerOptions?:
instructions?:
PropriétésLien direct vers Propriétés
id:
name:
provider:
status:
container:
processes:
Processus en arrière-planLien direct vers Processus en arrière-plan
DockerSandbox comprend un gestionnaire de processus intégré permettant de lancer et de gérer des processus en arrière-plan. Les processus s'exécutent dans le conteneur au moyen de docker exec.
const sandbox = new DockerSandbox({ id: 'dev-sandbox' })
await sandbox._start()
// Spawn a background process
const handle = await sandbox.processes.spawn('node server.js', {
env: { PORT: '3000' },
onStdout: data => console.log(data),
})
// Interact with the process
console.log(handle.stdout)
await handle.sendStdin('input\n')
await handle.kill()
Consultez la référence de SandboxProcessManager pour découvrir l'API complète.
Variables d'environnementLien direct vers Variables d'environnement
Définissez les variables d'environnement au niveau du conteneur avec env. Des variables propres à chaque commande peuvent également être transmises lors du lancement des processus :
const sandbox = new DockerSandbox({
image: 'node:22-slim',
env: {
NODE_ENV: 'production',
DATABASE_URL: 'postgres://localhost:5432/mydb',
},
})
Montages bindLien direct vers Montages bind
Montez des répertoires de l'hôte dans le conteneur au moyen de l'option volumes :
const sandbox = new DockerSandbox({
image: 'node:22-slim',
volumes: {
'/my/project': '/workspace/project',
'/shared/data': '/data',
},
})
Les bind mounts sont appliqués lors de la création du conteneur. Les chemins de l'hôte doivent exister avant le démarrage de la Sandbox.
RenforcementLien direct vers Renforcement
Utilisez les options de ressources et de renforcement propres à Docker pour limiter le conteneur d'une Sandbox. L'exemple suivant limite la mémoire et le nombre de processus, ainsi que le CPU à un seul cœur au moyen de valeurs cpuPeriod et cpuQuota identiques. Il supprime les fonctionnalités Linux et rend le système de fichiers racine accessible en lecture seule, avec /tmp monté comme espace de travail inscriptible :
const sandbox = new DockerSandbox({
image: 'node:22-slim',
memory: 512 * 1024 * 1024,
memorySwap: 512 * 1024 * 1024,
cpuPeriod: 100_000,
cpuQuota: 100_000,
pidsLimit: 256,
readonlyRootfs: true,
capDrop: ['ALL'],
capAdd: ['NET_BIND_SERVICE'],
securityOpt: ['no-new-privileges:true'],
ulimits: [{ name: 'nofile', soft: 1024, hard: 2048 }],
tmpfs: {
'/tmp': 'rw,noexec,nosuid,size=64m',
},
})
Ces options correspondent directement aux champs Docker HostConfig et ne sont pas définies si vous ne les transmettez pas.
Examinez ces compromis avant d'activer le renforcement :
readonlyRootfs: les installations de packages dans le conteneur et les Tools qui écrivent en dehors des chemins montés peuvent échouer. Ajoutez des entréestmpfspour les chemins de travail inscriptibles tels que/tmp, et montez des tmpfs ou des volumes pour les caches des gestionnaires de packages tels que~/.npmsi nécessaire.capDrop: la suppression de toutes les fonctionnalités désactive les commandes qui ont besoin de fonctionnalités Linux, notammentpinget les opérations de montage. Les Tools reposant sur FUSE sont également désactivés. Rajoutez uniquement les fonctionnalités nécessaires à votre charge de travail.memory: Docker considère0comme illimité. Omettezmemoryou transmettez0uniquement lorsque vous ne souhaitez pas limiter la mémoire.memorySwap: le comportement de la mémoire et du swap Docker dépend de la configuration de l'hôte et du daemon Docker. Lorsque vous définissezmemorysansmemorySwap, Docker autorise par défaut un swap pouvant atteindre deux fois la limite de mémoire. DéfinissezmemorySwapsur la même valeur quememorypour désactiver le swap du conteneur ; Docker accepte également-1pour un swap illimité.pidsLimit: des valeurs très faibles peuvent perturber les chargesdocker exec, car chaque commande lance des processus supplémentaires dans le conteneur de longue durée.privileged: les conteneurs privilégiés contournent les contrôles de fonctionnalités et d'options de sécurité. Ne combinez pasprivileged: trueavec des options de fonctionnalité ou de sécurité sauf si la charge de travail l'exige.- Reconnexion :
DockerSandboxréutilise un conteneur existant lorsque l'identifiant de la Sandbox correspond et avertit si les valeurs de renforcementHostConfiginspectées diffèrent. Détruisez et recréez la Sandbox pour appliquer les nouvelles options de renforcement. Docker peut normaliser les valeurs inspectées et la modification dememorySwaplors d'une reconnexion peut déclencher un avertissement si le conteneur d'origine utilisait le comportement de swap par défaut de Docker. - Docker Desktop : les limites de ressources s'appliquent dans la machine virtuelle Docker Desktop sous macOS et Windows ; les ressources attribuées à la VM peuvent donc limiter celles reçues par les conteneurs.
ReconnexionLien direct vers Reconnexion
DockerSandbox peut se reconnecter aux conteneurs existants en faisant correspondre les labels. Lors de l'appel à start(), il recherche un conteneur dont le label mastra.sandbox.id correspond à l'identifiant de la Sandbox. S'il en trouve un :
- Un conteneur en cours d'exécution est réutilisé directement.
- Un conteneur arrêté est redémarré.
// First run — creates a new container
const sandbox = new DockerSandbox({ id: 'persistent-sandbox' })
await sandbox._start()
// Later — reconnects to the existing container
const sandbox2 = new DockerSandbox({ id: 'persistent-sandbox' })
await sandbox2._start()
Options de connexion DockerLien direct vers Options de connexion Docker
Connectez-vous à des hôtes Docker distants ou utilisez des chemins de socket personnalisés au moyen de dockerOptions :
// Remote Docker host
const sandbox = new DockerSandbox({
dockerOptions: {
host: '192.168.1.100',
port: 2376,
ca: fs.readFileSync('ca.pem'),
cert: fs.readFileSync('cert.pem'),
key: fs.readFileSync('key.pem'),
},
})
// Custom socket path
const sandbox = new DockerSandbox({
dockerOptions: {
socketPath: '/var/run/docker.sock',
},
})