# 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.

**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

```bash no-run
npm install withruntime @anthropic-ai/claude-agent-sdk zod
npx 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](/docs/frameworks#what-was-verified)).

## Run a query in a sandbox

```ts check
import { 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](/docs/security#secrets-sandboxes-never-see) 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:

```python check
import anyio
from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query

options = 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](/docs/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](/docs/javascript#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](/docs/javascript#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:

```ts check
import { 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](/docs/security#read-only-keys-and-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](/how-to/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](/compare/claude-code-execution-tool-alternative).
To run the Claude Code CLI itself in a sandbox, see
[Claude Code in a sandbox](/integrations/claude-code).

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

## Sources

Checked 25 October 2026.

- [Securely deploying AI agents](https://code.claude.com/docs/en/agent-sdk/secure-deployment):
  the isolation technologies table, sandbox-runtime's shared kernel, the gVisor
  overheads and the credential proxy pattern
- [@anthropic-ai/claude-agent-sdk on npm](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk):
  version 0.3.310, with `maxTurns` and `maxBudgetUsd` in its `Options` type
- [claude-agent-sdk on PyPI](https://pypi.org/project/claude-agent-sdk/):
  version 0.2.174, with `ClaudeAgentOptions` taking `mcp_servers`,
  `allowed_tools` and `disallowed_tools`

Facts on this page were checked on 25 October 2026.