OpenAI Agents

Use Sandbox0 as the backend for OpenAI Agents SDK SandboxAgent runs through the Sandbox0 Python SDK adapter. The adapter maps the OpenAI workspace to /workspace on the sandbox writable rootfs.

Requirements#

• Python 3.10 or later
• sandbox0[openai-agents]
• SANDBOX0_TOKEN
• optional SANDBOX0_BASE_URL for a self-hosted deployment

bash
pip install "sandbox0[openai-agents]"

Basic Usage#

python
import asyncio

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import SandboxAgent, SandboxRunConfig

from sandbox0_openai_agents import Sandbox0SandboxClient, Sandbox0SandboxClientOptions


async def main() -> None:
    client = Sandbox0SandboxClient()
    agent = SandboxAgent(
        name="sandbox0-demo",
        instructions="Use the sandbox for filesystem and command execution tasks.",
    )

    result = await Runner.run(
        agent,
        "Create hello.txt in the workspace, print it, and summarize what you did.",
        run_config=RunConfig(
            sandbox=SandboxRunConfig(
                client=client,
                options=Sandbox0SandboxClientOptions(template="default"),
            ),
            workflow_name="Sandbox0 OpenAI Agents demo",
        ),
    )
    print(result.final_output)


asyncio.run(main())

Lifecycle And Persistence#

For a fresh session, the adapter claims a sandbox and uses its /workspace directory directly. start() reconnects to a running sandbox or resumes a paused one. stop() creates a best-effort named rootfs snapshot by default and stores its ID in Sandbox0SandboxSessionState.

If the original sandbox is unavailable, the adapter can claim a replacement from rootfs_snapshot_id. This creates a new isolated writable rootfs from the saved workspace state.

Runner-owned cleanup deletes the sandbox and, by default, the adapter-created rootfs snapshot. Preserve the snapshot when serialized run state must resume after cleanup:

python
options = Sandbox0SandboxClientOptions(
    template="default",
    delete_sandbox_on_delete=True,
    delete_rootfs_snapshot_on_delete=False,
)

Start directly from a known workspace snapshot:

python
options = Sandbox0SandboxClientOptions(
    template="default",
    rootfs_snapshot_id="snap_abc123",
)

Options#

Adapter file operations use the live sandbox file API, and shell commands run through a Sandbox0 CMD context with /workspace as the working directory. Generic OpenAI SDK snapshot specs are not accepted; use rootfs_snapshot_id for Sandbox0 workspace persistence.

Next Steps#