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, so its work runs in a microVM.

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 hands the agent four tools bound to one Firecracker microVM with its own Linux kernel, and disallowedTools removes the local ones. The sandbox waits on the model at $0.03125 an hour for 2 vCPUs and 4 GiB. On 25 September 2026 the current releases were @anthropic-ai/claude-agent-sdk 0.3.282 on npm and claude-agent-sdk 0.2.159 on PyPI.

Install

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

zod is needed beside the SDK. The login prints a link to approve in your browser; on a server, RUNTIME_API_KEY replaces it. 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 that lives 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, so allowedTools approves them without a permission prompt.
  • disallowedTools takes the local Bash and file tools away, so nothing the model asks for touches your server's disk.
  • await using stops the sandbox when solve returns, even after an error.

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

Where the SDK's tools run by default

Anthropic's secure deployment guide, read on 25 September 2026, says Claude Code and the Agent SDK "can execute code, access files, and interact with external services on your behalf", and 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, a proxy outside the agent's boundary that adds credentials to outgoing requests, is how Runtime secrets work: 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 takes 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 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, on 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, and compute billing stops until the next call wakes it.
  • 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",  maxCostMicros: 50_000, // refuse a first lease over $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.
  • maxCostMicros refuses a sandbox whose first lease would cost more.
  • A daily spending limit on the Runtime key fails any create or wake past it 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 Anthropic manages, not a machine 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.

New accounts get 50 free sandbox hours, no card (pricing).

Sources

Checked 25 September 2026.

Facts on this page were checked on 25 September 2026.

Claim 50 hours free