How to give an OpenAI Agents SDK agent a code sandbox

With Runtime, the agent definition stays exactly as written. Only the client in the run configuration changes. RuntimeCloudSandboxClient sits beside the SDK's own Docker, E2B and Modal clients. It runs the agent's shell, file edits and manifest in a Firecracker microVM with its own Linux kernel. A 2 vCPU, 4 GiB sandbox costs $0.03125 an hour while the agent waits on the model.

Install

On 25 October 2026 the current releases were openai-agents 0.24.0 on PyPI and @openai/agents 0.21.0 on npm. Runtime's client was tested with 0.22.3 and 0.18.0 on 23 September 2026, and needs those versions or later.

Terminalpip install "withruntime[openai-agents]"npm install withruntime @openai/agents

The first npx withruntime login on your machine opens a browser approval, so you do not paste a key. On a server, set RUNTIME_API_KEY.

A SandboxAgent that fixes a test

The client creates the sandbox when the run starts. It stops the sandbox when the run ends. The run uses free usage first, then credit.

Pythonfrom agents import Runnerfrom agents.run import RunConfigfrom agents.sandbox import SandboxAgent, SandboxRunConfigfrom withruntime.openai_agents import RuntimeCloudSandboxClient, RuntimeCloudSandboxClientOptionsagent = SandboxAgent(name="Coder", instructions="Fix the failing test, then run the suite.")run_config = RunConfig(    sandbox=SandboxRunConfig(        client=RuntimeCloudSandboxClient(),        options=RuntimeCloudSandboxClientOptions(),    ))result = Runner.run_sync(agent, "The tests are in tests/.", run_config=run_config)print(result.final_output)

The TypeScript client takes the same run. Its create fields go under create:

TypeScriptimport { run } from "@openai/agents";import { SandboxAgent } from "@openai/agents/sandbox";import { RuntimeCloudSandboxClient } from "withruntime/openai-agents";const agent = new SandboxAgent({ name: "Coder", instructions: "Fix the failing test." });const client = new RuntimeCloudSandboxClient();const result = await run(agent, "The tests are in tests/.", { sandbox: { client } });console.log(result.finalOutput);

The OpenAI Agents SDK guide lists every option, from exposed_ports to workspace_persistence.

Which sandbox client should you use?

The SDK ships its own clients. The table below describes each one, using OpenAI's sandbox clients page, read on 25 October 2026:

CodeInterpreterTool is a different kind of tool. OpenAI runs it. It works only with OpenAI's Responses models, and your code never holds the machine. Its container sizes and prices are set out in OpenAI Code Interpreter alternative.

What the agent can do in the sandbox

• A real shell. exec_command returns when a command ends or its yield time passes. A long command keeps a PTY session, which write_stdin feeds. Root works, and sudo -u runs a manifest user's commands.
• Files of any size. Reads, writes, apply_patch edits and image views, plus git repositories and local folders named in the manifest.
• Previews. Ports named in exposed_ports become HTTPS addresses under runtimehost.com. They are private by default.
• Pause and resume. pause_on_exit=True pauses the sandbox instead of stopping it. The next run wakes the same machine, with its memory and processes.
• Whole-machine persistence. workspace_persistence="snapshot" keeps installed packages and running processes as a Runtime snapshot. The workspace folder alone is not the only thing kept.

The Python client also takes image and snapshot_id. A run can then start from a custom image with your toolchain already installed.

An ordinary Agent with function tools

An Agent that is not a SandboxAgent takes four framework tools: runtime_exec, runtime_read_file, runtime_write_file and runtime_list_files. Your code controls the sandbox's lifetime.

Pythonfrom agents import Agent, Runner, function_toolfrom withruntime import Sandboxfrom withruntime.tools import sandbox_toolswith Sandbox.create(timeout_seconds=900) as sbx:    agent = Agent(        name="Analyst",        instructions="Use the sandbox to compute answers. Report exit codes.",        tools=[function_tool(f) for f in sandbox_tools(sbx)],    )    print(Runner.run_sync(agent, "What is the SHA-256 of the string 'runtime'?").final_output)

In TypeScript, runtimeFunctionTools(sbx) from withruntime/openai-agents returns the same four tools (frameworks).

Keep keys and spending safe

Your OpenAI key stays in your application. The sandbox receives commands, never the model's credentials. For limits on what the sandbox itself may do:

• Cap each sandbox. max_total_cost_micros in the options' extra stops a sandbox once it has cost that many microdollars in total.
• Cap each day. A daily spending limit on the key that runs the agent fails any create, wake or extension past it, with spending_limit_reached. It charges nothing (read-only keys and daily limits).
• Watch with a read-only key. Dashboards and CI checks can see every sandbox and its cost. They cannot start or change anything.
• Narrow the network. extra={"network": {"internet": True, "allow": ["pypi.org", "*.pythonhosted.org"]}} passes a network rule at create. The host enforces it, root included.
• Store tokens as secrets. A GitHub token stored with npx withruntime secrets set reaches the sandbox as a placeholder. The host adds the real value only to requests to the hosts you name (secrets).

Pythonfrom withruntime.openai_agents import RuntimeCloudSandboxClientOptionsoptions = RuntimeCloudSandboxClientOptions(    exec_timeout_s=600,    extra={        "network": {"internet": True, "allow": ["pypi.org", "*.pythonhosted.org"]},        "max_total_cost_micros": 100_000,  # at most $0.10 in all    },)

What it costs

Runtime charges $0.025 per vCPU-hour of CPU actually used, with a floor of a twentieth of a vCPU, and $0.0075 per reserved GiB-hour. An agent run spends most of its time waiting for the model, and that is when the floor applies. A new account gets 100 free hours of a 1 GB machine in its first 30 days with no card (pricing).

For running many coding agents at the same time, see a sandbox for coding agents. For the same pattern with Anthropic's framework, see Claude Agent SDK.

Sources

Checked 25 October 2026.

• OpenAI Agents SDK: sandbox clients: UnixLocalSandboxClient, DockerSandboxClient and the hosted clients, and what each is for
• OpenAI Agents SDK: tools: CodeInterpreterTool and its OpenAIResponsesModel requirement
• openai-agents on PyPI: version 0.24.0
• @openai/agents on npm: version 0.21.0

Facts on this page were checked on 25 October 2026.