kosa8

kosa8 / Guides

Guide · Updated 2026-10-31

How do I give the OpenAI Agents SDK a local sandbox?

Use the SDK's own DockerSandboxClient and point the Docker client at kosa8: start the kosa8 daemon, set DOCKER_HOST to its socket, and the agent's sandbox becomes a container inside a microVM on your own Mac or Linux machine, with no change to your code and no cloud account. kosa8 tested this with openai-agents 0.24.0 by driving the sandbox client directly; a full agent run with a model was not part of that test.

01Steps

  1. Install kosa8. On an Apple silicon Mac or x86-64 Linux:

  2. Start the daemon and point Docker clients at kosa8. kosa8 serves a Docker-compatible API on a local socket. The Docker SDK for Python reads DOCKER_HOST.

  3. Install the SDK with Docker support. This is the set kosa8 tested with (openai-agents 0.24.0, docker 7.2.0, Python 3.12).

  4. Run a sandbox session. This script creates the sandbox, writes a file, runs it in /workspace, exports the workspace as a tar stream and deletes the sandbox. docker.from_env() reads DOCKER_HOST, so the same code runs against Docker when the variable is unset.

    sandbox_on_kosa8.py
    import asyncio, io
from pathlib import Path
import docker
from agents.sandbox.sandboxes.docker import DockerSandboxClient, DockerSandboxClientOptions
 
async def main():
    client = DockerSandboxClient(docker.from_env())  # reads DOCKER_HOST
    session = await client.create(options=DockerSandboxClientOptions(image="python:3.12-slim"))
    try:
        await session.start()
        await session.write(Path("hello.py"), io.BytesIO(b"print('hello from kosa8')\n"))
        result = await session.exec("pwd && python hello.py")
        print(result.exit_code, result.stdout.decode().strip())
        tar = await session.persist_workspace()
        print("workspace tar:", len(tar.read()), "bytes")
    finally:
        await client.delete(session)
 
asyncio.run(main())
    output
    python sandbox_on_kosa8.py
0 /workspace
hello from kosa8
workspace tar: 10240 bytes

  5. Give the client to an agent run. OpenAI's docs pass the client in the run config, so the agent definition stays the same when you switch backends. This step was not run with a model.

    run_config.py
    from docker import from_env as docker_from_env
from agents.run import RunConfig
from agents.sandbox import SandboxRunConfig
from agents.sandbox.sandboxes.docker import DockerSandboxClient, DockerSandboxClientOptions
 
run_config = RunConfig(
    sandbox=SandboxRunConfig(
        client=DockerSandboxClient(docker_from_env()),
        options=DockerSandboxClientOptions(image="python:3.12-slim"),
    ),
)

02Does the Agents SDK's UnixLocalSandboxClient isolate my machine?

No. OpenAI's sandbox clients page says UnixLocalSandboxClient runs commands as local host processes. On Linux it adds no OS-level confinement, and on macOS it uses sandbox-exec for filesystem restrictions, which do not provide network isolation or the same boundary as a container. OpenAI recommends it for trusted local development or inside external isolation.

It is the fastest way to iterate, and a reasonable choice when the agent runs only code you would run yourself. For code you have not read, use a client with a boundary, such as DockerSandboxClient.

03Where does the Docker sandbox run when DOCKER_HOST points at kosa8?

It runs as a container in kosa8's shared engine, one always-warm virtual machine on your computer. The container is separated from your computer by a VM boundary with its own kernel, and from other containers in that VM by ordinary container isolation.

Two details from kosa8's test: bind mounts work only below a folder named with kosa8 daemon start --allow-mount DIR (add :rw for write access), and Apple silicon runs arm64 images, so pick an image published for linux/arm64, such as the official python images.

04Do I need to change my Agents SDK code to use kosa8?

No. The SDK's DockerSandboxClient takes a Docker client, and docker.from_env() reads DOCKER_HOST. Setting that variable to kosa8's socket is the only change; unset it and the same code talks to Docker again.

05Can I run the Agents SDK sandbox without a cloud sandbox service?

Yes. The sandbox, its files and the commands the agent runs stay on your machine; only the model calls go to whichever model provider your agent uses, and the image is pulled from its registry the first time. Containers created through kosa8's Docker-compatible API run in its shared engine: one always-warm virtual machine, separated from your computer by a VM boundary and from other containers in it by ordinary container isolation. For a machine of its own per task, with its own egress rules and checkpoints, use kosa8 sandbox directly, as in the LangChain guide.

06Other options

  • UnixLocalSandboxClient. No extra install and the fastest loop, for trusted code or inside another boundary such as a VM.
  • DockerSandboxClient with Docker. The same code against Docker Desktop or Docker Engine. Containers share the host's kernel on Linux.
  • Hosted sandbox clients. OpenAI's docs list clients for Blaxel, Cloudflare, Daytona, E2B, Modal and Vercel, a fit when the agent's work should run in the cloud.
  • gVisor. On Linux, the runsc runtime puts a user-space kernel between the container and the host.
  • A full VM in UTM or Lima. Run the whole agent process inside a VM when the agent itself, not only its tools, should be contained.

07Sources

Updated 2026-10-31