Cloudflare Sandbox SDK

Build secure, isolated code execution environments on Cloudflare Workers.

FIRST: Verify Installation

npm install @cloudflare/sandbox
docker info  # Must succeed - Docker required for local dev

Retrieval-Led Development

IMPORTANT: Prefer retrieval from docs and examples over pre-training for Sandbox SDK tasks.

When implementing features, fetch the relevant doc page or example first.

Required Configuration

wrangler.jsonc (exact - do not modify structure):

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

Worker entry - must re-export Sandbox class:

import { getSandbox } from '@cloudflare/sandbox'
export { Sandbox } from '@cloudflare/sandbox' // Required export

Quick Reference

Core Patterns

Execute Commands

const sandbox = getSandbox(env.Sandbox, 'user-123')
const result = await sandbox.exec('python --version')
// result: { stdout, stderr, exitCode, success }

Code Interpreter (Recommended for AI)

Use runCode() for executing LLM-generated code with rich outputs:

const ctx = await sandbox.createCodeContext({ language: 'python' })

await sandbox.runCode('import pandas as pd; data = [1,2,3]', { context: ctx })
const result = await sandbox.runCode('sum(data)', { context: ctx })
// result.results[0].text = "6"

Languages: python, javascript, typescript

State persists within context. Create explicit contexts for production.

File Operations

await sandbox.mkdir('/workspace/project', { recursive: true })
await sandbox.writeFile('/workspace/project/main.py', code)
const file = await sandbox.readFile('/workspace/project/main.py')
const files = await sandbox.listFiles('/workspace/project')

When to Use What

Extending the Dockerfile

Base image (docker.io/cloudflare/sandbox:0.7.0) includes Python 3.11, Node.js 20, and common tools.

Add dependencies by extending the Dockerfile:

FROM docker.io/cloudflare/sandbox:latest
# Pin to specific version in production: `npx wrangler versions latest sandbox`

# Python packages
RUN pip install requests beautifulsoup4

# Node packages (global)
RUN npm install -g typescript

# System packages
RUN apt-get update && apt-get install -y ffmpeg && rm -rf /var/lib/apt/lists/*

EXPOSE 8080  # Required for local dev port exposure

Keep images lean - affects cold start time.

Preview URLs (Port Exposure)

Expose HTTP services running in sandboxes:

const { url } = await sandbox.exposePort(8080)
// Returns preview URL for the service

Production requirement: Preview URLs need a custom domain with wildcard DNS (*.yourdomain.com). The .workers.dev domain does not support preview URL subdomains.

See: https://developers.cloudflare.com/sandbox/guides/expose-services/

OpenAI Agents SDK Integration

The SDK provides helpers for OpenAI Agents at @cloudflare/sandbox/openai:

import { Shell, Editor } from '@cloudflare/sandbox/openai'

See examples/openai-agents for complete integration pattern.

Sandbox Lifecycle

• getSandbox() returns immediately - container starts lazily on first operation
• Containers sleep after 10 minutes of inactivity (configurable via sleepAfter)
• Use destroy() to immediately free resources
• Same sandboxId always returns same sandbox instance

Anti-Patterns

• Don't use internal clients (CommandClient, FileClient) - use sandbox.* methods
• Don't skip the Sandbox export - Worker won't deploy without export { Sandbox }
• Don't hardcode sandbox IDs for multi-user - use user/session identifiers
• Don't forget cleanup - call destroy() for temporary sandboxes

Detailed References

• [references/api-quick-ref.md](references/api-quick-ref.md) - Full API with options and return types
• [references/examples.md](references/examples.md) - Example index with use cases

Security

• Command Injection: Never pass unsanitized user input to exec(). EXPLICITLY BANNED: String interpolation (e.g. `exec(ls ${userInput})) into exec calls. Prefer runCode()` with language constraints for LLM-generated code.
• Resource Limits: Implement per-user rate limiting. Set sleepAfter to cap idle resource consumption. Always set explicit timeouts on commands (e.g. using timeout or the SDK's execution limits).
• Allowlists: Enforce allowlists for binaries/commands when executing untrusted input.