OpenSandbox

OpenSandbox is the Python client SDK for the OpenSandbox platform, a general-purpose sandbox runtime built for AI agent workloads such as coding agents, GUI agents, and code interpreters. The SDK talks to a running OpenSandbox server (Docker or Kubernetes backed) over HTTP, giving Python code a typed interface for creating sandboxes, running shell commands, streaming output, and managing files inside them.

Beyond single-sandbox operations, the SDK ships a SandboxManager for administrative tasks like listing and killing running sandboxes, plus a full sandbox pooling layer (SandboxPoolAsync/SandboxPoolSync) with pluggable state stores — in-memory for local development, Redis-backed for distributed, multi-process deployments — to keep a warm buffer of ready sandboxes and cut acquire latency in production agent services.

What You Get

• An async Sandbox client (plus a SandboxSync mirror) for creating sandboxes from a container image, running commands, and streaming stdout/stderr/completion events via handler callbacks
• A filesystem adapter for writing, reading, searching, and deleting files inside a sandbox, including chunked uploads for large payloads
• A SandboxManager for admin operations — listing running sandboxes by filter and force-killing them
• SandboxPoolAsync/SandboxPoolSync with an in-memory state store for single-process use and a Redis-backed store for distributed, multi-pod pool coordination
• Typed exception hierarchy (SandboxApiException, SandboxRateLimitException, SandboxTimeoutException, SandboxConnectionException, pool-specific exceptions) with request IDs for correlating failures against server logs
• An optional pool-redis extra for production deployments that need shared pool state across processes

Common Use Cases

• Giving a coding agent (e.g. Claude Code style tooling) a disposable sandbox to execute untrusted or generated code safely
• Running an AI code interpreter that needs to execute Python/shell snippets and read back files or stdout
• Backing an agent evaluation or RL training pipeline that needs many short-lived, isolated execution environments at scale
• Maintaining a warm pool of pre-created sandboxes in a production agent service to avoid cold-start latency on every request
• Automating browser or desktop agent workflows (Chrome, Playwright, VNC, VS Code) inside a controlled sandbox

Under The Hood

Architecture The SDK is organized around a facade (sandbox.py) that developers interact with directly, backed by a set of per-resource adapters (adapters/filesystem_adapter.py, execd/command adapters, and others) that translate typed method calls into HTTP requests against the OpenSandbox server’s generated OpenAPI client (kept under api/ and deliberately excluded from lint/type-check as generated code). Administrative operations live in a separate manager.py, while sandbox pooling is its own subsystem (pool.py, pool_async.py, _pool_reconciler.py, _async_pool_reconciler.py) built around a state-store abstraction with in-memory and Redis-backed implementations coordinated through a primary-lock protocol for distributed replenish/shrink. A parallel sync/ package mirrors the entire async surface for synchronous callers, and config/ centralizes connection settings for both variants. Changing the core Sandbox abstraction would ripple through the adapters, the pool’s creation spec, and the sync mirror layer, since all three depend on its lifecycle contract.

Tech Stack Built for Python 3.10+ using hatchling with hatch-vcs for git-tag-derived versioning (scoped to this monorepo subdirectory via a custom tag regex), the SDK relies on httpx and httpx-sse for async and sync HTTP plus server-sent-event streaming, pydantic 2.x and attrs for typed models, and python-dateutil for date handling. An optional pool-redis extra pulls in redis and pyjwt for distributed pool state. Tooling is ruff for linting, pyright for type-checking, and pytest with pytest-asyncio and pytest-cov for the test suite, all managed through uv.

Code Quality The repository carries a substantial test suite (44 test files) covering filesystem upload transport behavior including chunked uploads, converters and error handling, connection-config environment-variable and timeout parsing, lifecycle metrics, and pool configuration — with explicit coverage of both async and sync code paths. Errors are modeled as an explicit typed hierarchy (SandboxException and subclasses like SandboxApiException, SandboxRateLimitException, SandboxTimeoutException, SandboxConnectionException, and pool-specific exceptions) rather than being swallowed, and each carries a request ID for correlating client-side failures with server logs. CI includes dedicated workflows for SDK tests, dependency stability, and release preflight checks ahead of publishing to PyPI.

API Design The SDK’s async/sync parity is its most developer-friendly trait: every async class (Sandbox, SandboxManager, SandboxPoolAsync) has a directly corresponding sync class (SandboxSync, SandboxPoolSync) with matching method names and semantics, so teams can adopt whichever concurrency model fits their codebase without relearning the API. Lifecycle methods are named to avoid ambiguity — close() releases only local resources, kill()/destroy() also terminate the remote sandbox — and streaming output uses a small ExecutionHandlers callback struct rather than requiring manual async iteration. Getting started requires only a handful of lines: configure a ConnectionConfig, create a sandbox from an image name, and run a command.