Runtime for the OpenAI Agents SDK

Run a SandboxAgent's shell, files and manifest in a Runtime sandbox, in Python or TypeScript, with the agent unchanged.

RuntimeCloudSandboxClient is a sandbox client for the OpenAI Agents SDK, like its Docker, E2B or Modal clients. Change the client in the run configuration and the same agent runs in a Firecracker microVM with its own kernel, billed for the CPU it uses.

Python

Terminalpip install "withruntime[openai-agents]"

Pythonfrom agents import Runnerfrom agents.run import RunConfigfrom agents.sandbox import Manifest, SandboxAgent, SandboxRunConfigfrom agents.sandbox.entries import Filefrom withruntime.openai_agents import RuntimeCloudSandboxClient, RuntimeCloudSandboxClientOptionsagent = SandboxAgent(    name="Analyst",    instructions="Answer from the files in the workspace.",    default_manifest=Manifest(entries={"sales.csv": File(content=b"month,total\nJuly,120\nAugust,180\n")}),)run_config = RunConfig(    sandbox=SandboxRunConfig(        client=RuntimeCloudSandboxClient(),        options=RuntimeCloudSandboxClientOptions(funding="trial"),    ))print(Runner.run_sync(agent, "How much did sales grow?", run_config=run_config).final_output)

The key comes from RUNTIME_API_KEY or this machine's npx withruntime login, as for the rest of the SDK. Pass RuntimeCloudSandboxClient(runtime=AsyncRuntime(...)) to share a client.

TypeScript

Terminalnpm install withruntime @openai/agents

TypeScriptimport { run } from "@openai/agents";import { SandboxAgent } from "@openai/agents/sandbox";import { RuntimeCloudSandboxClient } from "withruntime/openai-agents";export async function analyse() {  const agent = new SandboxAgent({    name: "Analyst",    instructions: "Answer from the files in the workspace.",    defaultManifest: {      entries: { "sales.csv": { type: "file", content: "month,total\nJuly,120\nAugust,180\n" } },    },  });  const client = new RuntimeCloudSandboxClient({ create: { funding: "trial" } });  const result = await run(agent, "How much did sales grow?", { sandbox: { client } });  return result.finalOutput;}

Options

Every option is optional.

Python	TypeScript	What it does
`funding`, `image`, ...	`create`	How to create the sandbox: `funding`, `region`, `image`, a snapshot, `vcpu`, memory, disk, `name`, `labels`
`snapshot_id`	`create.snapshot`	Start from a ready Runtime snapshot, with its files, memory and processes
`extra`	`create`	Any other create field, such as `network` or `volumes`
`env`	`env`	Set for every command, under the manifest's own environment
`exposed_ports`	`exposedPorts`	Ports `resolve_exposed_port` may share as Runtime previews
`preview_visibility`	`previewVisibility`	`private` (default): the endpoint carries its token in its query; `public`: anyone with the address
`pause_on_exit`	`pauseOnExit`	Pause instead of stopping at the end, so resuming wakes the same machine
`workspace_persistence`	—	`tar` (default) or `snapshot`, below
`snapshot_retention_days`	—	Days a `snapshot` persistence snapshot is kept
`exec_timeout_s`	`execTimeoutMs`	The longest a command may run: one hour by default, 24 hours at most

What runs in the sandbox

Shell with PTY sessions. exec_command returns when the command finishes or its yield time passes; a command still running keeps a session that write_stdin polls. With tty it gets a terminal and takes typed input.
Files. Reads, writes and apply_patch edits of any size, image views, listings, and paths outside the workspace that the manifest grants.
The manifest. Files, directories, local files and directories, git repositories, environment variables, and users and groups. Commands with a user run through sudo -u; you are root inside your own sandbox.
Exposed ports become Runtime previews at runtimehost.com. A private preview's endpoint works in a browser or any client that keeps cookies.

Keep a workspace between runs

Give the run a snapshot store, such as LocalSnapshotSpec, and a stopped session's workspace comes back when it resumes.

workspace_persistence="tar" (the default) keeps the workspace as an archive; resuming starts a new sandbox and unpacks it.
workspace_persistence="snapshot" keeps the whole machine as a Runtime snapshot: the workspace, every other file, installed packages, memory, and processes started outside the agent's PTY sessions. Resuming starts a copy of it. The snapshot is billed as snapshot storage (pricing).
pause_on_exit pauses the sandbox instead, and resuming wakes the same machine where it stopped.

In TypeScript, pauseOnExit resumes the same machine, and persistWorkspace() and hydrateWorkspace() move a workspace as a tar.

Function tools for an ordinary agent

An Agent that is not a SandboxAgent can take the four framework tools: runtime_exec, runtime_read_file, runtime_write_file and runtime_list_files.

Pythonfrom agents import Agent, function_toolfrom withruntime import Sandboxfrom withruntime.tools import sandbox_toolsdef coder(sbx: Sandbox) -> Agent:    return Agent(name="Coder", tools=[function_tool(f) for f in sandbox_tools(sbx)])

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

What was verified

On 23 September 2026 both clients ran SandboxAgent in the SDK's own runner against real trial sandboxes, driven by the SDK's scripted test model: OpenAI Agents SDK 0.22.3 in Python and 0.18.0 in TypeScript. Between them the runs covered commands, a long command polled through write_stdin, a terminal session, apply_patch, manifests with files, users, git repositories and local directories, a private preview, tar and snapshot persistence, pause and resume, and cleanup, with no sandbox left running.