Sandboxes and Execution

Give an agent a sandbox and it gets one more tool, execute: a shell command run inside an isolated container, not on your machine. By the end of this page you will have an agent that runs Python in Docker against a file from its workspace, writes a result back, and leaves a record of every command.

Every output on this page is what the code printed when it was run, with Docker on Linux and gpt-5.4-mini. The model writes its own commands, so the commands and the wording will differ on your run.

A first run in Docker

Install the Docker extra

pip install "omnicoreagent[docker]"

Docker must be running. The first run pulls the default image, python:3.12-slim, which can take a minute; later runs start in seconds.

Put a file in the workspace

The agent’s workspace is ./workspace/files/ by default. Create workspace/files/sales.csv:

region,amount
north,120
south,80
east,200
west,50

Run the agent

import asyncio
from omnicoreagent import OmniCoreAgent

async def main():
    agent = OmniCoreAgent(
        name="analyst",
        system_instruction="Use the execute tool to run commands. Answer in plain text, in one or two sentences.",
        model_config={"provider": "openai", "model": "gpt-5.4-mini"},
        agent_config={
            "governance_config": {
                "enabled": True,
                "profile": "interactive-dev",
                "sandbox_config": {"provider": "docker"},
            },
        },
    )
    result = await agent.run(
        "sales.csv is in your working directory. Use Python to add up the amount column, "
        "and write the total to total.txt."
    )
    print(result["status"], "|", result["response"])

    trajectory = await agent.get_trajectory(result["trace_id"])
    for step in trajectory["steps"]:
        for call in step["tool_calls"]:
            for run in call["executions"]:
                print("ran:", run["command"], "| exit", run["exit_code"],
                      "| in", run["sandbox_provider"], "|", run["duration_ms"], "ms")
            sync = call["workspace_sync"]
            if sync:
                print("copied in:", sync["copied_in"], "| copied back:", sync["written"])
    print("totals:", trajectory["totals"]["executions"])
    await agent.cleanup()

asyncio.run(main())

success | Done — I summed the amount column and wrote the total to total.txt.
ran: ['sh', '-c', "python3 - <<'PY'\nimport csv\nfrom decimal import Decimal\nfrom pathlib import Path\np = Path('sales.csv')\nwith p.open(newline='', encoding='utf-8') as f:\n    reader = csv.DictReader(f)\n    total = Decimal('0')\n    for row in reader:\n        val = row.get('amount', '').strip()\n        if val:\n            total += Decimal(val)\nPath('total.txt').write_text(str(total), encoding='utf-8')\nprint(total)\nPY"] | exit 0 | in docker | 1325.076 ms
copied in: ['sales.csv'] | copied back: ['total.txt']
totals: {'sessions': 1, 'commands': 1, 'failed': 0, 'timed_out': 0}

workspace/files/total.txt now holds 450. The command ran in a container; the file it wrote came back to your workspace.

How it works

The tool appears only with a sandbox

execute is added when governance is on (the default) and the configured provider can run commands. With governance turned off ("enabled": False), or with provider none, the agent has no way to run a command.

Each command is authorized twice

The tool call is sandbox.execute; the command inside the sandbox is process.exec, on the sandbox surface (or host for the local provider). The development profiles allow sandboxed commands; strict-production allows none without a rule of yours (Policies).

One sandbox per run

The first command opens a session; later commands in the same run reuse it, so files persist between them. When the run ends — success, error, a pause for approval, or a cancel — the session is closed and the container removed. A resumed run opens a fresh one.

Workspace files go in, text outputs come back

Before each command, workspace files that changed since the last copy are uploaded into the sandbox’s working directory (/workspace). After it, text files the command created or changed are copied back as governed workspace writes. The sandbox never mounts your workspace.

The model sends command (run with sh -c in the working directory) and an optional timeout in seconds: 60 by default, at most the agent’s tool_call_timeout (180 by default). A command that exits non-zero or times out comes back to the model as an error, with its exit code, stdout and stderr.

With your own strict policy

A strict policy allows nothing it does not name, the sandbox included. These three rules let the agent use execute and run commands only inside the sandbox:

import asyncio
from omnicoreagent import OmniCoreAgent

policy = {
    "name": "strict-with-sandbox",
    "mode": "strict",
    "rules": {
        "allow": [
            {"rule_id": "use_execute", "capability": "sandbox.execute"},
            {"rule_id": "sandbox_setup", "capability": "sandbox.*"},
            {"rule_id": "commands_in_the_sandbox", "capability": "process.exec",
             "conditions": {"execution_surface": "sandbox"}},
        ],
    },
}

