openai-agents-wbxsandbox
WBX Sandbox as a hosted sandbox for OpenAI Agents SDK sandbox agents. Each sandbox is an isolated Linux microVM with its own kernel, disk and network policy. The agent's shell and file tools run there, not on your machine.
pip install openai-agents-wbxsandbox
export WBXSANDBOX_API_KEY=... # API key from https://sandbox.wbx.cz (Settings → API keys)
export OPENAI_API_KEY=...
Quick start
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. Work in the workspace.",
)
run_config = RunConfig(
sandbox=SandboxRunConfig(
client=WBXSandboxClient(), # API key from WBXSANDBOX_API_KEY
options=WBXSandboxClientOptions(template="base"),
),
)
async def main() -> None:
result = await Runner.run(
agent,
"Which Python version is installed? Write it to version.txt.",
run_config=run_config,
)
print(result.final_output)
asyncio.run(main())
The runner creates the sandbox, gives the agent its shell and file tools, and deletes the sandbox when the run ends.
Supported versions
| Package | Tested range |
|---|---|
openai-agents |
>=0.25.0,<0.26 |
wbxsandbox |
>=0.15.7,<0.16 |
| Python | 3.10 – 3.13 |
The integration uses the SDK's sandbox provider interface, which is still evolving, so the
dependency on openai-agents is pinned to the tested minor version. A new release of this
package follows each tested SDK minor version.
Configuration
WBXSandboxClient holds the credentials. They stay on the live object and are never written
into run state:
| Argument | Default | Meaning |
|---|---|---|
api_key |
WBXSANDBOX_API_KEY, then WBX_API_KEY |
API key of your WBX Sandbox account |
url |
WBXSANDBOX_URL or https://sandbox.wbx.cz |
API address |
env |
– | Secret environment variables for every command (API tokens) |
WBXSandboxClientOptions describes the sandbox. Options may be saved in run state, so do not
put secrets here:
| Option | Default | Meaning |
|---|---|---|
template |
"base" |
Base image: base (Debian, Python 3.12), code-interpreter, node, go, browser, … |
name |
– | Named sandbox: an existing sandbox 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 name) |
"kill" deletes the sandbox after the run; "sleep" keeps its files for a later resume |
idle_timeout_s |
– | With on_exit="sleep": fall asleep after this many idle seconds |
compute_class |
account default | economy, balanced, performance, memory, dedicated |
vcpu, mem_mb |
template default | Size of the VM |
internet |
True |
False = no network at all |
allow |
– | Allowlist of reachable domains or addresses |
block |
– | Additional blocked destinations |
ip |
team default | "ipv4", "dual" or "ipv6" (own public IPv6 address) |
env |
– | Non-secret environment variables |
metadata |
– | Your labels, shown when listing sandboxes |
exposed_ports |
– | Ports the agent or your code may resolve to a public HTTPS URL |
Network settings can only make your account's policy stricter, never looser.
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 are kept, running
programs stop and compute is not 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. Sleeping
sandboxes are kept for the retention time of your plan.
Exposed ports
options = WBXSandboxClientOptions(exposed_ports=(8000,))
endpoint = await session.resolve_exposed_port(8000)
print(endpoint.url_for("http")) # https://8000-….wbxbox.net/?…token…
The URL contains an access token. On the first request the token moves to a cookie (a
redirect), so open it in a browser or with an HTTP client that keeps cookies
(requests.Session, httpx.Client, urllib with HTTPCookieProcessor). Anyone with the URL can
reach the port, so treat it like a password. The app must listen on 0.0.0.0.
Lifecycle and resume
- With
SandboxRunConfig(client=...)the runner owns the session: it starts it, snapshots the workspace when a snapshot is configured, and then callsdelete, which deletes the sandbox (on_exit="kill") or puts it to sleep (on_exit="sleep"). - With a live
session=your code owns the session: close it withawait session.aclose()and thenawait client.delete(session). resumereconnects to the sandbox recorded in the saved state (and wakes it up if it sleeps). If the sandbox no longer exists, a new one is created and its workspace is restored from the configured snapshot. The API only returns sandboxes of the account behind the client's API key, so a saved state cannot attach to someone else's sandbox.- Import
openai_agents_wbxsandboxin every process that restores saved run state; the import registers thewbxstate type.
Saved state contains the sandbox ID and name, the template and the creation options (including
non-secret env), never the API key or WBXSandboxClient(env=...). Fields are only added with
defaults, so states saved by 0.1.x keep working in later 0.x releases.
How it works
| SDK operation | WBX Sandbox |
|---|---|
create |
create a sandbox (template, class, size, network, name, lifetime) |
resume |
reconnect by ID and wake it up; recreate from the snapshot if it is gone |
delete |
delete the sandbox, or put it to sleep with on_exit="sleep" |
exec |
run the command with sh -c in the workspace (/workspace by default) |
shell tool (exec_command, write_stdin) |
the command runs in the background in the VM; after yield_time_ms the agent gets the output so far and a session ID, then polls it, so long builds and installs are not cut off |
read / write |
file download / upload; paths are resolved inside the VM so they cannot leave the workspace |
persist_workspace / hydrate_workspace |
tar of the workspace, validated before extraction |
| exposed ports | public HTTPS URL with an access token |
Commands run as root inside the VM. The VM is the isolation boundary; nothing runs on the
machine of the application.
Limitations
- Manifest mounts (S3, GCS, R2, Azure Blob, Box) are not supported yet; creating a sandbox with
a mount fails with a clear
ConfigurationError. Copy the data into the workspace instead. - Host path grants (
extra_path_grantswith a host path) are rejected: the sandbox is a remote VM. - No terminal device: commands run with stdin closed, so interactive programs (REPLs, prompts)
get end-of-file and
write_stdinonly accepts empty input (poll) or Ctrl-C (\x03). - Command output is captured as UTF-8 text (invalid bytes are replaced) and limited to 16 MB per stream. Use file reads for binary data.
- Background processes stop when the sandbox falls asleep; files are kept.
Examples
examples/fix_tests– the agent fixes failing tests in a small repository.examples/csv_chart– the agent analyzes a CSV file and returns a chart.
Development
pip install -e ".[test]"
pytest # unit and runner tests, no network
WBXSANDBOX_API_KEY=... pytest -m live # tests against the real service
License
MIT
Metadata
Release files for openai-agents-wbxsandbox 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| openai_agents_wbxsandbox-0.1.0.tar.gz | 31.1 kB | With provenance | Details for openai_agents_wbxsandbox-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| openai_agents_wbxsandbox-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for openai_agents_wbxsandbox-0.1.0-py3-none-any.whl |
Total release size: 49.6 kB
Release files / openai_agents_wbxsandbox-0.1.0.tar.gz
| Download URL | openai_agents_wbxsandbox-0.1.0.tar.gz |
|---|---|
| Size | 31.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
59f291acdb06b6aaa0f8d59fd422b8c1140b89ba61d66fe05e633e52f36e407a
|
|
BLAKE2b-256 checksum How to use checksums |
b85f3acd13705f26a0e5ebd88cd5f7c35b6a625120f3736b24d942dfa01cae9d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / openai_agents_wbxsandbox-0.1.0-py3-none-any.whl
| Download URL | openai_agents_wbxsandbox-0.1.0-py3-none-any.whl |
|---|---|
| Size | 18.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
32a6e29da56bb82429fc24c5a41f62528cd3e6880ab206d6969c9209e86567ca
|
|
BLAKE2b-256 checksum How to use checksums |
02e07087099e232d3b99098112371d2aa04bb1f954b781ba0a2f07030cafd9e3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for openai-agents-wbxsandbox 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for openai_agents_wbxsandbox-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.