导航|地址|刷新
Sandbox

Skip to contentDocumentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/agents/llms.txt
Use this file to discover all available pages before exploring further.

Docs Directory API SDKs Changelog

Search

Log in

Agents

/

Overview

Getting started

Quick start

Add to existing project

Testing your Agents

Concepts

What are agents?

Conversation state and memory

Tools

Calling LLMs

Using Agents with Workflows

Agentic patterns

Overview

Human-in-the-loop patterns

Long-running agents

Communication channels

Chat

Chat agents

Autonomous responses

Client SDK

Voice

Email

Slack

Webhooks

Overview

Push notifications

Tools

Sandbox

MCP

Browser

AI Search

Agentic Payments

Overview

Charge for HTTP content

x402

Overview

Charge for HTTP content

Charge for MCP tools

Pay from Agents SDK

Pay from coding tools

MPP (Machine Payments Protocol)

Code Mode

Overview

Create a durable Code Mode runtime

AI SDK integration

Use Code Mode with TanStack AI

Browser-owned tools

MCP

OpenAPI

How Code Mode works

Code Mode API reference

Harnesses

Overview

Think

Overview

Getting started

Configuration

Tools

Actions

Lifecycle hooks

Client tools

Messengers

Channels

Scheduled tasks

Workflows

Sub-agent RPC and programmatic turns

Programmatic submissions

Durable recovery

Runtime

Agents API

Lifecycle

Agent class internals

Callable methods

Store and sync state

Sessions

getCurrentAgent()

Communication

Routing

WebSockets

HTTP and Server-Sent Events

Chat SDK

Protocol messages

Readonly connections

Execution

Sub-agents

Schedule tasks

Durable execution with fibers

Queue tasks

Retries

Run Workflows

Agents as tools

Agent Skills

Operations

Configuration

Cross-domain authentication

Using AI Models

Observability

Examples

Chat agent

Slack agent

Voice agent

Browser agent

Email agent

Model Context Protocol (MCP)

Overview

APIs

MCP handler APIs

McpAgent

McpClient

Protocol

Tools

Authorization

Transport

MCP governance

Guides

Build MCP client

Build a Remote MCP server

Test a Remote MCP Server

Securing MCP servers

Connect to an MCP server

Handle OAuth with MCP servers

Migrate to MCP SDK v2

Build a single-tool Code Mode MCP server

Build a search and execute MCP server

Cloudflare

MCP server portals ↗

Cloudflare's own MCP servers

Overview

Cloudflare Community MCP Server

Code Mode MCP server patterns

Platform

Limits

Agent resources

Agent setup ↗

Cloudflare Skills ↗

Code Mode MCP Server ↗

Domain-specific MCP Servers ↗MCP

Agents llms.txt ↗

Agents llms-full.txt ↗

Cloudflare Docs llms.txt ↗

Cloudflare Docs llms-full.txt ↗

Home

/Agents

/Tools

/Sandbox

Sandbox

Last updated Jun 3, 2026|Copy as Markdown|View as Markdown|Agent setup

OverviewWhen to use SandboxBasic patternConfigurationSandbox and agent stateRelated resources

Agents can use Sandbox to run code in isolated container environments. Use Sandbox when an agent needs a real filesystem, shell commands, language runtimes, package installation, or long-lived project state that should not run inside the agent's own Worker isolate.

Sandbox is built on Cloudflare Containers and exposes a TypeScript API for command execution, file operations, background processes, and service previews.

When to use Sandbox

Use Sandbox for agents that need to:

Run untrusted or model-generated code in isolation.

Execute Python, Node.js, shell commands, or package managers.

Read, write, and manage project files.

Run tests, linters, build tools, or data analysis scripts.

Maintain a workspace across multiple agent turns.

Basic pattern

Bind the Sandbox Durable Object to your Worker, then access a sandbox from your agent methods with getSandbox().

import { Agent, callable } from "agents";import { getSandbox } from "@cloudflare/sandbox";export { Sandbox } from "@cloudflare/sandbox";export class CodeAgent extends Agent { @callable() async runPython(code) { const sandbox = getSandbox(this.env.Sandbox, this.name); await sandbox.writeFile("/workspace/script.py", code); const result = await sandbox.exec("python3 /workspace/script.py"); this.setState({ lastOutput: result.stdout }); return { success: result.success, stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode, }; }}

import { Agent, callable } from "agents";import { getSandbox } from "@cloudflare/sandbox";import type { Sandbox } from "@cloudflare/sandbox";export { Sandbox } from "@cloudflare/sandbox";type Env = { Sandbox: DurableObjectNamespace<Sandbox>;};export class CodeAgent extends Agent<Env, { lastOutput?: string }> { @callable() async runPython(code: string) { const sandbox = getSandbox(this.env.Sandbox, this.name); await sandbox.writeFile("/workspace/script.py", code); const result = await sandbox.exec("python3 /workspace/script.py"); this.setState({ lastOutput: result.stdout }); return { success: result.success, stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode, }; }}

Configuration

Configure the Sandbox container, Durable Object binding, and migration in wrangler.jsonc.

{ "containers": [ { "class_name": "Sandbox", "image": "./Dockerfile", "instance_type": "lite", "max_instances": 1 } ], "durable_objects": { "bindings": [ { "name": "Sandbox", "class_name": "Sandbox" } ] }, "migrations": [ { "tag": "v1", "new_sqlite_classes": ["Sandbox"] } ]}

[[containers]]class_name = "Sandbox"image = "./Dockerfile"instance_type = "lite"max_instances = 1[[durable_objects.bindings]]name = "Sandbox"class_name = "Sandbox"[[migrations]]tag = "v1"new_sqlite_classes = [ "Sandbox" ]

Sandbox and agent state

Use agent state for user-visible progress and small metadata. Use the sandbox filesystem for workspace files, generated code, package installs, logs, and artifacts.

For long-running sandbox work, pair Sandbox with durable execution with fibers or Workflows so the agent can recover or report progress if work outlives a single request.

Related resources

Sandbox SDK

Full Sandbox documentation for commands, files, sessions, and deployment.

Execute commands

Run shell commands in a sandbox environment.

Manage files

Read, write, upload, and download sandbox files.

PreviousPush notificationsNextMCP

Was this helpful?

YesNo

Edit pageReport issue

On this page

Overview

When to use Sandbox

Basic pattern

Configuration

Sandbox and agent state

Related resources

Edit pageReport issue

Getting started
PlansContact salesPartnersFind a partnerStartupsUnder attack?Domain name search

Company
AboutCareersInvestorsPressPress kitGlobal network

Public interest
Project GalileoAthenian ProjectCloudflare for CampaignsProject FairshotImpact/ESG

Compliance
Compliance resourcesTrust HubData ProtectionResponsible AITransparency reportReport abuse

Resources
App innovation reportCloudflare RadarCase studiesStatusSupportEventsBlog

Developers
DocumentationLearning centerCommunity

Solutions
SSE and SASE platformCloudflare AI CloudAI SecurityFrontend Development PlatformMulti-Tenant Platform DevelopmentWeb Security Platform

Start BuildingLog In

© 2026 Cloudflare, Inc.

Privacy policy|Report security issues|Terms of use|Trademark
|
Your privacy choices

Docs

------
导航页打开网址