Sandbox

Purpose and Scope

A sandbox is the execution environment in which a Managed Agent performs work that involves files, shell commands, project inspection, and tool calls. In the product docs, a cloud sandbox is an isolated Linux container on Anthropic-managed infrastructure, while a self-hosted sandbox is supplied by your own worker infrastructure. In the TypeScript SDK, sandbox behavior is not represented as a single top-level Sandbox class. Instead, you configure agents and their toolsets through the beta Managed Agents resources, then interact with the resulting runtime through sessions, events, files, and tools.

Sources: src/resources/beta/agents/index.ts, src/resources/beta/agents/agents.ts

For developers, the important mental model is that the sandbox is part of the agent framework rather than part of the local Node.js process. Cloud sandboxes come with common programming languages, database clients, and command-line utilities available to the agent without an installation phase. Local SDK helper tools, by contrast, run in your application process and are invoked through the SDK tool runner. This distinction matters for security, deployment, and debugging: server-side sandbox tools execute where the Managed Agent runs, while client-runnable tools execute where your SDK code is running.

Sources: src/lib/tools/BetaRunnableTool.ts, src/lib/tools/BetaToolRunner.ts

Relevant Source Files

• src/resources/beta/agents/index.ts - Re-exports the generated Managed Agents resource, agent configuration types, toolset types, MCP types, custom tool types, and the nested versions resource used when configuring agent behavior.
• src/resources/beta/agents.ts - Provides the beta agents barrel export so client.beta.agents resolves to the generated agents module.
• src/resources/beta/agents/agents.ts - Implements the Agents API resource with create, retrieve, update, list, and archive methods, including the Managed Agents beta header on each request.
• src/resources/beta/agents/versions.ts - Implements client.beta.agents.versions.list, using the same Managed Agents beta header and cursor pagination contract as the agents list surface.
• src/lib/tools/BetaRunnableTool.ts - Defines the common tool abstraction used by SDK tool runners, including the difference between client-runnable tools and server-side tools such as code execution, web search, and MCP toolsets.
• src/lib/tools/BetaToolRunner.ts - Implements the beta tool-runner loop for Messages, including async iteration, streaming support, helper headers, cloned message state, and tool execution coordination.

Core Primitives

The SDK exposes Managed Agent setup through generated beta resources. The root src/resources/beta/agents.ts file re-exports ./agents/index, and that index re-exports the Agents class plus many public types that describe agent configuration. The exported names include BetaManagedAgentsAgent, BetaManagedAgentsAgentToolConfig, BetaManagedAgentsAgentToolset20260401, tool input types for bash, edit, glob, grep, read, and write, MCP server definitions, custom tool definitions, model configuration, and paginated agent list types. Those names are the source-level vocabulary you will see when building TypeScript integrations around sandbox-capable agents.

Sources: src/resources/beta/agents.ts, src/resources/beta/agents/index.ts

Agent resources are the configuration side of the sandbox story. Agents.create posts to /v1/agents?beta=true, accepts AgentCreateParams, and returns a BetaManagedAgentsAgent. retrieve, update, list, and archive use the same generated resource class, with path interpolation for agent-specific operations and cursor pagination for listing. Every method shown in the generated resource adds the anthropic-beta header with managed-agents-2026-04-01, while preserving any additional beta values supplied in params.betas. This matches the official docs guidance that Managed Agents requests require the Managed Agents beta header, and it means normal SDK users do not need to manually attach that header for these resource methods.

Sources: src/resources/beta/agents/agents.ts

Versions are a smaller but important primitive when treating the sandbox as part of agent configuration. client.beta.agents.versions.list(agentID) calls /v1/agents/${agentID}/versions?beta=true and returns a cursor-paginated list of BetaManagedAgentsAgent records. Use this resource when you need to inspect the historical configurations available for an agent before updating a deployment or comparing toolset changes. It follows the same betas parameter pattern as the main agent resource, so custom beta values and the required Managed Agents beta value are combined in the outgoing header.

Sources: src/resources/beta/agents/versions.ts

System-to-Code Mapping

The cloud sandbox reference is operational documentation: it tells you what a cloud environment contains, such as Python, Node.js, Go, Rust, Java, Ruby, PHP, C/C++, SQLite, database clients, Git, curl, jq, archive tools, and development utilities. The SDK source maps that product concept to TypeScript surfaces for creating agents and declaring tool access. The exported BetaManagedAgentsAgentToolset20260401 family and its bash, edit, glob, grep, read, and write input types are the strongest source signal that sandbox-style operations are configured as part of an agent toolset rather than as ad hoc SDK methods.

