# 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](/docs/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.

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

```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(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`:

```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({ 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](/docs/openai-agents-sdk).

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

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

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

```python check
from withruntime.openai_agents import RuntimeCloudSandboxClientOptions

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

For running many coding agents at once, 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 September 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.22.3
- [@openai/agents on npm](https://www.npmjs.com/package/@openai/agents): version 0.18.0

Facts on this page were checked on 25 September 2026.