How to give an OpenAI Agents SDK agent a code sandbox

Run a SandboxAgent with Runtime's sandbox client, or give an ordinary Agent four function tools that act on one microVM.

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, and puts the agent's shell, file edits and manifest in a Firecracker microVM with its own Linux kernel. A new sandbox ran its first Python command 351 ms after the request at the median, measured on 24 September 2026 (speed), and a 2 vCPU, 4 GiB sandbox costs $0.03125 an hour while the agent waits on the model.

Install

On 25 September 2026 the current releases were openai-agents 0.22.3 on PyPI and @openai/agents 0.18.0 on npm, the same versions Runtime's client was tested with on 23 September 2026.

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

The first npx withruntime login on your machine opens a browser approval, so there is no key to paste. On a server, set RUNTIME_API_KEY.

A SandboxAgent that fixes a test

The client creates the sandbox when the run starts and stops it when the run ends. funding="trial" spends the free trial's hours.

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(funding="trial"),    ))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, with create fields 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({ create: { funding: "trial" } });const result = await run(agent, "The tests are in tests/.", { sandbox: { client } });console.log(result.finalOutput);

Every option, from exposed_ports to workspace_persistence, is listed in the OpenAI Agents SDK guide.

Which sandbox client should you use?

The SDK ships its own clients. What each one is, from OpenAI's sandbox clients page, read on 25 September 2026:

CodeInterpreterTool is a different kind of thing: 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 that 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, private by default.
• Pause and resume. pause_on_exit=True pauses instead of stopping, so 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, not only the workspace folder.

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

An ordinary Agent with function tools

An Agent that is not a SandboxAgent takes the four framework tools: runtime_exec, runtime_read_file, runtime_write_file and runtime_list_files. Your code owns 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 (frameworks).

Keep keys and spending safe

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

• Cap each create. max_cost_micros in the client options refuses a sandbox whose first lease would cost more than that many microdollars.
• 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, and charges nothing (read-only keys and daily limits).
• Watch with a read-only key. Dashboards and CI checks see every sandbox and its cost but can start or change nothing.
• 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, and the host adds the real value only on requests to the hosts you name (secrets).

Pythonfrom withruntime.openai_agents import RuntimeCloudSandboxClientOptionsoptions = RuntimeCloudSandboxClientOptions(    funding="paid",    max_cost_micros=100_000,  # at most $0.10 for the first lease    exec_timeout_s=600,    extra={"network": {"internet": True, "allow": ["pypi.org", "*.pythonhosted.org"]}},)

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. New accounts get 50 free sandbox hours with no card (pricing).

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

Sources

Checked 25 September 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.22.3
• @openai/agents on npm: version 0.18.0

Facts on this page were checked on 25 September 2026.