Skip to content
Runtime

How to run Claude Agent SDK tools in a cloud sandbox

Give the agent Runtime's in-process MCP server, and turn off its local Bash, Read, Write and Edit tools. Its work then runs in a microVM.

Start free, no cardRead as Markdown

On Runtime, the agent's commands leave your server entirely. By default, the Agent SDK's built-in tools act on the machine your application runs on. runtimeMcpServer(sbx) from withruntime/claude-agent-sdk gives the agent four tools. They are bound to one Firecracker microVM with its own Linux kernel. disallowedTools removes the local tools. The sandbox costs $0.03125 an hour while it waits on the model, for 2 vCPUs and 4 GiB. On 25 October 2026, the current releases were @anthropic-ai/claude-agent-sdk 0.3.310 on npm and claude-agent-sdk 0.2.174 on PyPI.

Install

Terminalnpm install withruntime @anthropic-ai/claude-agent-sdk zodnpx withruntime login

zod is needed alongside the SDK. The login prints a link to approve in your browser. On a server, RUNTIME_API_KEY replaces the login. Runtime's adapter ran in the SDK's own loop against real sandboxes on 23 September 2026, with Agent SDK 0.3.277 (what was verified).

Run a query in a sandbox

TypeScriptimport { query } from "@anthropic-ai/claude-agent-sdk";import { Sandbox } from "withruntime";import { RUNTIME_TOOL_NAMES, runtimeMcpServer } from "withruntime/claude-agent-sdk";export async function solve(prompt: string) {  await using sbx = await Sandbox.create();  let answer = "";  for await (const message of query({    prompt,    options: {      mcpServers: { runtime: runtimeMcpServer(sbx) },      allowedTools: RUNTIME_TOOL_NAMES,      disallowedTools: ["Bash", "Read", "Write", "Edit"],    },  })) {    if (message.type === "result" && message.subtype === "success") answer = message.result;  }  return answer;}console.log(await solve("Write a Python script that prints the first 20 primes, and run it."));

What the parts do:

  • runtimeMcpServer(sbx) is an MCP server named runtime. It runs in your process, so there is nothing to launch or connect. Its tools are runtime_exec, runtime_read_file, runtime_write_file and runtime_list_files.
  • RUNTIME_TOOL_NAMES holds their full names as the SDK sees them, such as mcp__runtime__runtime_exec. allowedTools approves them, so no permission prompt appears.
  • disallowedTools takes the local Bash and file tools away. The model cannot touch your server's disk.
  • await using deletes the sandbox when solve returns, even after an error.

Relative paths resolve under /workspace. By default, stdout, stderr and file reads are each cut to 20,000 characters. A noisy build therefore cannot fill the context window.

Where the SDK's tools run by default

Anthropic's secure deployment guide, read on 25 October 2026, says Claude Code and the Agent SDK "can execute code, access files, and interact with external services on your behalf". The guide sets out the ways to contain that:

Isolation Anthropic lists What its guide says With Runtime
sandbox-runtime Uses bubblewrap or sandbox-exec; processes "share the host kernel" Each sandbox has its own kernel
Containers Namespaces "while sharing the host kernel"; hardening is up to you No container to harden; the microVM is the boundary
gVisor Intercepts system calls; file-heavy work "up to 10-200× slower" Ordinary Linux I/O inside the microVM
VMs (Firecracker, QEMU) "Excellent (with correct setup)", "Medium/High" complexity Firecracker microVMs, run by Runtime
Credential proxy Recommends a proxy outside the boundary that injects keys into requests Secrets do this

The guide's recommended pattern for keys is a proxy outside the agent's boundary. The proxy adds credentials to outgoing requests. Runtime secrets work this way. The sandbox holds a placeholder, and the host adds the value only on HTTPS requests to the hosts you name.

Let the agent manage sandboxes itself

When the agent should create, pause and fork sandboxes on its own, connect Runtime's own MCP server instead. This also works from the Python SDK, which accepts stdio MCP servers:

