Sandbox Providers

The provider decides where the agent’s commands run. Everything else — the policy, the workspace bridge, the record of each command, your credentials — stays in your process and works the same with every provider. By the end of this page you will have picked one, set it up, and know what it enforces.

agent_config = {
    "governance_config": {
        "sandbox_config": {"provider": "e2b", "options": {"timeout_seconds": 300}},
    },
}

What the sandbox is (network, image, working directory) is the sandbox_manifest, the same for every provider; the Sandboxes and execution page has a first run and the manifest in full.

Every output on this page is what the code printed when it was run: Docker on Linux, and free E2B and Daytona accounts. Modal and Vercel were not run for this page; what is said about them comes from their adapters’ code.

Choose a provider

Provider	Install	Credentials	Runs where	Commands run as
`docker`	`omnicoreagent[docker]`	a running Docker	a container on your machine or Docker host	user `65534` (nobody)
`e2b`	`omnicoreagent[e2b]`	`E2B_API_KEY`	an E2B sandbox	user `1000` (measured)
`daytona`	`omnicoreagent[daytona]`	`DAYTONA_API_KEY`	a Daytona sandbox	root (measured)
`modal`	`omnicoreagent[modal]`	`modal token new`, or `MODAL_TOKEN_ID` and `MODAL_TOKEN_SECRET`	a Modal sandbox	the image’s user
`vercel`	`omnicoreagent[vercel]`	`VERCEL_TOKEN`, `VERCEL_TEAM_ID`, `VERCEL_PROJECT_ID`	a Vercel Sandbox	the image’s user
`http`	built in	your service’s token	a service you run	your service decides
`local`	built in	none	this machine, not isolated	your user
`none`	built in	none	nowhere: a policy with no `execute` tool	—
`local_test`	built in	none	handlers you register, for tests	—

Start with docker. It is free, local, and the strictest by default.
Hosted (e2b, daytona, modal, vercel) when the agent runs where there is no Docker, or you want the sandbox off your machine.
http for anything without an adapter: your own sandbox service.
local only where the machine itself is the boundary: a CI job, a throwaway VM, an evaluation container.

Credentials are read by the provider’s SDK from your process’s environment (or passed as options); they are never put inside a sandbox.

Network: what each provider enforces

A manifest’s network_policy is {"default": "deny"} unless you say otherwise. What each provider can keep:

Provider	`deny` (default)	`allow`	`allowed_hosts`	”No network” checked from inside
`docker`	Yes, `network_mode="none"`	Yes, `bridge`	Refused when the agent is built	Not needed: Docker enforces it
`e2b`	Asked of E2B	Yes	Refused when the agent is built	Yes
`daytona`	Asked of Daytona	Yes	Refused when the agent is built (below)	Yes
`modal`	Yes, `block_network`	Yes	Yes, Modal’s domain allowlist	No
`vercel`	Yes, `deny-all`	Yes, `allow-all`	Refused when the agent is built	No
`http`	Your service must keep it or refuse	←	←	Your service’s job
`local`	Refused: it cannot	Required	Refused	—

denied_hosts is passed on to an http service, which must keep it or refuse the session. No other built-in provider can block named hosts, so there it is refused when the agent is built. To reach only some hosts, use "default": "deny" with allowed_hosts on a provider that keeps them.

Hosted “no network” is checked, and free accounts fail the check. E2B and Daytona both accept a request for no internet and report it back — and on the free accounts this page was run with, both handed back sandboxes that reached the internet. The adapter tries one outbound connection from inside each new sandbox that must have no network; a sandbox that connects is destroyed and refused:

e2b deny REFUSED: SandboxUnsupportedError The e2b sandbox was created with no network access, but it still reached the internet: this account or plan does not enforce network isolation. Use a provider that does, allow the network in the manifest if the work needs it, or set the sandbox option verify_network_isolation=false to accept an unchecked sandbox. (17.0s)
daytona deny REFUSED: SandboxUnsupportedError The daytona sandbox was created with no network access, but it still reached the internet: this account or plan does not enforce network isolation. Use a provider that does, allow the network in the manifest if the work needs it, or set the sandbox option verify_network_isolation=false to accept an unchecked sandbox. (83.9s)

