> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# Cloudflare Sandbox

`CloudflareSandbox` executes commands and manages files in a remote [Cloudflare Sandbox](https://developers.cloudflare.com/sandbox/) through the [Sandbox Bridge HTTP API](https://developers.cloudflare.com/sandbox/bridge/http-api/).

> **Warning:** Deploy and secure a [Sandbox Bridge Worker](https://developers.cloudflare.com/sandbox/bridge/) before using this provider. The bridge can create and delete sandboxes, execute commands, and write files on behalf of its callers.

## Installation

**npm**:

```bash
npm install @mastra/cloudflare-sandbox
```

**pnpm**:

```bash
pnpm add @mastra/cloudflare-sandbox
```

**Yarn**:

```bash
yarn add @mastra/cloudflare-sandbox
```

**Bun**:

```bash
bun add @mastra/cloudflare-sandbox
```

## Usage

Add `CloudflareSandbox` to a workspace and assign it to an agent:

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { CloudflareSandbox } from '@mastra/cloudflare-sandbox'

const workspace = new Workspace({
  sandbox: new CloudflareSandbox({
    baseUrl: process.env.CLOUDFLARE_SANDBOX_BRIDGE_URL!,
    apiToken: process.env.CLOUDFLARE_SANDBOX_API_KEY,
    workingDirectory: '/workspace',
    commandTimeout: 300_000,
  }),
})

export const agent = new Agent({
  id: 'dev-agent',
  name: 'Development agent',
  instructions: 'You are a helpful development assistant.',
  model: 'anthropic/claude-sonnet-4-6',
  workspace,
})
```

The provider creates a remote sandbox when the workspace starts. Pass `sandboxId` to reconnect to an existing sandbox instead.

## Execute commands

Pass command arguments, environment variables, a working directory, and streaming callbacks through `executeCommand()`. The provider sends the command as an `argv` array, so the bridge handles shell escaping:

```typescript
const result = await workspace.sandbox?.executeCommand?.('npm', ['test'], {
  cwd: '/workspace/project',
  env: {
    NODE_ENV: 'test',
  },
  onStdout: chunk => process.stdout.write(chunk),
  onStderr: chunk => process.stderr.write(chunk),
})
```

## Write files

Relative paths are resolved under `/workspace`. Absolute paths must also resolve within `/workspace`. Each file is sent as its own bridge request, and the bridge caps a single file at 32 MiB.

```typescript
await workspace.sandbox?.writeFiles?.([
  { path: 'src/index.ts', content: "console.log('hello')\n" },
  { path: '/workspace/package.json', content: JSON.stringify({ type: 'module' }) },
])
```

## Constructor parameters

**baseUrl** (`string`): URL of the deployed Cloudflare Sandbox Bridge Worker.

**apiToken** (`string`): Bearer token matching the Worker's SANDBOX\_API\_KEY secret.

**sandboxId** (`string`): Existing Cloudflare sandbox ID to reconnect to instead of creating a sandbox.

**id** (`string`): Stable Mastra identifier. Defaults to a generated UUID-based value.

**name** (`string`): Human-readable sandbox name. (Default: `Cloudflare Sandbox`)

**env** (`Record<string, string>`): Environment variables applied to every command.

**workingDirectory** (`string`): Working directory applied to every command.

**commandTimeout** (`number`): Default command timeout in milliseconds. (Default: `300000`)

**instructions** (`string | ((options) => string)`): Custom instructions returned by getInstructions().

## Lifecycle behavior

- `start()`: Reconnects to `sandboxId` or creates a remote sandbox.
- `stop()`: Detaches the Mastra lifecycle without deleting the remote sandbox because the bridge doesn't expose a suspend operation.
- `destroy()`: Deletes the remote sandbox.

## Limitations

The provider supports command execution, streamed output, and file writes. It doesn't currently expose the bridge's bucket mounts, sessions, PTY terminals, or workspace persistence routes, and it doesn't support background process management, stdin, snapshots, or port URLs.