Sandbox

The sandbox port, Docker, callable and development-only local backends, and code_tool. Concepts: Sandboxed code.

Sandboxed code execution: SandboxPort, Docker, callable and dev-only local backends.

CODE_FILES = {'python': 'main.py', 'javascript': 'main.js', 'bash': 'main.sh'} module-attribute

CODE_KIND = 'code' module-attribute

InputFiles = Mapping[str, bytes | str] module-attribute

OnResult = Callable[[SandboxResult, ToolContext], Any] module-attribute

RunFn = Callable[[SandboxRequest], Any] module-attribute

CallableSandbox

Bases: GuardedSandbox

Wraps fn(request); the service does the isolating, this class checks and bounds.

network=True lets requests ask for network access; your service must enforce request.network and request.timeout_s itself.

Raises:

Type	Description
ToolUsageError	fn is not callable.
ConfigError	bad languages, limits or grace_s.

DockerSandbox

Bases: GuardedSandbox

Runs code in a throwaway container: no network, read-only root, no capabilities.

The image needs python3 (the runner), plus node or bash for those languages. It is never pulled at run time: docker pull it first. network=True lets a request use the default bridge network: unrestricted egress, including cloud metadata addresses and the host's own services.

Raises:

Type	Description
ConfigError	a bad image, user (root uid or gid is refused), runtime or limit.

command_line(request, *, container)

The exact docker run argv for request (the code goes on stdin, not here).

status()

docker_status for this sandbox's CLI.

DockerStatus dataclass

Whether Docker can run Linux containers here, with the versions found.

GuardedSandbox

Bases: ABC

A SandboxPort that checks every request and re-applies its limits to every result.

Backends implement _run. Output and files over the limits are cut here too, so a backend that ignores them fails closed (less output), never open.

request(code, *, language='python', files=None, timeout_s=30.0, max_output_bytes=64000, network=False, env=None)

The checked request run would send to the backend.

Raises:

Type	Description
ToolUsageError	bad code, language, files or env.
ConfigError	bad limits, or network asked of a sandbox that does not allow it.

run(code, *, language='python', files=None, timeout_s=30.0, max_output_bytes=64000, network=False, env=None, ctx=None) async

Run code in the sandbox and return its bounded result; a timeout is a result.

Raises:

Type	Description
ToolUsageError	bad code, language, files or env.
ConfigError	bad limits, or network asked of a sandbox that does not allow it.
IntegrationError	the backend failed (the cause is chained).
AdapterError	a fail-closed audit sink could not record the start; nothing ran.

run_sync(code, *, timeout=None, **kw)

run from sync code (inside a running loop, on a worker thread).

Limits dataclass

Bounds on what a backend returns: produced files and their bytes.

LocalSubprocessSandbox

Bases: GuardedSandbox

DEVELOPMENT ONLY: Python in a temporary folder with a time limit and output caps.

It isolates nothing (files, network, processes and memory are the host's) and refuses to start unless allow_unsafe_local=True. Every run logs a WARNING. On Windows, processes the code leaves running in the background are not killed when it exits.

Raises:

Type	Description
ConfigError	allow_unsafe_local is not True, or bad limits.

SandboxFile

Bases: BaseModel

A file the code left in its work directory; data may be cut (see size).

truncated property

True when data holds less than the whole file.

text()

data as UTF-8, with undecodable bytes replaced.

SandboxPort

Bases: Protocol

Runs untrusted code in isolation, within a time limit and an output limit.

SandboxRequest dataclass

A checked run: what a backend's _run receives.

code_file property

The file name the code is written to.

SandboxResult

Bases: BaseModel

What one run produced; output and files are bounded by the run's limits.

ok property

True when the code exited 0 within its time limit.

truncated property

True when any output or file was cut.

code_tool(sandbox, *, name='run_code', description=None, languages=('python',), timeout_s=30.0, max_output_bytes=64000, network=False, env=None, files=None, on_result=None, tags=())

A tool (kind "code") that runs the model's code in sandbox; every run needs approval.

confirm=True is fixed: there is no option to run model-written code unapproved. Limits, network, env and input files are the host's; the model chooses only the code (and the language, when more than one is offered).

Raises:

Type	Description
ConfigError	bad limits, env, files or languages, or network=True on a sandbox that does not allow it.
ToolUsageError	sandbox has no async run.

docker_status(docker='docker', *, timeout_s=10.0)

Probe the docker CLI and its daemon; never raises.