Cloudflare Sandbox

CloudflareSandbox executes commands and manages files in a remote Cloudflare Sandbox through the Sandbox Bridge HTTP API.

warning

Deploy and secure a Sandbox Bridge Worker before using this provider. The bridge can create and delete sandboxes, execute commands, and write files on behalf of its callers.

Installation

npm

npm install @mastra/cloudflare-sandbox

pnpm

pnpm add @mastra/cloudflare-sandbox

Yarn

yarn add @mastra/cloudflare-sandbox

Bun

bun add @mastra/cloudflare-sandbox

Usage

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

src/mastra/agents/dev-agent.ts

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:

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.

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

= Cloudflare Sandbox

Human-readable sandbox name.

env?:

Record<string, string>

Environment variables applied to every command.

workingDirectory?:

string

Working directory applied to every command.

commandTimeout?:

number

= 300000

Default command timeout in milliseconds.

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.