basic-worker

Basic Sandbox Worker Example

This example demonstrates how to use @dotdo/sandbox to run coding agents (Claude Code) in a Cloudflare Worker.

Features

• Create and manage Claude Code sandboxes in containers
• Run prompts for autonomous coding tasks
• Execute shell commands in the sandbox
• Handle responses with typed results

Setup

1. Install dependencies:

npm install @dotdo/sandbox @cloudflare/sandbox

2. Configure your environment variables:

# Create .dev.vars for local development
echo "ANTHROPIC_API_KEY=your-api-key" > .dev.vars

# Or set via wrangler secrets for production
wrangler secret put ANTHROPIC_API_KEY

3. Run locally:

wrangler dev

API Endpoints

GET /

Health check and welcome message.

POST /run

Run Claude Code with a prompt.

Request:

{
  "prompt": "Create a REST API with Express"
}

Response:

{
  "success": true,
  "output": {
    "result": "I've created a REST API...",
    "is_error": false,
    "session_id": "abc123"
  },
  "stdout": "...",
  "duration": 15234
}

POST /exec

Execute a shell command directly in the sandbox.

Request:

{
  "command": "ls -la /workspace"
}

Response:

{
  "success": true,
  "stdout": "total 0\ndrwxr-xr-x...",
  "stderr": "",
  "exitCode": 0
}

Code Walkthrough

Creating a Sandbox

import { getSandbox } from '@cloudflare/sandbox'
import { createClaudeCodeSandbox } from '@dotdo/sandbox/agents/claude-code'

// Get sandbox from container binding with session ID
const sandbox = getSandbox(env.CLAUDE_CODE_SANDBOX, sessionId)

// Create Claude Code sandbox
const claude = createClaudeCodeSandbox({
  sandbox,
  apiKey: env.ANTHROPIC_API_KEY,
  permissionMode: 'acceptEdits',
})

Running a Prompt

// Initialize (starts container)
await claude.init()

// Run prompt
const result = await claude.run('Create a hello world function', {
  timeout: 300000,
  model: 'claude-sonnet-4-20250514',
})

// Clean up
await claude.close()

Permission Modes

• default - Prompts for all permissions
• acceptEdits - Auto-accepts file edits (recommended for autonomous tasks)
• bypassPermissions - Bypasses all permission prompts (use with caution)

Deployment

wrangler deploy

Make sure your Cloudflare account has Container support enabled.