Skip to main content

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.0
  • opensandbox>=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/ExecTransportError with 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_endpoint URL mapping.

Not supported in this version (rejected explicitly, never silently):

  • PTY / interactive stdin sessions (supports_pty() is False; the SDK shell tool automatically uses one-shot exec instead).
  • Storage mounts (Mount manifest entries raise MountConfigError).
  • Sandbox users mapping (uid/gid execution) 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)

Source distribution for opensandbox-openai-agents 0.1.0
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)

Table of built distributions (wheels) for opensandbox-openai-agents 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page