Network access

A sandbox opens no outbound connection unless you allow it: network defaults to agents.Network.none(). Every executable sandbox but DangerousLocalSandbox takes the same two options for what leaves it. NoSandbox takes neither: it opens no connection.

network sets the outbound connections the sandbox can open.
header_bindings lists the credentials the sandbox adds to those connections, such as a token for your private GitHub repositories. See Header binding.

Allow connections

Build network with one of three methods:

agents.Network.none()                                                   # no outbound connection
agents.Network.all()                                                    # every outbound connection
agents.Network.allow(hosts=("api.github.com", "pypi.org"))              # only HTTPS to these hosts

agents.Network.none()                                                   # no outbound connection
agents.Network.all()                                                    # every outbound connection
agents.Network.allow(hosts=("api.github.com", "pypi.org"))              # only HTTPS to these hosts

Pass the policy as the sandbox's network=. The example's MistralSandbox needs the cloud_user role (Requirements) and the koyeb extra.

agents.Agent(
    model="mistral-large-4",
    environment=agents.MistralSandbox(network=agents.Network.all()),
)

agents.Agent(
    model="mistral-large-4",
    environment=agents.MistralSandbox(network=agents.Network.all()),
)

Of the built-in sandboxes, only BashkitSandbox takes Network.allow(): see Bashkit network.

Only bash opens connections, with commands such as curl. With access "files" or "none", the model has no bash, so network limits only your sandbox hooks and setup scripts.

Each sandbox type enforces only some policies. A sandbox refuses a policy it cannot enforce when you build it, so it never runs with weaker limits than you wrote:

Sandbox	`network`	Credentials
`NoSandbox`	`none()`	none
`BashkitSandbox`	`none()`, `all()`, `allow()`	none
`MistralSandbox`	`none()`, `all()`	`GitHubBinding`, `MistralApiBinding`, `WorkspaceHeaderBindings`
`LocalDockerSandbox`	`none()`, `all()`	none
`DangerousLocalSandbox`	always `all()`	none
`experimental.CustomSandbox`	what the subclass declares	what the subclass declares

Bashkit network

To open only the hosts you list, pass Network.allow():

agents.BashkitSandbox(network=agents.Network.allow(hosts=("api.github.com",)))

agents.BashkitSandbox(network=agents.Network.allow(hosts=("api.github.com",)))

Each hosts entry is a host name or an IP address, with an optional :port. Write "pypi.org", not "https://pypi.org": a scheme, a path or a * wildcard raises an error. The sandbox reaches these hosts over HTTPS only. It refuses a plain http:// request to them.

Private and loopback addresses stay refused, even when a host in Network.allow() matches them. To reach a service on your machine or your local network, for example while you test against a local API, turn that off:

agents.BashkitSandbox(
    network=agents.Network.allow(hosts=("localhost:8000",)),
    block_private_ips=False,
)

agents.BashkitSandbox(
    network=agents.Network.allow(hosts=("localhost:8000",)),
    block_private_ips=False,
)

Mistral sandbox network policy

MistralSandbox filters traffic by IP address, so it takes Network.none() (the default) or Network.all(). Network.allow(hosts=...) raises an error.

To open only some IP addresses, pass egress=agents.EgressPolicy.custom(allow_cidrs=...). It opens the addresses you list on top of Network.none(), so you cannot combine it with Network.all(). A /0 range such as 0.0.0.0/0 raises: use Network.all() instead.

agents.MistralSandbox()                               # no outbound access (default)

agents.MistralSandbox(network=agents.Network.all())   # unrestricted

agents.MistralSandbox(
    egress=agents.EgressPolicy.custom(
        allow_cidrs=(
            "203.0.113.10",       # single IPv4 address
            "10.0.0.0/8",         # IPv4 CIDR range
            "2001:db8::/32",      # IPv6 CIDR range
        ),
    ),
)

agents.MistralSandbox()                               # no outbound access (default)

agents.MistralSandbox(network=agents.Network.all())   # unrestricted

agents.MistralSandbox(
    egress=agents.EgressPolicy.custom(
        allow_cidrs=(
            "203.0.113.10",       # single IPv4 address
            "10.0.0.0/8",         # IPv4 CIDR range
            "2001:db8::/32",      # IPv6 CIDR range
        ),
    ),
)

Each allow_cidrs entry is an IPv4 or IPv6 address, or a CIDR range. custom needs at least one entry. Host names and URLs are not accepted; resolve them to addresses first.

Header binding

A header binding adds a credential to the requests that leave the sandbox. The sandbox never sees the value.

agents.Agent(
    model="mistral-large-4",
    environment=agents.MistralSandbox(
        network=agents.Network.all(),
        header_bindings=(agents.GitHubBinding(repos=("your-org/your-repo",)),),
    ),
)

agents.Agent(
    model="mistral-large-4",
    environment=agents.MistralSandbox(
        network=agents.Network.all(),
        header_bindings=(agents.GitHubBinding(repos=("your-org/your-repo",)),),
    ),
)

The token comes from the GitHub connector of the user who starts the session, so the binding needs no secret. A binding must reach its hosts, or building the sandbox raises an error: on MistralSandbox, pass network=agents.Network.all(). The header binding reference lists the other kinds, and the table in Allow connections shows which sandbox supports each.

Common issues

You see	Cause	Fix
`MistralSandbox does not support Network.allow(); pass network=Network.none() or network=Network.all()`	`MistralSandbox` filters by IP address, not by host.	Use `Network.all()`, or open addresses with `egress=agents.EgressPolicy.custom(allow_cidrs=...)`.
`MistralSandbox: agents.GitHubBinding needs network access to github.com, api.github.com, which Network.none() blocks; pass network=Network.all()`	A header binding cannot reach its hosts.	Pass `network=agents.Network.all()`.

Secrets: give your tools a credential that is not in your code.