# Durable multiplayer chat on Cloudflare

> Build a shared chat room with ordinary Everruns Agents and Engine sessions inside Cloudflare Durable Objects, with forks, reminders and history search.

Source: <https://everruns.com/docs/framework/examples/durable-chat/>

This walkthrough recreates [Earendil’s multiplayer chat tutorial](https://earendil.com/posts/pi-durable-on-cloudflare/) with ordinary Everruns Framework Agents. Conversations and search children run inside native Cloudflare Durable Objects. SQLite journals and durable alarms keep their work independent of connected browsers.

The [chat example](https://github.com/everruns/everruns/tree/main/examples/cloudflare-durable-chat) uses the shared Engine session-hosting profile and OpenRouter driver. This is experimental hosting; read [Durable Object hosting](https://everruns.com/docs/framework/durable-objects/) for its guarantees.

## See the demo

[Open the Cloudflare demo](https://everruns-durable-chat.everruns.workers.dev/), create a conversation, and copy the room link into a second browser.

[Durable multiplayer chat with Everruns on Cloudflare](https://www.youtube-nocookie.com/embed/eFmwod7GTrY?rel=0)

[Watch on YouTube](https://www.youtube.com/watch?v=eFmwod7GTrY).

![Alice and Bob share a launch-planning room. The assistant recalls their PostgreSQL decision, both participants are present, and committed messages have Fork here controls.](https://everruns.com/docs/_astro/durable-chat-shared.kOHoVw7m_27JLBP.webp)

Alice and Bob see the same committed conversation. **Copy room link** invites another browser; **Fork here** starts a new conversation from a committed message.

## Run the chat

Clone the whole repository because the example uses local workspace crates. Install Rust 1.96 and Node.js 24, then:

```sh
git clone https://github.com/everruns/everruns.git
cd everruns/examples/cloudflare-durable-chat
rustup target add wasm32-unknown-unknown
cargo install wasm-bindgen-cli --version 0.2.129 --locked
npm ci
npm run build
cp .dev.vars.example .dev.vars
```

Set `OPENROUTER_API_KEY` in `.dev.vars`. Start the local Worker:

```sh
npm run dev
```

The default model is [Muse Spark 1.3 Contributor](https://openrouter.ai/meta/muse-spark-1.3-contributor) through OpenRouter. Provider charges apply; Contributor uses submitted data for training. `MODEL` and `OPENROUTER_BASE_URL` are deployment settings.

Open the local URL, choose a name and create a conversation. Copy the room link into another browser. Both participants see committed messages. Record a decision in one conversation and ask about it in another to exercise the search child. Ask for a reminder in 30 seconds, close the browsers, and return after the deadline.

## Framework execution, application services

![Shared browsers use public room routes to a ChatRoom Durable Object. Stable admissions reach a ChatSession Durable Object for each conversation or search child, running Everruns Engine with its own journal and alarm. The shared driver calls OpenRouter through fetch.](https://everruns.com/docs/_astro/durable-chat.CnqZUOgV.svg)

A room is addressed through `/rooms/<name>/...`. It stores the conversation list, command receipts and reminders. Each conversation and history-search child has its own Durable Object, SQLite journal and alarm.

The app registers two ordinary Agents: `durable-chat` and `history-search`. Both use `Engine::builder().hosting(ObjectHosting::new(...))`. The child has only the search tool; the main agent has scheduling and history-search tools. Framework owns the model/tool loop, lifecycle, event history, interruption recovery, iteration limits and completion metadata.

`ObjectHosting` connects Engine to the Durable Object’s storage and alarms. Engine runs as WebAssembly, with the Worker providing storage, network requests and wakeups. Each session keeps the model selected when it was created; changing `MODEL` affects new sessions.

The shared OpenRouter driver handles Responses request encoding, streaming, provider options, retries, error mapping and usage metadata. The host adapter supplies `fetch`, bounded response bytes, cancellation, endpoint policy and the server-side credential.

## Accept commands without losing work

Every create, fork, send and schedule cancellation includes a stable `request_id`. The room stores a command fingerprint and receipt. A matching retry returns the same receipt; reusing the ID for another command is rejected.

Before accepting a mutation, the room arms its alarm. It then commits the receipt and outbox intent in one SQLite document update, without yielding between them. The room alarm delivers pending intents through Framework. Message delivery uses `Session::send_with_id` with an identity derived from the durable outbox entry. A crash after admission but before deleting the outbox entry resends the same identity, so Framework deduplicates it.

The room receipt acknowledges a durable delivery obligation. Framework’s own admission receipt is the authority for session execution. A room outbox is application delivery state; it does not replace the actor journal.

## Fork a committed prefix

A fork reads canonical events through Framework and selects committed user and assistant messages through the chosen boundary. It creates another registered session and uses the validated empty-history seed port to import that prefix. Pending tools, schedules and execution ownership are not inherited. A tool-call message cannot be used as a fork boundary.

The room’s event projection serves rendering, search and fork selection. Framework constructs model context from the session’s canonical history.

## Schedule reminders without a browser

The scheduling tool persists an instruction, deadline and optional recurrence. Its receipt is keyed by Framework’s tool execution identity, so retrying the same operation returns the existing schedule. The room alarm advances a due occurrence and records its delivery intent in the same write. Delivery enters the target session through normal Framework admission.

An occurrence has a stable message identity. Repeated delivery after a crash does not create another admission. Missed recurring ticks collapse into one follow-up. Cancellation disables future occurrences; it does not retract an already admitted instruction.

Schedules are an explicit application service here. A durable session journal alone does not provide a scheduler or room directory.

![A reminder is persisted in the room, browsers disconnect, the room alarm admits a stable reminder message, the session alarm runs Engine and commits a reply, and a reconnecting browser reads the result.](https://everruns.com/docs/_astro/durable-chat-reminders.Cwp8NirP_1Fw73Q.svg)

## Recover a history-search child

`search_history` creates a child keyed by the parent tool execution identity. That identity distinguishes different assistant tool-call messages even when a provider reuses a call ID. The child is an ordinary Framework session with its own durable admission and alarm. It can query room history through `search_conversations`, returning conversation IDs and sequence numbers.

![A second conversation invokes search_history, receives a cited PostgreSQL decision and answers. The sidebar shows the original conversation, a fork and independent history-search children.](https://everruns.com/docs/_astro/durable-chat-history.DusPOBKs_Z2pftoi.webp)

**Decision lookup** retrieves the choice recorded in **Launch plan**. The sidebar also shows **Fork of Launch plan** and the independent **History search** children. The tool result carries source conversation IDs and sequence numbers.

A parent interrupted while waiting can repeat this idempotent tool. It finds the same child and reads its reconstructible admission outcome; it does not create another child. Framework handles the interrupted tool and actor recovery. The room only stores application ownership and delivery state.

Search children and search-generated assistant answers are excluded from future search evidence. Retrieved transcripts are untrusted evidence, not instructions.

## Deploy and verify

```sh
npm run build
npm test
npm run check:bundle
npx wrangler deploy --dry-run
npx wrangler login
npm run deploy
npx wrangler secret put OPENROUTER_API_KEY
```

The public Worker handles browser requests. Room and session Durable Objects communicate through private bindings, and the OpenRouter API key stays on the server.

Public access and model costs

This example has no sign-in, room access controls or per-user quotas. Anyone with its URL can open rooms and send messages using the configured model budget. Add access and usage controls before sharing your own deployment.

The test suite covers shared conversations, forks, interrupted history searches and scheduled reminders across Worker restarts. It runs locally with workerd and simulated model responses.

See [Durable Object hosting](https://everruns.com/docs/framework/durable-objects/) for hosting guarantees and upgrade compatibility, and [Cloudflare’s platform limits](https://developers.cloudflare.com/workers/platform/limits/) for deployment constraints.