async def main():
    agent = OmniCoreAgent(
        name="runner",
        system_instruction="Run the command the user asks for with execute. Reply in plain text.",
        model_config={"provider": "openai", "model": "gpt-5.4-mini"},
        agent_config={"governance_config": {
            "enabled": True,
            "policy": policy,
            "sandbox_config": {"provider": "docker"},
        }},
    )
    result = await agent.run('Run: python -c "print(6*7)" and tell me the output.')
    print(result["status"], "|", result["response"])
    trajectory = await agent.get_trajectory(result["trace_id"])
    for step in trajectory["steps"]:
        for call in step["tool_calls"]:
            for decision in call["governance"]:
                print(call["tool_name"], decision["capability"], decision["effect"], decision["matched_rule_ids"])
    await agent.cleanup()

asyncio.run(main())

success | 42
execute sandbox.execute allow ['use_execute', 'sandbox_setup']
execute process.exec allow ['commands_in_the_sandbox']
execute sandbox.workspace.sync allow ['sandbox_setup']

The process.exec decision is the model’s command. The last one is the runtime’s own: after a command, it lists what changed in the sandbox to copy it back to the workspace. That listing is governed too, as sandbox.workspace.sync (part of sandbox.*), and it is not judged as a command the agent asked for, so rules on shell commands do not apply to it. If no rule names it, as in a strict policy that allows commands but not the sync, it follows the decision for the command that triggered it: the trace shows an allow with the reason follows_command and the command’s request id, not a rule match. A rule you write for it still decides, so a deny rule stops the copy-back (the model is told so, and the command’s files stay in the sandbox). Every file it copies back is still decided by the workspace file rules, below. Leave out sandbox.* and the sandbox cannot start; leave out the process.exec rule and every command is refused. sandbox.network.configure is part of sandbox.* here: to keep the network behind a person, add an ask rule for it, as the development profiles do (Policy reference). Under these three rules alone no workspace file is copied into the sandbox or back: each copy is checked as a read or a write of that file, and a strict policy refuses what it does not name. To let files through, add the two file rules, with a path target to narrow them:

{"rule_id": "files_in", "capability": "workspace.files.read"},
{"rule_id": "files_out", "capability": "workspace.files.write",
 "target": {"path": "outputs/*"}},

Rules on what a command runs

A process.exec rule can also name a command by its first words, with a command matcher: deny rm, ask before git push, allow only git status and git log. Only a plain chain of commands (git status && rm -rf build) is split and matched command by command. Anything else, such as a redirect, $(...), a variable, a glob, eval or sh -c, is one unreadable command: no rule allows it, and where the policy has command rules it is asked about (refused in strict), so eval "rm -rf ~" does not pass a deny on rm. Wrappers are not looked inside: sudo rm is a command named sudo. Command rules decide when to ask; what a command can touch is the sandbox’s to decide. See Rules on shell commands.

Files between the workspace and the sandbox

What is copied, and what is not:

	Copied in	Copied back
Text files (UTF-8)	Yes, when changed since the last copy	Yes, when created or changed by a command
Binary files	No	No: skipped, and the model is told why
Hidden paths (`.anything`), links	—	Never
A folder holding a `.git` (a checkout)	—	Never; clone repositories outside the workspace folder
A background run’s `run.json`, `events.jsonl`	Never	Never
A file the policy protects	No (a `read_file` of it would be refused)	No (a `write_file` of it would be refused)
Deletions	Not propagated either way

Limits: 500 files, 2 MB per file and 20 MB per copy. To copy less, give glob patterns over workspace paths (* crosses folders; no include copies everything not excluded). The patterns apply both ways: a file outside them is not copied in, and a file a command creates or changes outside them is not copied back either (it is skipped, with the reason “outside the bridge’s include/exclude patterns”):

agent_config = {
    "governance_config": {
        "sandbox_config": {"provider": "docker"},
        "workspace_bridge": {"include": ["src/*", "data/*.csv"], "exclude": ["data/archive/*"]},
    },
}

With enable_workspace_files: False nothing is copied. With the local provider nothing is copied either: commands already run on the machine, so point its working_dir at the workspace directory instead.

The network is off

A sandbox has no network unless its manifest asks for it, and the policy allows that. Here the agent looks at its own sandbox:

import asyncio
from omnicoreagent import OmniCoreAgent

async def main():
    agent = OmniCoreAgent(
        name="checker",
        system_instruction="Use the execute tool to run commands. Answer in plain text, without markdown.",
        model_config={"provider": "openai", "model": "gpt-5.4-mini"},
        agent_config={
            "governance_config": {
                "enabled": True,
                "profile": "interactive-dev",
                "sandbox_config": {"provider": "docker"},
            },
        },
    )
    result = await agent.run(
        "In your sandbox: list the names (not values) of the environment variables, "
        "then try to open https://pypi.org with Python (5 second timeout). "
        "Report both in two short lines."
    )
    print(result["response"])
    await agent.cleanup()

