Tools

By default, the agent has access to bash, file read/write, and Python — the same tools available in Claude Code. You can restrict these and add custom tools via MCP servers.

Default Tools

The agent runs with all Claude Code tools enabled. To restrict which tools the agent can use, pass allowedTools:

const session = await sandbox.agent.start({
  prompt: "Analyze the CSV files in /data",
  allowedTools: ["Read", "Bash"],
});

session = await sandbox.agent.start(
    prompt="Analyze the CSV files in /data",
    allowed_tools=["Read", "Bash"],
)

MCP Servers

Model Context Protocol servers give the agent access to custom tools. MCP servers run inside the sandbox — the agent discovers available tools via the protocol. Pass MCP server configuration when starting the agent:

const session = await sandbox.agent.start({
  prompt: "Query the users table and summarize the results",
  mcpServers: {
    sqlite: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-sqlite", "/data/app.db"],
    },
  },
});

session = await sandbox.agent.start(
    prompt="Query the users table and summarize the results",
    mcp_servers={
        "sqlite": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-sqlite", "/data/app.db"],
        },
    },
)

McpServerConfig

Field	Type	Required	Description
`command`	string	Yes	Command to start the MCP server
`args`	string[]	No	Command arguments
`env`	object	No	Environment variables for the server process

Example: Custom API Tool

const session = await sandbox.agent.start({
  prompt: "Fetch the latest deployment status",
  mcpServers: {
    deploy: {
      command: "node",
      args: ["/tools/deploy-server.js"],
      env: { DEPLOY_API_KEY: process.env.DEPLOY_API_KEY },
    },
  },
});

System Prompt

Steer agent behavior with a custom system prompt:

const session = await sandbox.agent.start({
  prompt: "Review the codebase for security issues",
  systemPrompt: "You are a security auditor. Focus on OWASP Top 10 vulnerabilities. Output findings as a markdown checklist.",
});

session = await sandbox.agent.start(
    prompt="Review the codebase for security issues",
    system_prompt="You are a security auditor. Focus on OWASP Top 10 vulnerabilities. Output findings as a markdown checklist.",
)

Permission Mode

Controls how the agent handles tool permissions:

const session = await sandbox.agent.start({
  prompt: "Set up the project",
  permissionMode: "bypassPermissions", // default — agent runs freely
});

session = await sandbox.agent.start(
    prompt="Set up the project",
    permission_mode="bypassPermissions",
)

The default is bypassPermissions — the agent can use any available tool without confirmation. This is safe because the agent runs inside an isolated sandbox VM.

Max Turns

Limit how many think → act → observe iterations the agent can perform:

const session = await sandbox.agent.start({
  prompt: "Fix the failing test",
  maxTurns: 10, // default: 50
});

session = await sandbox.agent.start(
    prompt="Fix the failing test",
    max_turns=10,
)

Lower maxTurns to prevent runaway agents on simple tasks. The default is 50.

Back to Agents overview. See also: Events · Multi-turn.

Getting Started

Sandboxes

Reserved Capacity

Agent SDK

Hosted Agents

CLI

Guides

TypeScript SDK

Python SDK

CLI Reference

API Reference

Resources

Default Tools

MCP Servers

McpServerConfig

Example: Custom API Tool

System Prompt

Permission Mode

Max Turns

​Default Tools

​MCP Servers

​McpServerConfig

​Example: Custom API Tool

​System Prompt

​Permission Mode

​Max Turns

Default Tools

MCP Servers

McpServerConfig

Example: Custom API Tool

System Prompt

Permission Mode

Max Turns