A promise of isolation the provider does not keep is worse than none: a policy may allow the work only because it is isolated. On such an account, either allow the network in the manifest (the policy asks a person, as below) or set "verify_network_isolation": False and accept an unchecked sandbox. The check needs python in the image; an image without it is refused too.

Docker

pip install "omnicoreagent[docker]"

agent_config = {
    "governance_config": {
        "sandbox_config": {"provider": "docker", "options": {"image": "python:3.12-slim"}},
    },
}

One container per run, removed when the run ends. It has no network unless the manifest allows it, a read-only root filesystem, an unprivileged user, all Linux capabilities dropped, no privilege escalation, a process limit, and a working directory and /tmp kept in memory. The Docker socket, system directories and credential folders (~/.ssh, ~/.aws, …) are never mounted. The first run pulls the image; later runs start in seconds. The default image has Python and its standard library and nothing else, and with no network a command cannot pip install. Build an image with what your tasks need and name it in the options or the manifest.

Option	Default	What it does
`image`	`python:3.12-slim`	The image; a manifest’s `image` wins
`user`	`"65534:65534"`	Numeric `uid` or `uid:gid`
`workdir_size`	`"1g"`	Size of the in-memory working directory
`pids_limit`	`256`	Most processes at once
`pull`	`"if_missing"`	`"never"`: the image must already be there
`runtime`	Docker’s default	`"runsc"` runs the container under gVisor
`max_output_bytes`	`1000000`	Output kept per stream; the rest is cut

A run on Docker, end to end, is on Sandboxes and execution. A container left behind by a process that was killed is removed when its run is resumed, run again with the same run ID, or abandoned (abandon_run): each container carries its run’s ID in the label omnicoreagent.run. To remove one run’s leftovers yourself, await DockerSandboxRuntime().cleanup_orphans(run_id=...) (from omnicoreagent.sandbox.docker). Without run_id it removes every container labelled omnicoreagent.sandbox, including those of agents still running on the same Docker host.

E2B

pip install "omnicoreagent[e2b]"
export E2B_API_KEY=your_e2b_key

On a free account the no-network check fails (above), so this agent asks for the network, and the policy asks a person first:

import asyncio
from omnicoreagent import OmniCoreAgent

async def main():
    agent = OmniCoreAgent(
        name="e2b_agent",
        system_instruction="Use the execute tool to run commands. Answer in plain text, in one sentence.",
        model_config={"provider": "openai", "model": "gpt-5.4-mini"},
        agent_config={
            "governance_config": {
                "enabled": True,
                "profile": "interactive-dev",
                "sandbox_config": {"provider": "e2b"},
                "sandbox_manifest": {"network_policy": {"default": "allow"}},
            },
        },
    )
    result = await agent.run("Which Linux distribution and Python version does your sandbox have? Check, don't guess.")
    while result["status"] == "awaiting_approval":
        for approval in result["approvals"]:
            print("approving:", approval["capability"], approval["target"]["host"])
            await agent.resolve_approval(
                result["run_id"], approval["approval_id"], decision="approve", approver="alice"
            )
        result = await agent.resume(result["run_id"])
    print(result["status"], "|", result["response"])

    story = await agent.get_run_trajectory(result["run_id"])
    for segment in story["segments"]:
        for step in segment["trajectory"]["steps"]:
            for call in step["tool_calls"]:
                for run in call["executions"]:
                    print("ran in", run["sandbox_provider"], "| exit", run["exit_code"], "|", run["duration_ms"], "ms")
    await agent.cleanup()

asyncio.run(main())

approving: sandbox.network.configure *
success | Debian GNU/Linux 12 (bookworm) with Python 3.11.6.
ran in e2b | exit 0 | 523.922 ms

A new E2B sandbox took about 12 seconds to start here. The sandbox is killed when the run ends.

Option	Default	What it does
`template`	E2B’s default	The E2B template; a manifest’s `image` wins
`api_key`	`E2B_API_KEY`	Pass the key instead of the environment
`timeout_seconds`	`600`	The sandbox’s lifetime; E2B stops it after this
`verify_network_isolation`	`True`	The no-network check above
`max_output_bytes`	`1000000`	Output kept per stream

Daytona

pip install "omnicoreagent[daytona]"
export DAYTONA_API_KEY=your_daytona_key

agent_config = {
    "governance_config": {
        "sandbox_config": {"provider": "daytona"},
        "sandbox_manifest": {"network_policy": {"default": "allow"}},
    },
}

