little-durable-objects

Named actors with serial method calls and saved state. Requires Node.js 20+.

npm install little-durable-objects

Start with the terminal chat tutorial: two listeners, live messages, and history that survives restarts. It includes complete files and expected output.

Local CLI

Export actors from src/durable-objects.ts. In your project directory:

npx little-durable-objects dev

Wait for Local actors ready at http://127.0.0.1:7100. In another terminal:

npx little-durable-objects run src/chat.ts Alice

Run a second listener in a third terminal:

npx little-durable-objects run src/chat.ts Bob

Once both clients have joined, type a message and press Enter. Both receive it. Reconnect either client to see the saved conversation. The CLI supplies credentials and stores SQLite metadata and snapshots in .little-durable-objects/. State survives restarts; losing that directory loses the actors. Restart dev after actor code changes.

dev --help lists options. token prints a one-hour local credential for tools such as wscat.

These CLI commands require version 0.1.25 or later.

Hosted clients

Set these before the first actor call:

export DURABLE_OBJECT_TOKEN='<session-token>'
export DURABLE_OBJECT_NAMESPACE_ID='my-project'
export DURABLE_OBJECT_CONTROL_PLANE_URL='https://objects.example.com'

Use a session token issued by your trusted backend. Terse supplies these variables to workflows. The SDK connects to the named actor and calls its methods.

See self-hosting for deployment and credentials. Runtime distributions bundle the Go provider.

WebSocket API

The gateway keeps connections while actors hibernate. Each accepted connection receives {"type":"state","state":{...}} automatically.

| API | Behavior | | ------------------------------------ | ---------------------------------------------------- | | Actor.get(id).connect(metadata) | Opens a connection with JSON-serializable metadata. | | onMessage(socket, message) | Handles incoming messages on the actor. | | onDisconnect(socket) | Handles a closed connection. | | this.broadcast(message) | Sends to connected clients. | | socket.send(message) | Sends to one client. | | socket.setTags(...tags) | Tags a connection for filtered broadcasts. | | socket.close() / socket.reject() | Closes a connection / rejects it during onConnect. |

this.connections lists connections during an invocation. From application code, Actor.get(id).broadcast(message) sends transient output without invoking the actor or saving state.

WebSockets use the control-plane URL unless DURABLE_OBJECT_SOCKET_GATEWAY_URL is set.

Reference

• CLI reference: commands, options, and environment variables.
• TypeScript API reference: actors, methods, connections, types, and errors.
• HTTP and WebSocket reference: deployments, tokens, connections, and callbacks.
• Local development: build and link a source checkout.

License

MIT © 2026 Terse