Skip to main content

​
What is a durable actor?

A durable actor is a serverless stateful object. An actor is a small backend for a piece of state you want to protect. It keeps state and compute in one place.

​
How does Terse relate to durable-actors?

durable-actors is an open source project under the MIT License. It includes the actor runtime, the SDK, and examples. You can run it yourself. Terse is the managed, hosted service for durable-actors. You deploy with terse deploy. Terse runs and scales the actor hosts. You manage projects in the Terse app.

​
How is an actor identified?

Each actor instance has an ID. Its project, class, and ID identify it globally. You can reach the same actor from anywhere. Keep the same ID across reconnects and restarts. Use a new ID for a new conversation or run.

​
Who manages the actor hosts?

Terse manages scaling and placement of actor hosts. Successful calls save persisted state. Hosts can scale down. The next call restores that state.

​
When should I use a durable actor?

  • AI agents
  • Human approvals
  • Collaborative documents
  • Chat rooms
  • Shared queues and rate limits

​
When should I use something else?

Use a stateless handler for independent requests. Use a database for cross-entity queries and analytics. Use a batch system for large data scans. Actor calls do not create a transaction across several actors. Coordinate cross-actor work explicitly.

​
How should I model a durable actor?

Think of an actor as your smallest piece of atomic state. Keep related values and their updates together.
  • Conversation: one actor for its messages and current turn.
  • Document: one actor for its content and revision number.

​
How long does a durable actor stay up before cleanup?

The runtime’s default idle timeout is 10 seconds. Deployments and actor resource settings can override it. Method calls and WebSocket messages reset activity. Running handlers defer eviction. An idle instance can leave memory; saved state remains. Open WebSockets keep the host and connections alive. The actor instance can still be evicted. Without open sockets, the idle host shuts down. A later call restores the actor from saved state. Idle cleanup does not delete actor state. Store approvals in persisted fields. Let the handler return during the wait.

​
What resource isolation does each durable actor get?

Each hosted actor runs in an isolated sandbox with CPU and memory limits. The underlying machines are shared. Runtime defaults are 0.25 CPU and 256 MiB RAM per actor.

​
Why are durable actors sequential by default? How do I disable that?

Mark a method as reentrant to allow overlap:
Reentrancy lets later calls enter before the marked method finishes. Ordinary calls still serialize with each other. A running ordinary call still blocks new entries. Mark the actual entry point; a decorated helper does not change its caller’s policy. Calls interleave across asynchronous work.

​
Where can I find more examples?

The open source durable-actors repository has runnable examples. They include AI chat, a chatroom, and collaborative documents. Each one has a README. The TypeScript guide builds a bank account actor step by step.