Skip to content

SYSTEM Cited by 11 sources

Cloudflare Durable Objects

Durable Objects (DO) is Cloudflare's globally-addressable, single-writer, stateful actor primitive on top of Workers (developers.cloudflare.com/durable-objects). Each Durable Object has an ID; Cloudflare routes all traffic for that ID to exactly one instance at a time, providing strong consistency and serialized access to embedded storage.

Role

  • Actor-style stateful compute on the edge: one instance per key, guaranteed single-writer semantics.
  • Embedded transactional storage per object.
  • Natural fit for coordination, session state, collaborative documents, agent state machines.
  • Used inside Cloudflare's own internal AI stack for agent runtime — see sources/2026-04-20-cloudflare-internal-ai-engineering-stack.

Local / remote parity

Durable Objects are among the bindings introspectable via Local Explorer's API at /cdn-cgi/explorer/api, backed by Miniflare-managed local instances and on-disk state (Source: sources/2026-04-13-cloudflare-building-a-cli-for-all-of-cloudflare). The API shape is identical between local and remote; --local flag on cf or Wrangler is the only routing difference.

As a credentialed-proxy boundary (Agent Lee, 2026-04-15)

Cloudflare's Agent Lee uses a Durable Object as the permission-enforcement layer between an LLM-driven sandbox and Cloudflare's MCP server. The DO inspects generated code, classifies it read vs write, proxies reads directly, and blocks writes until the user approves via a dashboard elicitation gate. API keys are held inside the DO and injected server-side — they are never present in the sandbox. This is the canonical wiki instance of patterns/credentialed-proxy-sandbox — the DO's per-key single-writer + embedded-storage primitives are load-bearing (scoped credential state, deterministic classification logic co-located with the gate).

As the agent-actor substrate (Project Think, 2026-04-15)

Published the same day as the Agent Lee launch, Cloudflare's Project Think positions Durable Objects as the explicit actor-model substrate for AI agents. "Each agent is an addressable entity with its own SQLite database. It consumes zero compute when hibernated. When something happens (an HTTP request, a WebSocket message, a scheduled alarm, an inbound email) the platform wakes the agent, loads its state, and hands it the event."

The comparison table from the post, reproduced:

VMs / Containers Durable Objects
Idle cost Full compute cost, always Zero (hibernated)
Scaling Provision + manage capacity Automatic, per-agent
State External DB required Built-in SQLite
Recovery You build it Platform restarts, state survives
Identity / routing You build it Built-in (name → agent)
10,000 agents × 1% active 10,000 always-on ~100 active at any moment

This economic framing is the load-bearing scaling premise that drives the entire Project Think substrate.

Project Think exposes three DO-substrate-hosted primitives as first-class SDK APIs on top of the base Agent:

  • Durable execution via fibers — runFiber("name", async (ctx) => { … }) registers a durable function invocation in the agent's SQLite; ctx.stash() checkpoints; onFiberRecovered() resumes after eviction / restart / deploy. See concepts/durable-execution, patterns/checkpoint-resumable-fiber.
  • Sub-agents via Facets — this.subAgent(ChildClass, "name") returns a child DO colocated with the parent via Facets, each with its own isolated SQLite. "Sub-agent RPC latency is a function call. TypeScript catches misuse at compile time." See patterns/colocated-child-actor-rpc.
  • Persistent sessions — tree-structured conversation memory stored in DO SQLite with FTS5 full-text search, non-destructive compaction, and forking. See patterns/tree-structured-conversation-memory.

Context blocks (structured system-prompt sections the model can read + update, persisted across hibernation) also live in DO storage.

