---
title: Sandbox
description: Give agents isolated Linux environments for running code, managing files, and executing commands.
image: https://edgetunnel-b2h.pages.dev/dev-products-preview.png
---

> Documentation Index  
> Fetch the complete documentation index at: https://edgetunnel-b2h.pages.dev/agents/llms.txt  
> Use this file to discover all available pages before exploring further. 

[Skip to content](#%5Ftop) 

# Sandbox

Agents can use [Sandbox](https://edgetunnel-b2h.pages.dev/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](https://edgetunnel-b2h.pages.dev/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()`.

* [  JavaScript ](#tab-panel-7099)
* [  TypeScript ](#tab-panel-7100)

**JavaScript**

```js
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,
    };
  }
}
```

**TypeScript**

```ts
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`.

* [  wrangler.jsonc ](#tab-panel-7097)
* [  wrangler.toml ](#tab-panel-7098)

**JSONC**

```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"]
    }
  ]
}
```

**TOML**

```toml
[[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](https://edgetunnel-b2h.pages.dev/agents/runtime/execution/durable-execution/) or [Workflows](https://edgetunnel-b2h.pages.dev/agents/runtime/execution/run-workflows/) so the agent can recover or report progress if work outlives a single request.

## Related resources

[ Sandbox SDK ](https://edgetunnel-b2h.pages.dev/sandbox/) Full Sandbox documentation for commands, files, sessions, and deployment. 

[ Execute commands ](https://edgetunnel-b2h.pages.dev/sandbox/guides/execute-commands/) Run shell commands in a sandbox environment. 

[ Manage files ](https://edgetunnel-b2h.pages.dev/sandbox/guides/manage-files/) Read, write, upload, and download sandbox files.

```json
{"@context":"https://schema.org","@type":"TechArticle","@id":"https://edgetunnel-b2h.pages.dev/agents/tools/sandbox/#page","headline":"Sandbox · Cloudflare Agents docs","description":"Give agents isolated Linux environments for running code, managing files, and executing commands.","url":"https://edgetunnel-b2h.pages.dev/agents/tools/sandbox/","inLanguage":"en","image":"https://edgetunnel-b2h.pages.dev/dev-products-preview.png","dateModified":"2026-06-03","publisher":{"@type":"Organization","name":"Cloudflare","url":"https://www.cloudflare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://edgetunnel-b2h.pages.dev/#website","name":"Cloudflare Docs","url":"https://edgetunnel-b2h.pages.dev/"}}
{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/agents/","name":"Agents"}},{"@type":"ListItem","position":3,"item":{"@id":"/agents/tools/","name":"Tools"}},{"@type":"ListItem","position":4,"item":{"@id":"/agents/tools/sandbox/","name":"Sandbox"}}]}
```