Duraclaw: Claude Code Session Orchestrator

1. What Duraclaw Is

Duraclaw is a Claude Code session orchestrator. It provides a browser-based interface for launching, monitoring, and interacting with Claude Code sessions that run on a remote VPS. The AI does the actual work on a server. You watch and interact from anywhere.

Think of it as a remote control panel for Claude Code. Where a local terminal session ties you to one machine, Duraclaw decouples the compute from the interface. Launch a session from your phone. Resume it from your laptop. The session state survives network drops, browser closes, and even Cloudflare Worker evictions.

2. Architecture Overview

The system has three layers, connected by WebSockets and proxied through Cloudflare's network:

Browser (any device)
    ↓ HTTPS / WebSocket
Cloudflare Worker (orchestrator)
    — TanStack Start SPA
    — Durable Objects (1 per session)
    — Better Auth + D1 for user sessions
    ↓ WebSocket over CF Tunnel
VPS Executor (cc-gateway, Bun)
    — @anthropic-ai/claude-agent-sdk
    — Runs against /data/projects/baseplane* worktrees

Each layer has a clear responsibility:

• Browser layer — TanStack Start SPA with the useAgent() React hook from the Cloudflare Agents SDK. Renders the session UI, sends user messages, receives streaming responses. No session state lives here.
• Worker layer — Cloudflare Worker hosting the SPA, API routes, and Durable Object bindings. Authentication via Better Auth with D1 storage. Each session gets its own Durable Object instance.
• VPS layer — A Bun WebSocket server (cc-gateway) running the Anthropic Claude Agent SDK. Bound to 127.0.0.1 only, exposed to the internet exclusively through a Cloudflare Tunnel. Executes Claude Code against real project worktrees.

3. SessionDO: The Per-Session State Machine

The SessionDO is the architectural core of Duraclaw. It is a Cloudflare Durable Object that owns the complete lifecycle of a single Claude Code session. Every session gets exactly one DO instance, and that DO is the single source of truth for that session's state.

What SessionDO Owns

• Session state — current phase (initializing, active, paused, terminated), configuration, and metadata
• Message history — persisted in the DO's built-in SQLite storage, not in an external database
• WebSocket relay — holds connections to both the browser client and the VPS gateway, relaying messages bidirectionally
• Scheduled reconnects — when a Worker eviction occurs, the DO uses the Alarms API to schedule a reconnect attempt to the VPS gateway

DO Migration Pattern

As SessionDO evolves, its SQLite schema needs migrations. The do-migrations.ts module implements a versioned migration runner that executes on DO wake-up. Each migration is idempotent and runs inside a transaction. This pattern is reusable boilerplate for any Durable Object that uses SQLite storage.

// do-migrations.ts pattern (simplified)
const migrations = [
  { version: 1, sql: `CREATE TABLE IF NOT EXISTS messages (...)` },
  { version: 2, sql: `ALTER TABLE messages ADD COLUMN tool_results TEXT` },
];

export function runMigrations(sql: SqlStorage) {
  const current = sql.exec("PRAGMA user_version").one()?.user_version ?? 0;
  for (const m of migrations) {
    if (m.version > current) {
      sql.exec(m.sql);
      sql.exec(`PRAGMA user_version = ${m.version}`);
    }
  }
}

4. cc-gateway: The VPS Executor

The cc-gateway package is a Bun-based WebSocket server that runs on the VPS. It is the bridge between the Cloudflare orchestrator and the actual Claude Code process. Its responsibilities are narrow by design:

• Accept WebSocket connections from SessionDOs (via CF Tunnel)
• Spawn and manage Claude Agent SDK sessions
• Execute against real project worktrees at /data/projects/baseplane*
• Stream tool calls, results, and completions back to the DO

Security Model

The gateway binds to 127.0.0.1 only. It has zero public-facing ports. All external access routes through a Cloudflare Tunnel, which terminates TLS and provides the wss:// endpoint configured as CC_GATEWAY_URL. This is a clean separation of concerns: the gateway handles compute, Cloudflare handles networking and security.

Protocol Contract

All messages between the CF Worker and the VPS gateway are typed via the shared-types package. The protocol defines two message families:

// shared-types/protocol.ts
type GatewayCommand =
  | { type: "session.create"; config: SessionConfig }
  | { type: "session.message"; content: string }
  | { type: "session.tool.approve"; toolCallId: string }
  | { type: "session.tool.deny"; toolCallId: string; reason: string }
  | { type: "session.terminate" };

type GatewayEvent =
  | { type: "session.created"; sessionId: string }
  | { type: "session.message.delta"; content: string }
  | { type: "session.tool.request"; toolCall: ToolCall }
  | { type: "session.tool.result"; toolCallId: string; result: unknown }
  | { type: "session.complete"; summary: string }
  | { type: "session.error"; error: string };

WS-based ChatTransport

The ws-chat-transport.ts module implements a custom ChatTransport for Vercel's AI SDK. Instead of HTTP streaming (the default), it sends messages over WebSocket. This is a reusable pattern for any real-time AI chat application running on Cloudflare Workers, where HTTP streaming has limitations around connection lifetimes and buffering.

