Concepts

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 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:

TypeScript
Python

import { Actor, Reentrant } from "terse-sdk/actor"

export class Worker extends Actor {
    @Reentrant
    async wait(milliseconds: number): Promise<string> {
        await new Promise(resolve => setTimeout(resolve, milliseconds))
        return this.id
    }
}

import time
from durable_actors import Actor, reentrant


class Worker(Actor):
    @reentrant
    def wait(self, seconds: float) -> str:
        time.sleep(seconds)
        return self.id

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. TypeScript calls interleave across asynchronous work. Python calls overlap on worker threads.

Get started

Reference

What is a durable actor?

How is an actor identified?

Who manages the actor hosts?

When should I use a durable actor?

When should I use something else?

How should I model a durable actor?

How long does a durable actor stay up before cleanup?

What resource isolation does each durable actor get?

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

​What is a durable actor?

​How is an actor identified?

​Who manages the actor hosts?

​When should I use a durable actor?

​When should I use something else?

​How should I model a durable actor?

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

​What resource isolation does each durable actor get?

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

What is a durable actor?

How is an actor identified?

Who manages the actor hosts?

When should I use a durable actor?

When should I use something else?

How should I model a durable actor?

How long does a durable actor stay up before cleanup?

What resource isolation does each durable actor get?

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