Skip to content

How to use sandboxio from LangGraph, the OpenAI Agents SDK and MCP

Both agent integrations have a complete, CI-executed program: examples/05_langgraph_agent.py and examples/06_openai_agents.py. Each runs its sandboxio half with no API key set, so you can watch the tool work before spending a token.

Each integration returns the framework's native tool object wrapping run_code or run on a sandbox you provide. The tool descriptions are written for the model: one obvious way, the limits stated. No integration can weaken a default — deny egress, the timeout and the caps come from the sandbox you hand it (spec/09).

Two ways to hand over a sandbox:

  • a ready sandbox — reused across calls; you own its lifetime;
  • a factory such as backend.create or functools.partial(sandboxio.create, "e2b://") — one fresh sandbox per tool call, torn down when the call ends.

Supported framework versions

Extra Package Tested from Tested to
sandboxio[langgraph] langchain-core 0.3 latest
sandboxio[openai-agents] openai-agents 0.19 latest
sandboxio[mcp] mcp 2.0 latest

"Tested from" is not a guess: a weekly CI matrix installs each framework at exactly that version, on its own, and runs the tests that cover it. There is no upper pin — a new release is exercised the following Monday, and an incompatibility becomes our bug to absorb rather than your migration (the version policy).

Older versions may happen to work. They are not tested, so they are not supported.

LangGraph / LangChain

uv add "sandboxio[docker,langgraph]"
import sandboxio
from sandboxio.integrations.langgraph import make_code_tool

async with await sandboxio.create("docker://python:3.12-slim") as sb:
    run_python = make_code_tool(sb)                 # a langchain_core BaseTool
    print(await run_python.ainvoke({"code": "print(2 ** 10)"}))
    # graph = create_react_agent(model, tools=[run_python])

make_command_tool(sb) wraps run the same way. Both take name=, description= and timeout= overrides.

OpenAI Agents SDK

uv add "sandboxio[e2b,openai-agents]"
import functools

import sandboxio
from sandboxio.integrations.openai_agents import make_code_tool

run_python = make_code_tool(functools.partial(sandboxio.create, "e2b://"))   # FunctionTool
# agent = Agent(name="analyst", instructions="...", tools=[run_python])

sandboxio backends as an OpenAI SandboxClient is planned for v0.2 (ADR-0013).

MCP server

Use this when the consumer is an MCP client — Claude Desktop, Cursor, your own agent in another language — rather than your own Python code. The client gets code execution against a sandbox it cannot reconfigure: the backend, the egress policy and the timeout are fixed when you start the process, and no tool runs anything on the host. If you are writing the agent in Python, call sandboxio.create() directly; the protocol hop buys you nothing.

The docker:// backend used below is the CONTAINER tier: a shared kernel, for trusted, dev and CI code. If the client may feed the server code you would not run yourself, start it on an e2b:// backend instead — MICROVM is the documented floor for untrusted code (isolation tiers). The container image defaults to E2B for exactly this reason.

uv add "sandboxio[mcp,docker]"
python -m sandboxio.mcp --backend docker://python:3.12-slim

One sandbox per server process, created on the first tool call and killed at shutdown. Tools: run_python(code), run_command(cmd), read_file(path), write_file(path, content), list_files(path), sandbox_info(). One run_python tool instead of many narrow schemas is the point — it is the MCP code-execution pattern.

Claude Desktop, Cursor and most clients take this shape:

{
  "mcpServers": {
    "sandboxio": {
      "command": "uvx",
      "args": ["--from", "sandboxio[mcp,docker]", "python", "-m", "sandboxio.mcp",
               "--backend", "docker://python:3.12-slim"]
    }
  }
}

Options are fixed for the process: --backend, --timeout, --egress deny|allow, --transport stdio|streamable-http, --host (localhost unless you say otherwise), --port. There is deliberately no tool that changes them at runtime, and no tool ever executes on the host: every call routes through the sandbox.

As a container

docker build -f docker/mcp/Dockerfile -t sandboxio-mcp .
docker run -i --rm -e E2B_API_KEY sandboxio-mcp --backend e2b://code-interpreter-v1

The image is rootless, mounts no Docker socket, and defaults to the E2B backend because a sandbox provider inside the container must be a cloud one. Catalog metadata lives in docker/mcp/.