Durable Objects

This is the skill you reach for when you need state that sticks around between requests and belongs to a specific key: a chat room, a leaderboard, a rate limiter, a long-running agent. Each instance gets its own in-memory state plus a transactional KV store, and you can attach WebSockets directly to it. The constraints are tight: one TypeScript file per class, no npm imports, PascalCase class names that map to kebab-case URLs. You deploy once and instances spin up on demand per ID. Works well for multiplayer rooms or per-user agents where you need guaranteed single-threaded execution and can't tolerate the cold-start shuffle of stateless functions. Just remember that cross-instance coordination is on you.

GitHub stars: 532
last updated: Jun 11, 2026

View on GitHub

Install

$ npx -y skills add butterbase-ai/butterbase-skills --skill durable-objects --agent claude-code

Installs into .claude/skills of the current project.

Files

Butterbase Durable Objects

Durable Objects (DOs) are stateful per-key actors running on Cloudflare Workers. Each instance has its own in-memory state and a built-in transactional KV store. Use one when state must survive across requests for a single room/user/agent. For stateless work, use a serverless function instead (butterbase-skills:function-dev).

One tool: manage_durable_objects.

1. The mental model

Class: ChatRoom (deployed once)
   │
   ├── instance "lobby"      ─►  in-memory state + state.storage  +  WebSockets
   ├── instance "general"    ─►  separate state, separate sockets
   └── instance "user-123"   ─►  separate again

Each URL  https://<app>.butterbase.dev/_do/chat-room/<instance-id>
gets routed to the instance with that id. State is isolated per id.

A class is shared code; an instance is a unique key (/lobby, /general, /user-123). Different ids = different state. There is no shared cross-instance state.