cocoonstack-sandbox-openai plugs cocoon microVMs into the
OpenAI Agents SDK as a
custom sandbox provider, so an Agents run executes its shell/file tools
inside a real hardened VM instead of a local process or container.
from cocoonsandbox_openai import CocoonSandboxClient, CocoonSandboxClientOptions
client = CocoonSandboxClient()
session = await client.create(options=CocoonSandboxClientOptions(
addr="10.0.0.5:7777",
api_token="...",
template="ghcr.io/cocoonstack/sandbox/rt:24.04",
))
async with session:
result = await session.exec("python3", "script.py", shell=False)
await client.delete(session)
Wire it into a run via the SDK’s SandboxRunConfig the same way the
built-in providers (Docker, UnixLocal) are; CocoonSandboxClient is a
drop-in BaseSandboxClient.
The adapter implements the SDK’s BaseSandboxClient / BaseSandboxSession
pair over the sync Python SDK, bridged with
asyncio.to_thread:
| SDK surface | cocoon |
|---|---|
create |
Client.new — one claimed sandbox per session |
session exec |
Sandbox.run (stdout/stderr/exit); a per-call timeout is run’s wall clock and surfaces as TimeoutError |
read / write |
Sandbox.read_file / write_file; a missing path on read → FileNotFoundError; a per-call user raises NotImplementedError (fs verbs carry no user on the wire) |
persist_workspace / hydrate_workspace |
Sandbox.pull / push (tar) |
| exposed port | Sandbox.proxy_port |
delete |
Sandbox.close (release) |
resume |
reattach from the serialized session state: node address, api token, sandbox id, sandbox token, owner |
CocoonSandboxClientOptions carries the node address, api token, template
ref, network lane (empty for the node’s default, or none/egress), and
TTL. The session state is
JSON-serializable, so a run can be resumed against the same sandbox after a
process restart. Requires Python 3.10+ (the Agents SDK floor); the
underlying cocoonsandbox stays 3.9+.