asyncio.run(main())

GPG_KEY, HOME, HOSTNAME, LANG, PATH, PWD, PYTHON_SHA256, PYTHON_VERSION
URLError: <urlopen error [Errno -3] Temporary failure in name resolution>

No network, and none of your process’s variables: LLM_API_KEY is not there. The variables listed come from the python:3.12-slim image itself (GPG_KEY is the ID of the key Python’s releases are signed with). To turn the network on, ask for it in sandbox_manifest. The development profiles ask a person first (rule ask_sandbox_network), so the run pauses before its first command:

import asyncio
from omnicoreagent import OmniCoreAgent

async def main():
    agent = OmniCoreAgent(
        name="fetcher",
        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": "docker"},
                "sandbox_manifest": {"network_policy": {"default": "allow"}},
            },
        },
    )
    result = await agent.run("Use Python in your sandbox to fetch https://pypi.org and report the HTTP status code.")
    print("status:", result["status"])
    while result["status"] == "awaiting_approval":
        for approval in result["approvals"]:
            print("waiting on:", approval["capability"], approval["target"]["host"], "|", approval["reason"])
            await agent.resolve_approval(
                result["run_id"], approval["approval_id"], decision="approve", approver="alice"
            )
        result = await agent.resume(result["run_id"])
        print("status:", result["status"])
    print(result["response"])
    await agent.cleanup()

asyncio.run(main())

status: awaiting_approval
waiting on: sandbox.network.configure * | Turning the sandbox network on needs approval.
status: success
200

"allow" opens the whole internet. To allow only named hosts, use "allowed_hosts": ["pypi.org", "*.pythonhosted.org"] on a provider that enforces a host allowlist; Docker, E2B, Vercel and local cannot, and the agent is refused when it is built rather than given more network than it asked for. Which providers enforce what is on Sandbox providers.

What the manifest can ask for

sandbox_config says who runs the sandbox; sandbox_manifest says what it is. Each thing it asks for is a policy question when the session opens:

Field	Default	Asked as
`network_policy`	`{"default": "deny"}`	`sandbox.network.configure` (once per allowed host)
`image`	the provider’s (`python:3.12-slim` for Docker)	`sandbox.image.use`
`working_dir`	`/workspace`	—
`environment`	`{"plain": {}}`	`sandbox.environment.set`
`resources`	none (e.g. `{"cpu": "2", "memory": "1g"}`)	`sandbox.resources.set`
`workspace_mount`	none	`sandbox.filesystem.mount` (asks in the dev profiles)
`lifecycle`	`{"cleanup": "always", "snapshot": False}`	—

A setting the chosen provider does not apply is refused when the agent is built, naming the provider and the setting: a workspace mount works on Docker only, a host allowlist on Modal and http only, CPU and memory limits everywhere but E2B. There is no list of paths a sandboxed command may read or write: it reaches the sandbox’s own disk and, on Docker, the workspace mount; filesystem_policy was removed, since no provider applied it. lifecycle does not change the agent’s own sandbox, which is closed when its run ends: cleanup ("always", "on_success", "never") applies only to a one-off command run through the sandbox service without a session, and nothing acts on snapshot yet. A manifest with an unknown field, or one that sets provider or sandbox_id, is refused when the agent is built.

Secrets stay out

A sandbox gets only the environment you give it in sandbox_manifest["environment"]["plain"] — never your process’s environment, and never your model key or provider credentials, which stay in your process with the policy and the telemetry. Docker also never mounts the Docker socket, system directories or credential folders such as ~/.ssh or ~/.aws, whatever the policy says (Security model).

agent_config = {
    "governance_config": {
        "sandbox_config": {"provider": "docker"},
        "sandbox_manifest": {"environment": {"plain": {"APP_ENV": "test"}}},
    },
}

Put nothing secret in plain: the model’s commands can read it and print it. environment.secret_refs is refused when the agent is built, since no built-in provider delivers secrets to a command. Keep a secret in a tool that runs in your process, and let the model call the tool.

What a command’s record holds

Each command is in the run’s trajectory under the tool call that ran it (call["executions"]):

Field	What
`command`	The argv, `['sh', '-c', '<the model's command>']`
`exit_code`, `timed_out`, `duration_ms`	How it ended
`stdout`, `stderr`	Its output, subject to the privacy capture policy
`stdout_bytes`, `stderr_bytes`, `*_truncated`	Output size; output over 1 MB is cut
`sandbox_provider`, `sandbox_session_id`	Where it ran
`matched_rule_ids`	The rule that allowed it, e.g. `allow_sandboxed_execution`

