# 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. 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.

```bash no-run
pip 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.

```python check
from agents import Runner
from agents.run import RunConfig
from agents.sandbox import SandboxAgent, SandboxRunConfig
from withruntime.openai_agents import RuntimeCloudSandboxClient, RuntimeCloudSandboxClientOptions

agent = 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`:

```ts check
import { 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](/docs/openai-agents-sdk) 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:

| Option                              | Where the agent's commands run        | What OpenAI's docs say about it                                                                          |
| ----------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `UnixLocalSandboxClient`            | Your own machine                      | For trusted local development; on Linux it "adds no OS-level confinement"                                |
| `DockerSandboxClient`               | A container on your machine           | Container isolation, installed with `openai-agents[docker]`                                              |
| Hosted clients (E2B, Modal, others) | The provider's cloud                  | For "production-style isolation" in "a provider-managed environment"                                     |
| `CodeInterpreterTool`               | OpenAI's hosted container             | A hosted tool, available only with `OpenAIResponsesModel`                                                |
| `RuntimeCloudSandboxClient`         | A Runtime microVM with its own kernel | A client installed with `withruntime[openai-agents]`; documented in [the guide](/docs/openai-agents-sdk) |

`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](/compare/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](/docs/images) 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.

```python check
from agents import Agent, Runner, function_tool
from withruntime import Sandbox
from withruntime.tools import sandbox_tools

with 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](/docs/frameworks#openai-agents-sdk)).

## 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](/docs/security#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](/docs/security#secrets-sandboxes-never-see)).

```python check
from withruntime.openai_agents import RuntimeCloudSandboxClientOptions

options = 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](/docs/pricing)).

For running many coding agents at the same time, see
[a sandbox for coding agents](/use-cases/coding-agent-sandbox). For the same
pattern with Anthropic's framework, see
[Claude Agent SDK](/integrations/claude-agent-sdk).

## Sources

Checked 25 October 2026.

- [OpenAI Agents SDK: sandbox clients](https://openai.github.io/openai-agents-python/sandbox/clients/):
  `UnixLocalSandboxClient`, `DockerSandboxClient` and the hosted clients, and
  what each is for
- [OpenAI Agents SDK: tools](https://openai.github.io/openai-agents-python/tools/):
  `CodeInterpreterTool` and its `OpenAIResponsesModel` requirement
- [openai-agents on PyPI](https://pypi.org/project/openai-agents/): version 0.24.0
- [@openai/agents on npm](https://www.npmjs.com/package/@openai/agents): version 0.21.0

Facts on this page were checked on 25 October 2026.