Sources: src/resources/beta/agents/index.ts

The tool helper files define the boundary between local helper execution and managed sandbox execution. BetaClientRunnableToolType is documented as the set of tool types that can be implemented on the client, and the comment explicitly excludes server-side tools like code execution, web search, and MCP toolsets. A BetaRunnableTool adds run, parse, and optional close hooks for your application to execute a tool call locally. That is useful for custom business logic, but it is not the same as asking a Managed Agent to operate inside its cloud sandbox with its configured toolset and mounted resources.

Sources: src/lib/tools/BetaRunnableTool.ts

MCP is another place where the distinction matters. The agent index exports MCP-related types such as BetaManagedAgentsMCPServerURLDefinition, BetaManagedAgentsMCPToolConfig, BetaManagedAgentsMCPToolset, and related params. The tool helper uses toolName to resolve registry keys, choosing mcp_server_name for MCP toolsets and name for other tools. That tells SDK users two things: MCP tools are first-class in Managed Agent configuration, and the SDK intentionally shares name-resolution behavior across tool-runner surfaces so local and session-oriented workflows address tools consistently.

Sources: src/resources/beta/agents/index.ts, src/lib/tools/BetaRunnableTool.ts

Execution Flow

A typical sandbox-oriented flow starts by creating or updating an agent with the model and tool configuration you want the Managed Agent to use. In TypeScript, the generated resource call looks like the normal SDK style: construct a client, call client.beta.agents.create, and pass an AgentCreateParams body. The generated method moves betas out of the body, sends the remaining fields as JSON, and adds the required header. After creation, use retrieve to inspect the agent, update to change the active version or configuration, list for inventory, and archive when an agent should no longer be used.

Sources: src/resources/beta/agents/agents.ts

const agent = await client.beta.agents.create({
  model: 'claude-sonnet-4-6',
  name: 'Sandbox-enabled agent',
});
 
for await (const version of client.beta.agents.versions.list(agent.id)) {
  console.log(version.id);
}

When the agent runs, work that depends on the managed environment should be modeled as agent tool access and session resources, not as hidden side effects in your application. Official Managed Agents file guidance describes uploading files through the Files API and mounting them into a session sandbox as resources. That gives the agent deterministic input paths inside its environment. If you also provide local tools through the SDK helper layer, implement them as BetaRunnableTool objects and expect the runner to parse tool input, invoke run, format errors consistently, and call close for tools that hold process-level resources when session tool iteration ends.

Sources: src/lib/tools/BetaRunnableTool.ts, src/lib/tools/BetaToolRunner.ts

API Reference Snapshot

The reference detail to remember is the beta header behavior. The generated agents and versions resources accept an optional betas array, then build an anthropic-beta header that appends managed-agents-2026-04-01. That design keeps the Managed Agents requirement close to the resource implementation and reduces per-call boilerplate in application code. If you pass custom request headers, they are merged through buildHeaders, so request-level customization remains available without losing the SDK-managed beta value.

Sources: src/resources/beta/agents/agents.ts, src/resources/beta/agents/versions.ts

Implementation Details and Next Steps

BetaToolRunner is useful context even when your main focus is Managed Agents sandboxes, because it shows how the SDK treats tool execution as an iterative conversation loop. The class is an async iterable that yields BetaMessage or BetaMessageStream objects depending on streaming configuration. It clones message arrays to avoid mutating caller-owned state, tracks whether params have changed between API calls, caches the last assistant message and tool response, and attaches Stainless helper headers. It also warns that compactionControl is deprecated in favor of server-side compaction through edits: [{ type: 'compact_20260112' }].

Sources: src/lib/tools/BetaToolRunner.ts

For next steps, read the Managed Agents setup and sessions pages to see where configured agents are started, how files are attached to sessions, and how event streams report agent work. Then use the beta agents reference when you need exact method names, return types, or pagination behavior. If you are deciding whether code should run locally or in a managed sandbox, start from the BetaRunnableTool distinction: client-runnable tools belong in your TypeScript process, while server-side tools, MCP toolsets, and cloud sandbox operations belong in the Managed Agent configuration and runtime.