Sandbox setup
A fresh sandbox holds only what its image ships. You add tools with a setup script or another
image, and a git identity with a sandbox hook. The
examples use MistralSandbox; Local sandboxes shows the same options on
LocalDockerSandbox.
Image and setup
The default image is the SDK's default sandbox image, pinned by digest in each SDK release. It is
Debian with Python 3.12, git, gh, curl, jq, ripgrep, Node 22 with pnpm, uv and
pre-commit. Commands run as appuser, with no sudo, so a setup script cannot install system
packages with apt-get.
To bring your own tools, set setup_script to install them when the sandbox starts, or set
image to a different one:
agents.MistralSandbox(
setup_script="pip install --quiet pandas",
setup_script_timeout_seconds=600,
network=agents.Network.all(), # pip needs outbound access
)
agents.MistralSandbox(image="ghcr.io/your-org/agent-sandbox:1.0")The setup script runs once, before the agent's first command. If it exits non-zero, the sandbox is deleted and the session fails.
A custom image must be public, and it must provide a shell and python3. With a custom image,
background processes are off unless you set
supports_background_processes=True.
Credentials
To let the sandbox call an external service, use a header binding: the credential never enters the sandbox.
Set a git identity
A fresh sandbox has no git identity, so git commit fails until something sets user.name and
user.email. Add an agents.pattern.sandbox_hook.GitIdentity sandbox hook to set them when
the sandbox is created:
agent = agents.Agent(
model="mistral-large-4",
environment=agents.MistralSandbox(
hooks=[agents.pattern.sandbox_hook.GitIdentity(name="Acme Bot", email="bot@acme.com")],
),
)The sandbox must have git: the default MistralSandbox image does, and BashkitSandbox does not.
DangerousLocalSandbox refuses GitIdentity, because the hook would overwrite your own
~/.gitconfig.
Common issues
| You see | Cause | Fix |
|---|---|---|
git config failed with exit code 127: bash: line 1: git: command not found | The sandbox has no git, such as BashkitSandbox. | Use MistralSandbox or an image with git. |
DangerousLocalSandbox runs on the host, so it refuses GitIdentity: it would change the host user's own configuration | GitIdentity would overwrite your own git configuration. | Use LocalDockerSandbox or MistralSandbox for git work. |
Next
Sandbox hooks: seed the workspace when the sandbox is created, and save what the agent produced.