call["workspace_sync"] lists what was copied in, written back and skipped (with the reason), and trajectory["totals"]["executions"] counts sessions, commands, failures and timeouts. The trace also has the session itself, as sandbox_session_created and sandbox_session_closed events: provider, the provider’s own name for the sandbox (sandbox_ref, the container ID for Docker), image, network, working directory, and on close the number of commands, how long it was open, and lost. See Observability.

A sandbox that dies

A sandbox can die under a run: the provider stopped it, its lifetime ran out, someone removed it, or a command ignored its time limit and the sandbox was stopped. That is not reported as a slow command. The model is told:

The sandbox was lost during this command (...). Files created in it are gone; the next command runs in a fresh sandbox with the workspace files copied in again.

The next command opens a fresh sandbox, and the trace records the old session closed with lost: true. A run that pauses for approval, or whose process dies, continues where it stopped (Durable runs).

Options

Where	Option	Default	What it does
`governance_config`	`sandbox_config`	none	`{"provider": ..., "options": {...}}`: who runs the sandbox (providers)
`governance_config`	`sandbox_manifest`	no network, provider’s image, `/workspace`	What the sandbox is (above)
`governance_config`	`workspace_bridge`	copy everything	`{"include": [...], "exclude": [...]}` globs
`governance_config`	`sandbox_runtime`	none	A runtime object instead of `sandbox_config` (not both)
`agent_config`	`tool_call_timeout`	`180`	The most seconds one command may be given
`agent_config`	`enable_workspace_files`	`True`	Off: nothing is copied in or out

Every agent setting is in the agent settings reference; every capability in the policy reference.

When things go wrong

The agent never calls execute

The tool is not there. Check that governance is not turned off ("enabled": False) and that governance_config has a sandbox_config whose provider runs commands (none does not). Do not add "enabled": True to fix it: without a profile that switches to interactive-dev. A model that asks for it anyway gets:

Tool 'execute' is not available; discover it first if hidden

Command timed out after 1s

The command ran longer than the timeout the model gave it. It is killed inside the sandbox and the model receives:

{"tool_name": "execute", "args": {"command": "sleep 5", "timeout": 1}, "status": "error", "data": {"exit_code": 137, "stdout": "", "stderr": "", "timed_out": true, "execution_surface": "sandbox"}, "message": "Command timed out after 1s"}

The model can retry with a longer timeout, up to tool_call_timeout.

Command exited with 2

The command failed; the model sees its stderr and usually corrects itself:

{"tool_name": "execute", "args": {"command": "ls /nope", "timeout": 30}, "status": "error", "data": {"exit_code": 2, "stdout": "", "stderr": "ls: cannot access '/nope': No such file or directory\n", "timed_out": false, "execution_surface": "sandbox"}, "message": "Command exited with 2"}

Temporary failure in name resolution / pip install fails

The sandbox has no network, as intended. Either build an image with what your tasks need and name it ("sandbox_manifest": {"image": "..."}), or allow the network in the manifest (above).

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

Raised when the agent is built with allowed_hosts on a provider that cannot keep it:

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)

Use "default": "allow", or Modal or your own http service.

Sandbox image … is not present and pulling is disabled

With "pull": "never", the image must already be on the Docker host. The command’s call fails with:

Sandbox image example/not-here:1 is not present and pulling is disabled

Sandbox providers

Docker, E2B, Daytona, Modal, Vercel, your own service, or this machine.

Policies

Allow, ask or deny each command, image and network request.

Approvals

Pause a run for a person, and resume it later.

Budgets

Cap dollars, tokens, calls and sandbox seconds.

Security model

What is enforced, and where the boundaries are.

Privacy

What the record of a command keeps.

Get Started

Make It Safe

Run It

See and Improve

Build

How It Works

Reference

HTTP API (OmniServe)

Releases

Sandboxes and Execution

Sandboxes and Execution

A first run in Docker

How it works

With your own strict policy

Rules on what a command runs

Files between the workspace and the sandbox

The network is off

What the manifest can ask for

Secrets stay out

What a command’s record holds

A sandbox that dies

Options

When things go wrong

Next

Sandbox providers

Policies

Approvals

Budgets

Security model

Privacy

​Sandboxes and Execution

​A first run in Docker

​How it works

​With your own strict policy

​Rules on what a command runs

​Files between the workspace and the sandbox

​The network is off

​What the manifest can ask for

​Secrets stay out

​What a command’s record holds

​A sandbox that dies

​Options

​When things go wrong

​Next

Sandbox providers

Policies

Approvals

Budgets

Security model

Privacy

Sandboxes and Execution

A first run in Docker

How it works

With your own strict policy

Rules on what a command runs

Files between the workspace and the sandbox

The network is off

What the manifest can ask for

Secrets stay out

What a command’s record holds

A sandbox that dies

Options

When things go wrong

Next