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
• model-provider authentication, normally OPENAI_API_KEY when using OpenAI; the Sandbox0 token authenticates sandbox operations only
• optional SANDBOX0_BASE_URL to override the API endpoint; Sandbox0 Cloud is the default

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. The adapter's explicit resume call uses filesystem-only resume; this integration does not implement retained-process memory restoration. stop() attempts a named RootFS snapshot by default and stores its ID in Sandbox0SandboxSessionState. It is a persistence operation and does not pause or delete the sandbox's compute.

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. Snapshots capture the writable RootFS, not only /workspace, and do not retain processes, memory, or runtime-only mounts. They remain subject to expiry and retention limits. Snapshot API errors during stop() can leave the state with an older snapshot ID or no snapshot. Verify the saved ID before depending on it for recovery. If there is no snapshot and the original sandbox is unavailable, a replacement starts from the template without the old files.

Runner-owned cleanup deletes the sandbox and, by default, the current saved RootFS snapshot, including one supplied by the caller. Preserve that 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,
)

On a successful new snapshot, stop() replaces the state's snapshot ID and attempts to delete the previous one even when delete_rootfs_snapshot_on_delete is false. That option controls client cleanup, not historical snapshot retention. Use explicit snapshot management when older restore points must live.

Start directly from a known workspace snapshot:

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

This borrowed-snapshot example keeps the source snapshot. With snapshot-on-stop disabled, it does not automatically create a restore point for later changes.

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. To publish a listener, configure a Sandbox Service or Private Preview explicitly. exposed_ports alone does not configure network ingress or return a public URL.

Next Steps#