Skip to main content
A stateful actor is a single-threaded server that owns the state of one entity — one user, one cart, one call leg, one chat room. You write it as a TypeScript class; the platform runs one instance per name, routes every call for that name to that instance, runs your methods one at a time, and persists what you write. You never bind a socket, take a lock, or shard it. 
import { StatefulActor } from "@telnyx/edge-runtime";

export class Account extends StatefulActor {
  async debit(amount: number): Promise<{ ok: boolean; balance: number }> {
    const balance = (await this.ctx.storage.get<number>("balance")) ?? 0;
    if (balance < amount) return { ok: false, balance };   // check-then-act, no lock
    await this.ctx.storage.put("balance", balance - amount);
    return { ok: true, balance: balance - amount };
  }
}
That debit is a read-modify-write with no lock and no transaction. In a normal request handler that’s a race; here it isn’t — and that property is the whole product. How it works derives it from first principles, starting from a plain C server. Two words used precisely throughout these docs: the actor is the class you ship (Account); an instance is its per-name materialization (idFromName("acct_123") reaches the acct_123 instance of Account).

​
What the Runtime Guarantees

  • One instance per name — idFromName("acct_123") routes every call to a single owner; no two hosts run it at once.
  • One call at a time — single-threaded dispatch. No locks, no races inside an instance.
  • Durable before reply — a method’s result isn’t returned until the writes it made are persisted.
  • Memory is a cache — only what you write to storage survives eviction or restart.
Execution model states each precisely; How it works derives them from a plain C server.

Quick start

Scaffold, deploy, and curl an actor.

How it works

The C-vs-actor derivation from first principles.

Execution model

The four guarantees, stated precisely.

Lifecycle & placement

Where instances run; what survives a restart.

Addressing

Naming and routing instances.

Project structure

The two-export shape.

Shared actors

Reach one actor from many functions.

When to use

And when to reach for something else.

Runtime API

The full surface.

Alarms

Scheduled work from inside an actor.
  • Bindings — how bindings resolve on env
  • KV — globally distributed key-value storage
  • Execution Model — function lifecycle and concurrency