WBX Sandbox
Integrations

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

OptionDefaultMeaning
template"base"Base image – see Templates
name–Named sandbox: an existing one with this name is reused and its workspace kept
timeout_s3600Lifetime 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_classaccount defaultCompute class
vcpu, mem_mbtemplateSize of the VM
internet, allow, blockfull internetNo network, an allowlist or extra blocked destinations – see Network
ipteam 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
Secrets go to the client, not the options. Options can be saved in the run state. Put API tokens for the agent’s commands into 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_wbxsandbox in 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.