Sandboxed Browser-Agent Runtime on Cloudflare Workers

Overview

A Cloudflare Worker that runs the Claude Agent SDK inside an isolated Cloudflare Sandbox container to process browser-automation agent requests. It keeps the model provider API key server-side as a secret, exposes a clean request/streaming API, and maintains conversation context across turns.

Why It Exists

Running an LLM agent directly in the browser leaks API keys and offers no isolation for the tool-calling loop. This project validates a pattern where the agent executes in a hardened, ephemeral sandbox at the edge, with the browser only sending intent (“fill the name field”, “click submit”) and receiving results.

What We Built

• A Worker entrypoint (src/index.ts) that routes standard and /stream requests and binds a Sandbox Durable Object class.
• An agent server (agent-server.ts / agent/server.ts) that drives the Claude Agent SDK, registers browser tools as an MCP server, and resumes sessions for multi-turn context.
• A custom Dockerfile built on cloudflare/sandbox:0.6.3, installing the Claude Code CLI and SDK under a non-root agent user, started via sandbox.startProcess().
• Streaming responses via Server-Sent Events, including a “voice” mode flag.
• wrangler.jsonc wiring containers, Durable Object bindings, SQLite migrations, observability, and custom routes on a dedicated zone.

Technologies & Approach

TypeScript on Cloudflare Workers, with the @cloudflare/sandbox package providing container instances backed by Durable Objects. The Claude Agent SDK handles the agent loop and session resume; browser tools are surfaced through an MCP server for clean registration. Bun is used inside the container image; secrets hold the model API key.

Outcome / Impact

Proved a viable architecture for safe, server-side execution of a browser agent at the edge: isolated container runtime, no key exposure to clients, and real-time streamed updates with preserved session state.

Capabilities Demonstrated

• Running the Claude Agent SDK in an isolated edge sandbox
• Defining agent tools via the Model Context Protocol
• Streaming agent output over SSE with multi-turn session resume
• Edge container orchestration with Cloudflare Sandbox, Durable Objects, and Wrangler
• Secrets-based API key protection