5. Monorepo Structure

Duraclaw uses a standard pnpm + Turborepo monorepo layout. Four packages, each with a clear boundary:

duraclaw/
  apps/
    orchestrator/       → CF Worker (the UI + API)
      — TanStack Start SPA
      — Durable Object definitions
      — Better Auth configuration
      — D1 bindings

  packages/
    cc-gateway/         → VPS executor (Bun WebSocket server)
      — Claude Agent SDK integration
      — Worktree management
      — Tool approval/denial handlers

    kata/               → Workflow CLI
      — Phased implementation management
      — Verification gates
      — Subagent orchestration

    shared-types/       → Protocol types
      — GatewayCommand / GatewayEvent
      — Session configuration types
      — Shared enums and constants

The monorepo enforces a unidirectional dependency graph: orchestrator and cc-gateway both depend on shared-types, but never on each other. kata is a development-time dependency only — it is not part of the production runtime.

6. Kata: Verification-Driven Development

Kata is the workflow CLI used by the developers building Duraclaw. It is not part of Duraclaw's runtime — it lives in packages/kata/ and manages the development process itself.

What Kata Does

• Phased implementation — breaks work into planning, implementation, and verification phases
• Completion gates — each phase must pass gates: typecheck passes, tests pass, committed, pushed
• Subagent orchestration — spawns specialized agents (impl-agent, test-agent, review-agent) for each phase
• Verification evidence — every roadmap subphase requires a verification delta before it's marked done, stored in .kata/verification-evidence/

Kata Status in the Dashboard

The kata status endpoint (/projects/:name/kata-status) surfaces the current kata session state to the orchestrator UI. From the Duraclaw dashboard, you can see what implementation phase a worktree is on, which gates have passed, and what verification evidence exists. This closes the loop between the development workflow and the session management system.

7. Extractable Infrastructure Patterns

Duraclaw contains several architectural patterns worth extracting and reusing in other systems.

Pattern 1: Durable Objects as Per-Entity State Machines

SessionDO demonstrates a clean pattern for using Durable Objects as per-entity state machines. One DO instance owns one session's full lifecycle: state transitions, SQLite message history, WebSocket relay to both client and server, and scheduled reconnects via the Alarms API. The DO migration pattern (do-migrations.ts) is reusable boilerplate for any DO that evolves its schema over time.

Pattern 2: Cloudflare Agents SDK

Duraclaw uses the newer Agent base class from the agents package rather than raw Durable Objects. This gives the client side a useAgent() React hook that handles WebSocket connection management, reconnection, and typed message passing. This is the emerging pattern for stateful real-time applications on Cloudflare.

Pattern 3: WS-based ChatTransport for AI SDK

The ws-chat-transport.ts module is a custom ChatTransport implementation for Vercel's AI SDK that sends over WebSocket instead of HTTP streaming. Reusable in any real-time AI chat application where HTTP streaming is insufficient — particularly on Cloudflare Workers where connection lifetimes and buffering behavior differ from traditional servers.

Pattern 4: VPS-to-CF Tunnel

The gateway binds to 127.0.0.1 only, with all external access routed through a Cloudflare Tunnel. The CC_GATEWAY_URL is a wss:// tunnel hostname. This pattern cleanly separates compute (VPS) from networking (Cloudflare) and is applicable to any scenario where you need to expose a private service through Cloudflare's network without opening ports.

Pattern 5: Permission Gating via Hooks

The sessions.ts module shows how to intercept PreToolUse events to gate every tool call behind an approval prompt. This is relevant for any agent deployment where you want human-in-the-loop control. The user sees the tool call in the browser, approves or denies it, and the decision flows back through the DO to the VPS executor.

// Permission gating flow
Browser → SessionDO → cc-gateway → Claude Agent SDK
                                          ↓
                                    PreToolUse event
                                          ↓
                          cc-gateway → SessionDO → Browser
                                    (tool approval prompt)
                                          ↓
Browser → SessionDO → cc-gateway → approve/deny

Pattern 6: Kata Verification-Driven Development

The AGENTS.md verification policy is a methodology pattern, not a code pattern. It mandates that every implementation phase produces verification evidence against the real running system — HTTP requests, browser automation, log inspection — not mocks or unit tests alone. This is directly applicable to any team running AI agents against real infrastructure.

8. Implications for Organized AI

Duraclaw is architecturally what OpenClaw would become if you added a full browser UI and Durable Object session management on top. The cc-gateway is structurally similar to the OpenClaw gateway. The key learnable delta is the combination of three patterns:

• DO-per-session state management — each AI session as an independent state machine with its own persistence
• Agents SDK integration — typed real-time communication between browser and DO via useAgent()
• CF Tunnel pattern — private VPS compute exposed through Cloudflare's network without port exposure

These three patterns together solve the core problem of managing long-running AI sessions from a web UI: the session outlives any single connection, the state is durable across evictions, and the compute runs securely on private infrastructure.