Each run gets an ephemeral sandbox, deleted when the run ends. Measured here: the default image (python:3.12-slim) gave Debian 13 and Python 3.12.14, commands ran as root, and a sandbox took 48 to 84 seconds to start. Daytona returns a command’s output as one stream: stdout holds everything and stderr is empty. allowed_hosts is refused when the agent is built: Daytona’s allow list takes IP ranges, not host names. Use "deny" or "allow" on Daytona. (In 0.4.1 it was accepted and the session then failed to start.)

Option	Default	What it does
`image`	`python:3.12-slim`	The image; a manifest’s `image` wins
`api_key`, `api_url`, `target`	Daytona’s environment	Where and as whom to connect
`verify_network_isolation`	`True`	The no-network check above
`max_output_bytes`	`1000000`	Output kept

pip install "omnicoreagent[modal]"
modal token new

agent_config = {
    "governance_config": {
        "sandbox_config": {"provider": "modal"},
        "sandbox_manifest": {
            "network_policy": {"default": "deny", "allowed_hosts": ["pypi.org", "*.pythonhosted.org"]},
        },
    },
}

Modal is the built-in provider that keeps a host allowlist: the hosts are passed as Modal’s outbound_domain_allowlist. Each allowed host is its own sandbox.network.configure question, so a policy can allow some hosts and ask about the rest. Sandboxes run in a Modal app named omnicoreagent-sandbox (created if missing). There is no from-inside network check for Modal.

Option	Default	What it does
`image`	`python:3.12-slim`	Pulled from a registry; a manifest’s `image` wins
`app_name`	`"omnicoreagent-sandbox"`	The Modal app the sandboxes belong to
`timeout_seconds`	`600`	The sandbox’s lifetime
`max_output_bytes`	`1000000`	Output kept per stream

Vercel

pip install "omnicoreagent[vercel]"
export VERCEL_TOKEN=... VERCEL_TEAM_ID=... VERCEL_PROJECT_ID=...

agent_config = {
    "governance_config": {
        "sandbox_config": {"provider": "vercel", "options": {"timeout_seconds": 300}},
    },
}

The network is deny-all or allow-all; a host allowlist is refused. There is no from-inside network check for Vercel.

Option	Default	What it does
`image`	Vercel’s default	A manifest’s `image` wins
`project_id`	Vercel’s environment (`VERCEL_PROJECT_ID`)	The project the sandbox belongs to
`timeout_seconds`	`600`	The sandbox’s execution time limit
`max_output_bytes`	`1000000`	Output kept per stream

HTTP: your own sandbox service

For anything without an adapter — Cloudflare’s Sandbox SDK behind a Worker, a sandbox service inside your own network — run a small service and point the agent at it:

agent_config = {
    "governance_config": {
        "sandbox_config": {
            "provider": "http",
            "options": {"base_url": "https://sandboxes.example.com", "token": "..."},
        },
    },
}

The service answers five requests, each with Authorization: Bearer <token> when a token is set:

Request	Body	Answer
`POST /sessions`	`{"manifest": {image, working_dir, environment, network, resources}}`	`{"session_id": "..."}`
`POST /sessions/{id}/exec`	`{command, cwd, env, timeout_seconds, stdin}`	`{exit_code, stdout, stderr, timed_out}`
`PUT /sessions/{id}/files?path=`	raw bytes	204
`GET /sessions/{id}/files?path=`		raw bytes
`DELETE /sessions/{id}`		204

network carries default, allowed_hosts and denied_hosts. The service is responsible for the isolation it promises: one that cannot keep the network policy must refuse the session. Only the plain environment is sent.

Option	Default	What it does
`base_url`	required	Where the service listens
`token`	none	Sent as a bearer token
`headers`	none	Extra headers on every request
`request_timeout_seconds`	`120`	Per request
`verify_tls`	`True`	Check the service’s certificate
`max_output_bytes`	`1000000`	Output kept per stream

Local: this machine, not a sandbox

local runs each command as a process on the machine the agent runs on, with nothing in between: a command can reach the network, read and change any file your user can, and what it changes stays changed. Use it only where the machine is already the boundary. The built-in profiles never allow host commands on their own (permissive-dev and strict-production deny them; interactive-dev asks a person for each one). To let an agent run them without asking, start from a profile, drop the asks that stand in the way, and allow host commands with a rule of your own. The manifest’s working_dir must already exist, so create it first (here app/, next to the script: mkdir app, or the os.makedirs line below); otherwise the first command fails, saying the working directory does not exist:

