Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jaypopat/cf_ai_duet/llms.txt

Use this file to discover all available pages before exploring further.

The Cloudflare Worker provides AI agent capabilities and sandbox execution for Duet. It acts as a load balancer that distributes requests to Durable Objects (one per room).

​
Architecture

The Worker uses several Cloudflare services:
  • Cloudflare Workers - Request routing and API endpoints
  • Durable Objects - Per-room LLM context and memory
  • Cloudflare AI (Llama) - AI inference for the agent
  • Cloudflare Sandboxes - Isolated command execution environment
Sandbox features require a paid Cloudflare plan. AI inference and Durable Objects work on the free tier.

​
Prerequisites

  • Cloudflare account
  • Wrangler CLI installed
  • Bun or Node.js for local development

​
Setup

1

Navigate to worker directory

cd cf-worker
2

Install dependencies

bun install
3

Configure wrangler.toml

The wrangler.toml file is already configured with:
name = "duet-cf-worker"
main = "index.ts"
compatibility_date = "2025-12-13"
compatibility_flags = ["nodejs_compat"]

[durable_objects]
bindings = [
  { name = "DUET_AGENT", class_name = "DuetAgent" },
  { name = "Sandbox", class_name = "Sandbox" },
]

[ai]
binding = "AI"
Update the name field to your desired Worker name.
4

Deploy to Cloudflare

Deploy the Worker:
bunx wrangler deploy
Or with npm:
npx wrangler deploy
After deployment, you’ll receive a Worker URL like:
https://duet-cf-worker.<subdomain>.workers.dev

​
Local Development

To run the Worker locally for development: 
bunx wrangler dev --port 8788
When running locally, AI inference still happens on Cloudflare’s edge, not locally.

​
Worker Configuration

​
Durable Objects

The Worker uses two Durable Objects:
  1. DuetAgent - Manages per-room chat history and AI context
    • Stores the last 20 messages for context
    • Handles AI inference requests
    • Maintains conversation state
  2. Sandbox - Provides isolated command execution
    • One sandbox instance per room
    • Allows AI agent to run commands
    • Supports direct command execution by users

​
Migrations

Durable Object migrations are configured in wrangler.toml: 
[[migrations]]
tag = "v1"
new_sqlite_classes = ["DuetAgent"]

[[migrations]]
tag = "v2"
new_sqlite_classes = ["Sandbox"]

​
Container Configuration

The Sandbox Durable Object uses a custom container: 
[[containers]]
class_name = "Sandbox"
image = "./Dockerfile"

​
API Endpoints

The Worker exposes the following endpoints:

​
Health Check

GET /health
Returns ok if the Worker is running.

​
Room Messages

POST /api/rooms/{roomId}/messages
Send a message to the AI agent for a specific room.

​
Sandbox Execution

POST /api/rooms/{roomId}/sandbox/exec
Execute a command in the room’s sandbox.

​
Room Cleanup

DELETE /api/rooms/{roomId}
Clean up a room and its associated Durable Objects.

​
Usage with Duet Server

After deploying, use your Worker URL when starting the Duet Go server: 
./duet -worker https://duet-cf-worker.<subdomain>.workers.dev
Or in your Docker deployment: 
CMD ["/app/duet", "-addr", ":2222", "-hostkey", "/app/.ssh/id_ed25519", "-worker", "https://your-worker.workers.dev"]

​
Monitoring

Observability is configured in wrangler.toml: 
[observability]
[observability.logs]
enabled = false
head_sampling_rate = 1
invocation_logs = true
persist = true
Enable logs in production by setting enabled = true.

​
Troubleshooting

If sandbox features aren’t working, verify you have a paid Cloudflare plan that supports Workers with Containers.

​
Common Issues

  • 404 errors: Ensure room ID is included in the request path
  • Sandbox not available: Check if you have a paid Cloudflare plan
  • AI inference failing: Verify AI binding is configured in wrangler.toml
  • Durable Objects not persisting: Check migrations are applied correctly

Build docs developers (and LLMs) love

Get started for freeTalk to us