Local sandboxes
Three sandboxes run the agent's commands on the machine that runs the agent, with no cloud_user
role: LocalDockerSandbox in a Docker container, BashkitSandbox in an in-process Bash
interpreter, and DangerousLocalSandbox directly on the host. Use them to develop and test; deploy
with MistralSandbox.
Local Docker sandbox
LocalDockerSandbox() runs each session in a Docker container on the machine that runs the agent.
Use it to develop and test an agent locally, in development or CI, with real container isolation
and Python and without the cloud_user role. It needs a Docker daemon next to the agent's process, which a
Mistral-managed deployment does not have, so switch to MistralSandbox before you deploy.
Install the docker Python package and start a Docker daemon:
uv add dockerfrom mistralai import agents
agent = agents.Agent(
model="mistral-large-4",
name="docker-agent",
environment=agents.LocalDockerSandbox(),
)The default image is python:3.12-bookworm. The agent works in /workspace, which is
bind-mounted from a per-session directory under ~/.cache/. The container is removed with that
directory when the session closes.
To install extra tools, pass image= or setup_script=. With a custom image=, background
processes are off unless you set supports_background_processes=True. The
LocalDockerSandbox reference lists
every option and its default.
The container has no CPU or memory limit, and it runs on your own Docker daemon, so keep it to code you are willing to run on your machine.
In-process Bash sandbox
For an in-process Bash and filesystem sandbox without Python, install the optional extra and use
BashkitSandbox():
uv add 'mistralai-agents[bashkit]'agents.Agent(model="mistral-large-4", environment=agents.BashkitSandbox())BashkitSandbox() runs the shell and the built-in file tools, but it does not provide Python or
git. Background processes are not available in this sandbox. Use MistralSandbox() for Python,
git or background processes.
To choose between BashkitSandbox and MistralSandbox, see
Built-in sandboxes. To reach a service on your machine from
Bashkit, see Bashkit network.
Local host sandbox
DangerousLocalSandbox() runs the agent's commands directly on the host machine, with no
container and no isolation. Use it to run and test an agent end to end on your laptop or in CI,
with no Docker daemon and no container: the agent's shell and file tools
run for real in a per-session workspace under ~/.cache/.
agents.Agent(model="mistral-large-4", environment=agents.DangerousLocalSandbox(shell="bash"))It takes no network: commands reach every network your machine reaches.
To run the agent in one of your folders, pass workspace. The agent's commands run there, and its
files stay there after the session closes:
agents.DangerousLocalSandbox(workspace="/abs/path/to/project")Without workspace, the per-session folder is deleted when the session closes. delete_on_cleanup
changes that: see the
DangerousLocalSandbox reference.
No isolation
DangerousLocalSandbox executes model-generated shell commands on your machine, as the user
that runs the agent, with its permissions and environment. A malicious or mistaken model output can
read, write or delete your files, including any credentials visible to that process.
- It is opt-in: set
ALLOW_DANGEROUS_LOCAL_HOST=1, or building the sandbox fails. - Building it emits a
UserWarning. - Never enable it in production or anywhere shared.
For container isolation, use LocalDockerSandbox(). For isolated
execution in production, use MistralSandbox().
Common issues
| You see | Cause | Fix |
|---|---|---|
ModuleNotFoundError: No module named 'docker' when a session starts | LocalDockerSandbox needs the docker package. | Run uv add docker. |
DangerousLocalSandbox runs on the host, so it always has the host's network and cannot enforce another policy: remove the network argument | DangerousLocalSandbox cannot block traffic. | Leave out network=. |
Next
Sandbox setup: install tools in the sandbox and set a git identity.