Seen in

  • sources/2026-05-13-cloudflare-browser-run-now-running-on-cloudflare-containers-its-faster — canonical wiki instance of DO + Container as a paired primitive with placement decoupling as the primary asymmetry. DO-enabled Cloudflare Containers create a Durable Object near the request, but the connected Container "may spin up on the other side of the world" — for chatty multi-message workloads (e.g. headless-browser control over WebSocket) the cross-region distance is paid per-message (concepts/do-to-container-cross-region-rtt). Browser Run's response: pre-warmed regional pools of DO+Container pairs (patterns/regional-pre-warmed-do-container-pair-pool), selecting the "DO-container pair closest to the user within that region" at request time. First wiki instance of DOs treated as a half of a paired primitive whose placement is load-bearing for a chatty-RPC partner.
  • sources/2026-04-21-planetscale-faster-planetscale-postgres-connections-with-cloudflare-hyperdrive — canonical "DO-not-on-write-path" datapoint. The Simeon Griggs 2026-02-19 PlanetScale × Hyperdrive prediction-market demo names the trade-off explicitly: "If we're going to use a Durable Object to broadcast updates over WebSockets, it may be tempting to make the Durable Object the write path to the database. However, this negatively impacts performance. Durable Objects are single-threaded and hosted in a single location, making them a bad candidate for the write path. Instead the Workers will send transactions to the database via the Hyperdrive connection." The DO in this architecture holds no authoritative state — only the WebSocket subscriber list. Writes go Worker → Hyperdrive → Postgres; on commit, the Worker "pings the Durable Object via the WebSocket connection to fan out that update to all other connected browsers". The post also flags the single-DO scaling ceiling and the canonical mitigation ("you can scale Durable Objects horizontally — sharded with a key"). Canonical wiki substrate for patterns/single-region-do-fanout-from-distributed-writers and the broadcast side of patterns/db-authoritative-with-websocket-notify.
  • sources/2026-04-13-cloudflare-building-a-cli-for-all-of-cloudflare — one of the remote-or-local bindings the new CLI unifies.
  • sources/2026-01-29-cloudflare-moltworker-self-hosted-ai-agent — used as the state layer for Moltworker's per-session agent state.
  • sources/2026-04-20-cloudflare-internal-ai-engineering-stack — used inside Cloudflare's internal agent runtime.
  • sources/2026-04-15-cloudflare-introducing-agent-lee — the credentialed proxy between LLM-generated code and the Cloudflare MCP server; classifies read vs write, hosts the elicitation gate, holds API keys so the sandbox never sees them.
  • sources/2026-04-15-cloudflare-project-think-building-the-next-generation-of-ai-agents — positioned as the actor-model substrate for AI agents; the three SDK primitives (fibers, sub-agents via Facets, sessions)
  • context blocks all live on DO storage. The "10,000 agents at 1% active" VM-vs-DO comparison quantifies the one-to-one-agent scaling premise.
  • sources/2026-04-16-cloudflare-ai-search-the-search-primitive-for-your-agents — DO-per-agent-session is the canonical consumer of the AI Search ai_search_namespaces binding. The support-agent example's SupportAgent extends AIChatAgent is a DO; creates a per-customer AI Search instance at session start (idempotent try { create() } catch {}); exposes search_knowledge_base + save_resolution tools that fan out across shared + per-customer instances. DO-backed conversation-history + per-customer search-instance together realise agent memory at both the episodic and semantic tiers.
  • sources/2026-04-16-cloudflare-artifacts-versioned-storage-that-speaks-git — one DO per Artifacts repo is the load-bearing substrate of the versioned-storage tier launched 2026-04-16. Each DO hosts a ~100 KB pure-Zig Wasm Git server + embedded SQLite (state.storage.kv) holding Git objects chunked across rows (2 MB row limit); pack-file snapshots spill to R2; auth tokens in [[systems/ cloudflare-kv|KV]]. "The ability to create millions (or tens of millions+) of instances of stateful, isolated compute is inherent to how Durable Objects work today, and that's exactly what we needed for supporting millions of Git repos per namespace." Post calls out the ~128 MB DO memory budget driving streaming on fetch + push paths (ReadableStream<Uint8Array> from raw WASM chunks) and delta-form-alongside-resolved-object storage as the key memory-discipline moves. Canonical wiki instance of patterns/do-backed-git-server and the repo-per-session dogfood pattern (Cloudflare uses Artifacts internally to persist filesystem + session history in per-session repos — fork, time-travel, diff on arbitrary agent state). Fourth 2026-04 launch whose load-bearing primitive is "one DO per caller-identified unit" (alongside Agent Lee, Project Think, and AI Search).
  • sources/2026-04-16-cloudflare-email-service-public-beta-ready-for-agents — one DO per email-address-resolved agent instance is the load-bearing shape of the Agents SDK's email surface (2026-04-16). The address-based resolver parses local+sub@domain and dispatches to a DO via {className: local, instanceName: sub}; embedded DO state (this.setState(...)) is the inbox's memory substrate — "the inbox becomes the agent's memory, without needing a separate database or vector store"; HMAC-SHA256-signed inReplyTo headers route replies back to the exact originating DO instance (patterns/signed-reply-routing-header). Fifth 2026-04 launch whose load-bearing primitive is "one DO per caller-identified unit" (alongside Agent Lee, Project Think, AI Search, and Artifacts).
  • sources/2026-04-17-cloudflare-introducing-flagship-feature-flags-built-for-the-age-of-ai — one DO per Flagship app as control-plane source of truth for the 2026-04-17 Flagship feature-flag service (private beta). Direct from the post: "the control plane writes the change atomically to a Durable Object — a SQLite-backed, globally unique instance that serves as the source of truth for that app's flag configuration and changelog. Within seconds, the updated flag config is synced to Workers KV, Cloudflare's globally distributed key-value store, where it's replicated across Cloudflare's network." Sixth 2026-04 launch whose load-bearing primitive is "one DO per caller-identified unit" (after Agent Lee, Project Think, AI Search, Artifacts, and Email Service) — but structurally distinct: Flagship is the first where the per-unit DO is explicitly paired with globally-replicated Workers KV as the edge-local read tier for the DO's data, because feature-flag evaluation must be zero-outbound-call in the same V8 isolate serving the request. Flagship is the canonical wiki instance of patterns/do-plus-kv-edge-config-distribution — DO as atomic-write source-of-truth with embedded audit-trail changelog, KV as eventually-consistent edge replica. The sibling pattern patterns/do-backed-git-server (Artifacts) uses KV differently — there KV holds auth tokens (a distinct read tier) while the per-repo DO holds the data; in Flagship KV holds the data (flag config) while the per-app DO holds the source-of-truth.
Last updated · 542 distilled / 1,571 read