import os
from omnicoreagent import OmniCoreAgent
from omnicoreagent.governance import (
    PolicyEffect, PolicyRule, PolicyRuleConditions, build_default_policy,
)

policy = build_default_policy("interactive-dev")
policy.rules.ask = [
    rule for rule in policy.rules.ask
    if rule.rule_id not in {"ask_process_exec", "ask_high_risk", "ask_sandbox_network"}
]
policy.rules.allow.insert(0, PolicyRule(
    rule_id="allow_host_commands",
    effect=PolicyEffect.ALLOW,
    capability="process.exec",
    conditions=PolicyRuleConditions(execution_surface="host"),
))

os.makedirs("app", exist_ok=True)  # the working directory must exist

agent = OmniCoreAgent(
    name="host_runner",
    system_instruction="Use the execute tool to run commands.",
    model_config={"provider": "openai", "model": "gpt-5.4-mini"},
    agent_config={
        "governance_config": {
            "enabled": True,
            "policy": policy,
            "sandbox_config": {"provider": "local"},
            "sandbox_manifest": {
                "working_dir": os.path.abspath("app"),   # a real directory, used as it is
                "network_policy": {"default": "allow"},
            },
        },
    },
)

A command pwd; echo "LLM_API_KEY=${LLM_API_KEY:-unset}" in that agent came back as:

{"exit_code": 0, "stdout": "/…/local/app\nLLM_API_KEY=unset\n", "stderr": "", "timed_out": false, "execution_surface": "host"}

Dropping ask_high_risk stops the profile asking about every other high-risk action on the host too; keep it if the agent has other tools that should still ask. A deny rule always wins over an allow, so this cannot be done from permissive-dev. What it refuses. A manifest must ask for what local really gives: network allow and filesystem allow, with no host or path lists. A manifest that leaves the network at its default (none), or no manifest at all, is refused when the agent is built, as are an image, a workspace mount, CPU, memory or GPU limits, a sandbox lifetime, and secret references. What it enforces. Each command’s time limit (the command and everything it started are killed); the output cap; the host environment is not passed, only PATH, HOME, USER, LOGNAME, LANG, LC_ALL, TERM, TMPDIR and TZ plus the manifest’s plain environment. Files are another matter: a command can read whatever your user can, including credential files. Workspace files are not copied in or out — point working_dir at the workspace to have commands work in it directly. The model is told the truth too: its execute tool says it runs on this machine and is not isolated, and every command is recorded with execution_surface: host.

Option	Default	What it does
`environment_passthrough`	none	Host variable names to pass, e.g. `["PYTHONPATH", "VIRTUAL_ENV"]`
`inherit_environment`	`False`	`True` passes the whole host environment (prefer the named list)
`create_working_dir`	`False`	Create a missing `working_dir` instead of failing
`max_output_bytes`	`1000000`	Output kept per stream

`none` and `local_test`

"provider": "none" gives the agent a policy but no sandbox: there is no execute tool, and a policy rule that requires a sandbox (sandbox_required) is never satisfied. local_test runs Python handlers you register instead of commands, for tests of your own agent. Pass the runtime itself, and say that a test runtime may stand in for a sandbox:

import asyncio
from omnicoreagent import OmniCoreAgent
from omnicoreagent.sandbox import LocalTestSandboxRuntime
from omnicoreagent.sandbox.models import SandboxExecResult

def fake_shell(request):
    # request.command is ["sh", "-c", "<the model's command>"]
    return SandboxExecResult(exit_code=0, stdout=f"pretend output of: {request.command[2]}\n")

async def main():
    agent = OmniCoreAgent(
        name="under_test",
        system_instruction="Use the execute tool.",
        model_config={"provider": "openai", "model": "gpt-5.4-mini"},
        agent_config={
            "governance_config": {
                "sandbox_runtime": LocalTestSandboxRuntime(commands={"sh": fake_shell}),
                "allow_test_sandbox_runtime": True,
            },
        },
    )
    result = await agent.run("Run the tests.")
    print(result["response"])
    await agent.cleanup()

asyncio.run(main())

