Claude Agent SDK - Superserve

The Claude Agent SDK is Anthropic’s framework for building agents with tool-use loops. Expose sandbox.commands.run as an in-process MCP tool so every command the agent generates runs in an isolated VM instead of on your machine.

Setup

npm install @superserve/sdk @anthropic-ai/claude-agent-sdk zod
npm pkg set type=module  # the example uses top-level await
export SUPERSERVE_API_KEY=ss_live_...
export ANTHROPIC_API_KEY=sk-ant-...

pip install superserve claude-agent-sdk
export SUPERSERVE_API_KEY=ss_live_...
export ANTHROPIC_API_KEY=sk-ant-...

The agent loop runs on your machine, so the Claude Agent SDK reads ANTHROPIC_API_KEY from your local environment. Only the commands that the agent runs go to the sandbox.

Wire the sandbox into the agent

The highlighted block defines a bash tool backed by the sandbox. Everything else is standard Claude Agent SDK usage.

import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk"
import { Sandbox } from "@superserve/sdk"
import { z } from "zod"

const sandbox = await Sandbox.create({ name: "agent-runtime" })

const bash = tool(
  "bash",
  "Run a shell command in the sandbox.",
  { command: z.string() },
  async ({ command }) => {
    const result = await sandbox.commands.run(command, { timeoutMs: 60_000 })
    return {
      content: [
        { type: "text", text: `${result.stdout}\n${result.stderr}` },
      ],
    }
  },
)

const superserve = createSdkMcpServer({
  name: "superserve",
  version: "1.0.0",
  tools: [bash],
})

try {
  for await (const message of query({
    prompt: "List the files in /tmp and tell me how many there are.",
    options: {
      tools: [], // disable built-in tools so commands run only in the sandbox
      mcpServers: { superserve },
      allowedTools: ["mcp__superserve__bash"],
    },
  })) {
    if (message.type === "result" && message.subtype === "success") {
      console.log(message.result)
    }
  }
} finally {
  await sandbox.kill() // delete the sandbox even if the agent run fails
}

import anyio
from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient, create_sdk_mcp_server, tool
from superserve import AsyncSandbox

sandbox: AsyncSandbox | None = None

@tool("bash", "Run a shell command in the sandbox.", {"command": str})
async def bash(args):
    result = await sandbox.commands.run(args["command"], timeout_seconds=60)
    return {
        "content": [
            {"type": "text", "text": f"{result.stdout}\n{result.stderr}"},
        ],
    }

superserve = create_sdk_mcp_server(name="superserve", version="1.0.0", tools=[bash])

options = ClaudeAgentOptions(
    tools=[],  # disable built-in tools so commands run only in the sandbox
    mcp_servers={"superserve": superserve},
    allowed_tools=["mcp__superserve__bash"],
)

async def main():
    global sandbox
    sandbox = await AsyncSandbox.create(name="agent-runtime")
    try:
        async with ClaudeSDKClient(options=options) as client:
            await client.query("List the files in /tmp and tell me how many there are.")
            async for msg in client.receive_response():
                print(msg)
    finally:
        await sandbox.kill()  # delete the sandbox even if the agent run fails

anyio.run(main)

allowedTools only skips the permission prompt; it does not remove Claude Code’s built-in Bash, Read, and Edit tools. Without tools: [], the agent can run commands on your machine instead of in the sandbox. Add equivalent tools for file reads/writes the same way; see Run commands and Read & write files.

⌘I