Durable Objects

Single-threaded JavaScript objects on Cloudflare’s network, each with a globally unique name and its own private SQLite database, that any Worker can call to coordinate state.

What it is: Actor model
Used for: Coordination services
Type: Commercial product
Made by: Cloudflare, Inc.
License: Proprietary
Facts checked: 12 October 2026

What it is

A Durable Object is an instance of a class you write, addressed by an ID or a name. Any Worker anywhere that knows the name reaches the same single instance, which runs in one data center on a single thread, like an actor working through its mailbox. It is created on first use near the first caller (a locationHint or an eu, us or fedramp jurisdiction can steer that), stays in memory while busy, and is evicted when idle. Workers call it over HTTP, WebSockets or plain JavaScript RPC. That makes it the natural place for things that need one owner: a chat room, a document being edited, a game session, a rate limiter, an AI agent’s memory.

Each object has its own storage, private to it. In SQLite-backed objects (the default, and the only kind on the Free plan) SQLite runs as a library in the same thread, so queries return synchronously in microseconds, and the database can hold 10 GB on the paid plan. Writes are confirmed once three of five follower machines in other data centers have the change, then batched to object storage, which also lets you restore an object to any point in the last 30 days. An object can set one alarm at a time, retried with backoff if the handler throws, and with the WebSocket Hibernation API it can drop out of memory while clients stay connected and wake when a message arrives. Paid usage costs $0.15 per million requests, $12.50 per million GB-seconds of duration, and D1’s row prices plus $0.20 per GB-month for storage.

Why teams pick it

Strongly consistent, transactional state with no lock service: one single-threaded instance per name
Storage in the same thread as the code, so reads and writes often take microseconds
Scales out to millions of objects with no capacity planning; there is no limit on objects per class
WebSocket hibernation and alarms let idle rooms and scheduled work cost nothing in duration

Watch out for

One object is one thread on one machine: a soft limit of about 1,000 requests per second, so hot keys must be split across objects
An object stays where it was created; callers far from it pay the round trip, and location hints are best-effort
10 GB of SQLite storage per object (1 GB on Free), and key plus value may not exceed 2 MB
Duration is billed at 128 MB of memory whenever the object is active and cannot hibernate, so holding WebSockets open without hibernation gets expensive

The Durable Objects family

1 technologies built from or on Durable Objects

Built on it

Cloudflare Agents SDKOpen sourceA TypeScript framework (npm `agents`) in which every AI agent is a Durable Object: one addressable instance per user or task, with its own SQL state, WebSocket clients, scheduled jobs and MCP tools.

Alternatives

What all actor model have in common →

AkkaCommercialThe JVM toolkit that brought Erlang-style actors, clustering and sharding to Java and Scala; source-available since 2022, with a paid licence for most production use.

Apache PekkoOpen sourceThe Apache-licensed fork of Akka 2.6: actors, cluster sharding, persistence, streams and HTTP for Java and Scala, run by a foundation instead of a company.

celldBetaOpen sourceA self-hosted, distributed implementation of Cloudflare Durable Objects that runs an unchanged Workers app across your own machines, with its durable state in an object storage bucket you own.

How it fits with other technologies

What Durable Objects uses

What uses Durable Objects

One counter per room, called over RPC from a Worker · ts

import { DurableObject } from "cloudflare:workers";

export class Room extends DurableObject {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS hits (id INTEGER PRIMARY KEY, n INTEGER)");
  }

  // single-threaded, and the SQL API is synchronous
  async hit(): Promise<number> {
    const sql = this.ctx.storage.sql;
    sql.exec("INSERT INTO hits VALUES (1, 1) ON CONFLICT(id) DO UPDATE SET n = n + 1");
    return sql.exec("SELECT n FROM hits WHERE id = 1").one().n as number;
  }
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const name = new URL(request.url).pathname;       // every caller of /lobby reaches one object
    const room = env.ROOM.get(env.ROOM.idFromName(name));
    return Response.json({ hits: await room.hit() });
  },
};

// wrangler.jsonc:
//   "durable_objects": { "bindings": [{ "name": "ROOM", "class_name": "Room" }] },
//   "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Room"] }]

See it in a real stack

No architecture uses Durable Objects yet. Drop it into the playground and wire it up yourself.Open playground →

Where it came from2020–2026

Workers ran stateless code everywhere, and Workers KV gave them eventually consistent storage, but there was no way to hold strongly consistent state or to make two clients talk to the same instance: each request was load-balanced to a random isolate. Anything that needed coordination, such as chat, collaborative editing or game sessions, still needed a server somewhere else.

On 28 September 2020 Kenton Varda announced Durable Objects in closed beta, together with WebSocket support in Workers. The name breaks down as objects in the object-oriented sense, unique (one instance in the world per ID) and durable (with private persistent storage). They opened to all paid Workers users on 31 March 2021 and became generally available on 15 November 2021, with key-value storage.

On 26 September 2024 Cloudflare added SQLite storage in each object, running in the same thread as the code and persisted by a new Storage Relay Service that already ran D1. SQLite storage became generally available with 10 GB per object on 7 April 2025, when Durable Objects also came to the Free plan, pitched as the base for AI agents. Cloudflare has since built D1, Queues, Workflows and its Agents SDK on them.

Why it’s built this way

Route by name to one instance instead of load-balancing: Coordination needs every client of a room or document to reach the same code, so Cloudflare made the object, not the request, the unit of placement.
Storage private to each object: Splitting one big database into many small logical units keeps storage next to the code, so access can be very fast while staying strongly and transactionally consistent, and the system scales out by adding objects.
Synchronous SQLite in the same thread: With no network hop a query often finishes in microseconds, and not awaiting I/O avoids races where other events run mid-transaction; output gates hold replies until writes are confirmed so speed does not cost durability.

Timeline

2020
Announced in closed beta on 28 September, with WebSockets for Workers
2021
Open beta on 31 March; generally available on 15 November
2024
SQLite storage in every object, in beta from 26 September
2025
SQLite storage generally available with 10 GB per object; free tier added on 7 April
2026
Billing for SQLite storage starts in January

Sources8 · facts checked 12 October 2026

Improve this page on GitHub