With a stand-in model that called execute with pytest -q, the tool returned:

{"exit_code": 0, "stdout": "pretend output of: pytest -q\n", "stderr": "", "timed_out": false, "execution_surface": "sandbox"}

Without allow_test_sandbox_runtime, the agent gets no execute tool.

Bring your own provider

register_sandbox_provider("name", factory) adds a provider; it then works anywhere a provider name does. The factory is called with the options dict and a telemetry recorder, and returns a SandboxRuntime:

from omnicoreagent.sandbox import register_sandbox_provider

def make_my_sandbox(options, telemetry_recorder):
    from my_package import MySandboxRuntime   # your SandboxRuntime subclass
    return MySandboxRuntime(**options)

register_sandbox_provider("mysandbox", make_my_sandbox)

A runtime implements create, execute, read_file, write_file, set_network_policy, snapshot and terminate, and sets supports_execution = True and supports_required_sandbox = True when it isolates commands.

When things go wrong

SandboxUnsupportedError: … still reached the internet

The hosted sandbox was asked for no network and has one (see the warning above). Allow the network in the manifest, use a plan or provider that enforces isolation, or set "verify_network_isolation": False.

ValueError: governance_config.sandbox_config.provider must be a registered sandbox provider

A misspelled provider, or one of yours not registered before the agent is built:

ValueError: governance_config.sandbox_config.provider must be a registered sandbox provider: daytona, docker, e2b, http, local, local_test, modal, none, vercel

ValueError: Unknown docker sandbox option(s): network

Options are checked per provider; the network belongs in the manifest:

ValueError: Unknown docker sandbox option(s): network

Use "sandbox_manifest": {"network_policy": {"default": "allow"}}.

ValueError: The docker sandbox does not enforce a network host allowlist

allowed_hosts on docker, e2b, daytona, vercel or local:

ValueError: The docker sandbox does not enforce a network host allowlist (allowed_hosts): use network_policy default 'deny' or 'allow', or a provider that enforces one (modal, http)

The same check refuses denied_hosts on any built-in provider but http (“does not enforce blocking named hosts”), and environment.secret_refs on every built-in provider (“does not enforce delivering secrets”).

The local sandbox cannot restrict the network

local with no sandbox_manifest, or one that leaves the network at its default (deny). Building the agent fails with:

The local sandbox does not enforce network off: local runs on the host and cannot cut its network; set network_policy default 'allow' with no host lists, or use an isolating provider such as docker

Give it the manifest shown above.

ImportError: … requires optional dependency

The provider’s extra is not installed, e.g. pip install "omnicoreagent[e2b]".

SandboxUnsupportedError: The Docker sandbox needs the Docker SDK

Without the docker extra, nothing fails when the agent is built: the run’s first execute call fails with The Docker sandbox needs the Docker SDK: pip install omnicoreagent[docker]. Install it: pip install "omnicoreagent[docker]".

Sandboxes and execution

The execute tool, files in and out, the network, the record of a command.

Policies

Allow, ask or deny commands, images and network access.

Approvals

The person who says yes to the network.

Budgets

Cap sandbox seconds, and everything else a run spends.

Security model

What each boundary does and does not protect.

Guardrails

Prompt injection in what the agent reads.

Get Started

Make It Safe

Run It

See and Improve

Build

How It Works

Reference

HTTP API (OmniServe)

Releases

Sandbox Providers

Sandbox Providers

Choose a provider

Network: what each provider enforces

Docker

E2B

Daytona

Vercel

HTTP: your own sandbox service

Local: this machine, not a sandbox

`none` and `local_test`

Bring your own provider

When things go wrong

Next

Sandboxes and execution

Policies

Approvals

Budgets

Security model

Guardrails

​Sandbox Providers

​Choose a provider

​Network: what each provider enforces

​Docker

​E2B

​Daytona

​Modal

​Vercel

​HTTP: your own sandbox service

​Local: this machine, not a sandbox

​none and local_test

​Bring your own provider

​When things go wrong

​Next

Sandboxes and execution

Policies

Approvals

Budgets

Security model

Guardrails

Sandbox Providers

Choose a provider

Network: what each provider enforces

Docker

E2B

Daytona

Modal

Vercel

HTTP: your own sandbox service

Local: this machine, not a sandbox

`none` and `local_test`

Bring your own provider

When things go wrong

Next