# 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

```bash no-run
npm install withruntime @anthropic-ai/claude-agent-sdk zod
npx 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](/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` 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](/docs/security#secrets-sandboxes-never-see) 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:

```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 `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`,
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](/docs/javascript#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](/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",
  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](/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 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](/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).

New accounts get 50 free sandbox hours, no card ([pricing](/docs/pricing)).

## Sources

Checked 25 September 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.282, with `maxTurns` and `maxBudgetUsd` in its `Options` type
- [claude-agent-sdk on PyPI](https://pypi.org/project/claude-agent-sdk/):
  version 0.2.159, with `ClaudeAgentOptions` taking `mcp_servers`,
  `allowed_tools` and `disallowed_tools`

Facts on this page were checked on 25 September 2026.