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.createorfunctools.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¶
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¶
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.
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/.