OpenAI Agents SDK
Run the shell and file tools of an OpenAI Agents SDK sandbox agent in a WBX sandbox – an isolated Linux microVM – instead of on your own machine. One package, one line in the run configuration.
Install
pip install openai-agents-wbxsandbox
export WBXSANDBOX_API_KEY=YOUR_API_KEY # Settings → API keys
export OPENAI_API_KEY=…
Tested with openai-agents 0.25 and Python 3.10–3.13. The package uses the Python SDK for every call.
Quickstart
import asyncio
from agents import Runner
from agents.run import RunConfig
from agents.sandbox import SandboxAgent, SandboxRunConfig
from openai_agents_wbxsandbox import WBXSandboxClient, WBXSandboxClientOptions
agent = SandboxAgent(name="Workspace assistant", instructions="Use the shell to answer.")
run_config = RunConfig(
sandbox=SandboxRunConfig(
client=WBXSandboxClient(), # API key from WBXSANDBOX_API_KEY
options=WBXSandboxClientOptions(template="base"),
),
)
async def main():
result = await Runner.run(agent, "Which Python version is installed?", run_config=run_config)
print(result.final_output)
asyncio.run(main())
The runner creates a sandbox, the agent works in its /workspace and the sandbox is deleted when the run ends. You pay only for the seconds it ran.
Options
| Option | Default | Meaning |
|---|---|---|
template | "base" | Base image – see Templates |
name | – | Named sandbox: an existing one with this name is reused and its workspace kept |
timeout_s | 3600 | Lifetime in seconds (your plan’s maximum applies) |
on_exit | "kill" ("sleep" with a name) | "kill" deletes the sandbox after the run, "sleep" keeps its files for later |
idle_timeout_s | – | With on_exit="sleep": fall asleep after this many idle seconds |
compute_class | account default | Compute class |
vcpu, mem_mb | template | Size of the VM |
internet, allow, block | full internet | No network, an allowlist or extra blocked destinations – see Network |
ip | team default | "ipv4", "dual" or "ipv6" with its own public IPv6 address |
env | – | Non-secret environment variables |
exposed_ports | – | Ports that can get a public HTTPS URL |
WBXSandboxClient(env={...}) – they are sent to the sandbox but never serialized.Keep the workspace between runs
options = WBXSandboxClientOptions(name="report-builder", on_exit="sleep")
After the run the sandbox falls asleep instead of being deleted: files stay, running programs stop and no compute is billed. The next run with the same name – or a resume from saved run state – wakes it up in a few seconds and continues in the same workspace.
Resume and snapshots
- Resume reconnects to the sandbox from the saved run state and wakes it up. If the sandbox no longer exists, a new one is created and its workspace restored from the snapshot you configured (e.g.
LocalSnapshotSpec). - A saved state can only reconnect to sandboxes of the account behind your API key.
- Import
openai_agents_wbxsandboxin every process that restores saved run state.
Not supported yet
- Manifest mounts (S3, GCS, R2, Azure Blob, Box) – the run fails with a clear error before a sandbox is created. Copy the data into the workspace instead.
- Interactive input – commands have no terminal, so prompts and REPLs get end-of-file. Long commands (builds, installs) are fine: they keep running and the agent polls their output.
- Command output is text (UTF-8) up to 16 MB per stream; read binary results as files.
Examples (fix failing tests, CSV to chart) and source: github.com/WBX-Sandbox/openai-agents-wbxsandbox · package: pypi.org/project/openai-agents-wbxsandbox.