Pythonimport anyiofrom claude_agent_sdk import ClaudeAgentOptions, ResultMessage, queryoptions = ClaudeAgentOptions(    mcp_servers={"runtime": {"type": "stdio", "command": "npx", "args": ["-y", "withruntime", "mcp"]}},    allowed_tools=[        "mcp__runtime__runtime_sandbox_create",        "mcp__runtime__runtime_sandbox_exec",        "mcp__runtime__runtime_sandbox_files_read",        "mcp__runtime__runtime_sandbox_files_write",        "mcp__runtime__runtime_sandbox_manage",    ],    disallowed_tools=["Bash", "Read", "Write", "Edit"],)async def main() -> None:    prompt = "Create a sandbox, benchmark json vs orjson on a 50 MB file, report, then stop it."    async for message in query(prompt=prompt, options=options):        if isinstance(message, ResultMessage):            print(message.result)anyio.run(main)

The server's tools follow the pattern runtime_<product>_<verb>. The full list, from previews to forks, is in MCP tools.

What the agent can do in the sandbox

With the four tools, the agent runs any shell command as root through sudo. The sandbox runs Ubuntu 24.04 with Python 3.12, Node.js 24, Bun, git and gcc. Your application holds the sbx object, so it can go further between turns:

  • Share a port. sbx.previews.create(3000) gives an app the agent started a private HTTPS address (share a port).
  • Pause between conversations. sbx.pause() keeps files, memory and running processes. Compute billing stops until the next call wakes the sandbox.
  • Try two approaches. sbx.fork({ count: 2 }) makes running copies with memory included. Point a second query at each copy (snapshots and forks).
  • Run Docker. sudo enable-docker starts Docker inside the sandbox.

Keep keys and spending safe

The Anthropic key stays in your application's process, where query runs. The sandbox never receives it. For everything else:

TypeScriptimport { query } from "@anthropic-ai/claude-agent-sdk";import { Sandbox } from "withruntime";import { RUNTIME_TOOL_NAMES, runtimeMcpServer } from "withruntime/claude-agent-sdk";await using sbx = await Sandbox.create({  timeoutSeconds: 900,  onLeaseEnd: "stop",  maxTotalCostMicros: 50_000, // stop it once it has cost $0.05  network: { internet: true, allow: ["pypi.org", "*.pythonhosted.org", "registry.npmjs.org"] },});for await (const message of query({  prompt: "Profile the script in /workspace/app.py and make it faster.",  options: {    mcpServers: { runtime: runtimeMcpServer(sbx, { timeoutSeconds: 120 }) },    allowedTools: RUNTIME_TOOL_NAMES,    disallowedTools: ["Bash", "Read", "Write", "Edit"],    maxTurns: 30,    maxBudgetUsd: 2,  },})) {  if (message.type === "result") console.log(message.subtype);}
  • maxBudgetUsd and maxTurns are the SDK's own caps on model spending and loop length.
  • maxTotalCostMicros stops a sandbox once it has cost that much in total.
  • A daily spending limit on the Runtime key fails any create or wake past the limit with spending_limit_reached. Only a person can set or raise it (daily limits).
  • A read-only key suits the dashboard that watches these agents.
  • network.allow is enforced by the host, so root inside the sandbox cannot widen it (turn off sandbox internet).

The code execution tool, compared

Anthropic also offers a server-side code execution tool in the Messages API. It runs in a container that Anthropic manages. It does not run on a machine that your application holds and configures. Sizes, limits and prices of the two are compared in Claude code execution tool alternative. To run the Claude Code CLI itself in a sandbox, see Claude Code in a sandbox.

A new account gets 100 free hours of a 1 GB machine in its first 30 days. No card is needed (pricing).

Sources

Checked 25 October 2026.

Facts on this page were checked on 25 October 2026.

Related.

100 free hoursin your first 30 days.

of a 1 GB machine

  • No credit card
  • Four sandboxes at once, 2 vCPU and 4 GiB each
  • Then prepaid credit from $10, no plan fee
Start free, no card
Start free, no card