opensandbox-openai-agents
OpenSandbox sandbox provider for the
OpenAI Agents SDK (openai-agents).
This package implements the Agents SDK sandbox client/session interfaces on top of the
OpenSandbox Python SDK (opensandbox), so agents can run their shell tool and workspace
I/O inside a remote OpenSandbox sandbox. It follows the SDK's
external sandbox provider guide:
the provider ships in its own distribution, and applications pass the client to
SandboxRunConfig(client=...) explicitly. The Agents SDK does not need to import this
package or register any entry points.
Install
pip install opensandbox-openai-agents
Pinned compatibility ranges (tested together):
openai-agents>=0.24.0,<0.25.0opensandbox>=1.2.0,<2.0.0
Usage
from agents import RunConfig, Runner
from agents.sandbox import SandboxRunConfig
from opensandbox.config import ConnectionConfig
from opensandbox_agents import OpenSandboxClient, OpenSandboxClientOptions
client = OpenSandboxClient(
connection_config=ConnectionConfig(
domain="sandbox.example.com", # your OpenSandbox API endpoint
api_key="<access_key_id>:<secret_key>",
protocol="https",
),
)
run_config = RunConfig(
sandbox=SandboxRunConfig(
client=client,
options=OpenSandboxClientOptions(
image="opensandbox/code-interpreter:latest",
sandbox_ttl_s=3600, # optional sandbox TTL
resource={"cpu": "1", "memory": "2Gi"},
env_vars={"MY_VAR": "value"},
),
),
)
result = await Runner.run(agent, "inspect the workspace", run_config=run_config)
The connection configuration (endpoint and credentials) lives on the client and is never serialized. Options are serializable and round-trip through persisted session state; keep them free of secrets.
Options
| Option | Type | Default | Meaning |
|---|---|---|---|
image |
str | None |
— | Sandbox image. Exactly one of image/snapshot_id is required. |
snapshot_id |
str | None |
— | Create from an OpenSandbox image snapshot instead of a raw image. |
workspace_root |
str |
/workspace |
Workspace root inside the sandbox (agent cwd). |
env_vars |
dict[str, str] | None |
— | Environment variables injected at creation. |
metadata |
dict[str, str] | None |
— | Provider metadata labels. |
resource |
dict[str, str] | None |
— | Resource spec, e.g. {"cpu": "1", "memory": "2Gi"}. |
entrypoint |
tuple[str, ...] | None |
— | Container entrypoint override. |
sandbox_ttl_s |
int | None |
— | Sandbox time-to-live in seconds. |
ready_timeout_s |
int |
60 |
Readiness wait when creating. |
pause_on_exit |
bool |
False |
Pause instead of delete when the session shuts down. |
timeouts |
OpenSandboxTimeouts | dict |
— | Per-operation timeout overrides (seconds). |
exposed_ports |
tuple[int, ...] |
() |
Ports resolvable via the exposed-port endpoint API. |
Resume behavior
Persisted state carries the sandbox id. On resume the provider reconnects to the existing
sandbox; if it is unreachable it recreates one from the recorded creation inputs and
restores the workspace from the SDK snapshot. When the session exits with
pause_on_exit=True, resume first tries the OpenSandbox pause/resume path.
Capability notes and limitations
Implemented on top of OpenSandbox execd (commands + files APIs):
- Shell command execution with wall-clock timeout mapping, per-command environment, and
workspace-root cwd (
ExecTimeoutError/ExecTransportErrorwith retryability metadata). - File read/write within the workspace, with path-confinement validation against the workspace root.
- Workspace persistence: tar snapshot/restore over the execd file API, including the Agents SDK snapshot/resume semantics.
- Lifecycle: create, resume/recreate, delete (kill or pause), TTL, metadata, resources.
- Exposed ports via
get_endpointURL mapping.
Not supported in this version (rejected explicitly, never silently):
- PTY / interactive stdin sessions (
supports_pty()isFalse; the SDK shell tool automatically uses one-shot exec instead). - Storage mounts (
Mountmanifest entries raiseMountConfigError). - Sandbox users mapping (
uid/gidexecution) beyond the default account.
The provider image must run OpenSandbox execd; official opensandbox/* images do.
Development
python -m venv .venv && ./.venv/bin/pip install -e ".[dev]"
./.venv/bin/pytest
Tests are mock-based and require no sandbox service or model API key. demo/demo.py
shows a complete scripted run against a real OpenSandbox endpoint.
License
Apache-2.0. This is an independent integration package and is not affiliated with or endorsed by OpenAI or the OpenSandbox project.
Metadata
Release files for opensandbox-openai-agents 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 |
|---|---|---|---|---|
| opensandbox_openai_agents-0.1.0.tar.gz | 24.4 kB | Without provenance | Details for opensandbox_openai_agents-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| opensandbox_openai_agents-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for opensandbox_openai_agents-0.1.0-py3-none-any.whl |
Total release size: 45.2 kB
Release files / opensandbox_openai_agents-0.1.0.tar.gz
| Download URL | opensandbox_openai_agents-0.1.0.tar.gz |
|---|---|
| Size | 24.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6d7a47e4f101bb2ada95fafd31b5267ac88928eaff198f06f0438b97bd6156f5
|
|
BLAKE2b-256 checksum How to use checksums |
972909346f85cef041e9aedf765b91995d8a7752c32e1c31e7a96c3072a55267
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.0
|
Release files / opensandbox_openai_agents-0.1.0-py3-none-any.whl
| Download URL | opensandbox_openai_agents-0.1.0-py3-none-any.whl |
|---|---|
| Size | 20.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8992dbed8284020b4d3bc36a171975f51d82afc1ecc4ed3a7218e22ec8c48e91
|
|
BLAKE2b-256 checksum How to use checksums |
4e8c9a50deb7f34c1dabc28df24d3c0ed9da1593caf964676ca58c7b643a62ac
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.0
|
Security for opensandbox-openai-agents 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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A 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.