Sandboxes locales

Trois sandboxes exécutent les commandes de l'agent sur la machine qui exécute l'agent, sans le rôle cloud_user : LocalDockerSandbox dans un conteneur Docker, BashkitSandbox dans un interpréteur Bash intégré au processus et DangerousLocalSandbox directement sur la machine hôte. Utilisez-les pour développer et tester ; déployez avec MistralSandbox.

LocalDockerSandbox() exécute chaque session dans un conteneur Docker sur la machine qui exécute l'agent. Utilisez cette sandbox pour développer et tester un agent localement, en développement ou en CI, avec une isolation réelle par conteneur et Python, sans le rôle cloud_user. Elle nécessite un démon Docker sur la même machine que le processus de l'agent, ce dont un déploiement géré par Mistral ne dispose pas. Passez donc à MistralSandbox avant de déployer.

Installez le package Python docker et démarrez un démon Docker :

uv add docker

uv add docker

from mistralai import agents

agent = agents.Agent(
    model="mistral-large-4",
    name="docker-agent",
    environment=agents.LocalDockerSandbox(),
)

from mistralai import agents

agent = agents.Agent(
    model="mistral-large-4",
    name="docker-agent",
    environment=agents.LocalDockerSandbox(),
)

L'image par défaut est python:3.12-bookworm. L'agent travaille dans /workspace, qui est monté via un bind mount depuis un répertoire propre à chaque session sous ~/.cache/. Le conteneur et ce répertoire sont supprimés à la fermeture de la session.

Pour installer des outils supplémentaires, passez image= ou setup_script=. Avec une image personnalisée via image=, les processus en arrière-plan sont désactivés, sauf si vous définissez supports_background_processes=True. Les Références de LocalDockerSandbox présentent toutes les options et leurs valeurs par défaut.

Le conteneur n'a aucune limite de CPU ou de mémoire et s'exécute sur votre propre démon Docker. N'y exécutez donc que du code que vous acceptez d'exécuter sur votre machine.

Pour disposer d'une sandbox Bash et d'un système de fichiers intégrés au processus, sans Python, installez la dépendance optionnelle et utilisez BashkitSandbox() :

uv add 'mistralai-agents[bashkit]'

uv add 'mistralai-agents[bashkit]'

agents.Agent(model="mistral-large-4", environment=agents.BashkitSandbox())

agents.Agent(model="mistral-large-4", environment=agents.BashkitSandbox())

BashkitSandbox() exécute le shell et les outils de fichiers intégrés, mais ne fournit ni Python ni git. Les processus en arrière-plan ne sont pas disponibles dans cette sandbox. Utilisez MistralSandbox() pour Python, git ou les processus en arrière-plan.

Pour choisir entre BashkitSandbox et MistralSandbox, consultez Sandboxes intégrées. Pour accéder à un service sur votre machine depuis Bashkit, consultez Réseau Bashkit.

DangerousLocalSandbox() exécute les commandes de l'agent directement sur la machine hôte, sans conteneur ni isolation. Utilisez cette sandbox pour exécuter et tester un agent de bout en bout sur votre ordinateur portable ou en CI, sans démon Docker ni conteneur : le shell et les outils de fichiers de l'agent s'exécutent réellement dans un espace de travail propre à chaque session sous ~/.cache/.

agents.Agent(model="mistral-large-4", environment=agents.DangerousLocalSandbox(shell="bash"))

agents.Agent(model="mistral-large-4", environment=agents.DangerousLocalSandbox(shell="bash"))

Cette sandbox n'accepte pas network : les commandes ont accès à tous les réseaux accessibles depuis votre machine.

Pour exécuter l'agent dans l'un de vos dossiers, passez workspace. Les commandes de l'agent s'y exécutent et ses fichiers y restent après la fermeture de la session :

agents.DangerousLocalSandbox(workspace="/abs/path/to/project")

agents.DangerousLocalSandbox(workspace="/abs/path/to/project")

Sans workspace, le dossier propre à la session est supprimé à sa fermeture. delete_on_cleanup modifie ce comportement : consultez les Références de DangerousLocalSandbox.

:::danger Aucune isolation DangerousLocalSandbox exécute les commandes shell générées par le modèle sur votre machine, avec le compte utilisateur qui exécute l'agent, ses autorisations et son environnement. Une sortie du modèle malveillante ou erronée peut lire, modifier ou supprimer vos fichiers, y compris tout identifiant d'accès visible par ce processus.

• Son utilisation nécessite une activation explicite : définissez ALLOW_DANGEROUS_LOCAL_HOST=1, sinon la création de la sandbox échoue.
• Sa création émet un UserWarning.
• Ne l'activez jamais en production ni dans un environnement partagé.

Pour une isolation par conteneur, utilisez LocalDockerSandbox(). Pour une exécution isolée en production, utilisez MistralSandbox(). :::

Configuration de la sandbox : installez des outils dans la sandbox et définissez une identité git.