Mistral sandbox

MistralSandbox() gives each session its own Linux container, run on Mistral Cloud. The container has Python, a shell and a writable /workspace, and it is deleted when the session closes. Use it for every deployed agent that needs a sandbox: it is the only built-in sandbox with container isolation that runs in a Mistral-managed deployment.

from mistralai import agents

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

from mistralai import agents

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

Install the sandbox extra:

uv add 'mistralai-agents[koyeb]'

uv add 'mistralai-agents[koyeb]'

Without it, agents info and agents serve stop and tell you to install it, and agent.run() raises an error that names the extra.

The identity that creates the sandbox needs the cloud_user workspace role: the owner of MISTRAL_API_KEY in your process and under agents serve, and the deployment's service account under agents deploy. Ask an admin to give you the role in the admin console (Organization > Workspaces > your workspace > Members), where it is shown as Mistral Cloud User. agents deploy gives it to that service account when you, the deployer, have it.

Every session that uses the sandbox runs one Mistral Cloud instance. Three options set its size and how long it stays up:

agents.MistralSandbox(
    instance_type="large",       # instance size; defaults to "medium"
    idle_timeout_seconds=300,    # sleep after 5 idle minutes; 0 (the default) never sleeps
    ttl_seconds=2 * 60 * 60,     # delete after 2 hours at most; defaults to 24 hours
)

agents.MistralSandbox(
    instance_type="large",       # instance size; defaults to "medium"
    idle_timeout_seconds=300,    # sleep after 5 idle minutes; 0 (the default) never sleeps
    ttl_seconds=2 * 60 * 60,     # delete after 2 hours at most; defaults to 24 hours
)

ttl_seconds is a backstop: a session deletes its sandbox when it closes, and if it never does, for example because the deployment did not come back after a crash, Mistral Cloud deletes the sandbox after ttl_seconds. A session whose sandbox is deleted while it runs fails, so keep ttl_seconds above your longest session.

The MistralSandbox reference lists every option.

Only the default region, nl-north-1, can block traffic. In any other region, the sandbox runs only with network=agents.Network.all(), and any other policy stops the session from starting. So pick another region only for an agent that may reach every network:

agents.MistralSandbox(region="...", network=agents.Network.all())

agents.MistralSandbox(region="...", network=agents.Network.all())

Local sandboxes: run a sandbox on your machine for tests and CI.