Restate in five minutes

teaspill's coordination runs on Restate, an open-source durable-execution engine. You never talk to Restate directly — the gateway and the SDKs do — but five minutes of its vocabulary makes the rest of these docs click.

What Restate is

Restate is an engine for running code durably. It records what your code does as it does it, and when a process dies, it resumes the interrupted work from the last completed step — the durable execution you met on the previous page. teaspill runs Restate as one of the services in its self-hosted stack; your agent code registers with it and gets durability without writing any recovery logic.

Virtual objects

A virtual object is a named, addressable unit with its own state that handles one invocation at a time. Every teaspill agent is one. "Single-writer" means nothing else can mutate its state concurrently — which is what makes its event ordering trustworthy.

Concretely: when three messages arrive for the same researcher at once, Restate queues them and the researcher handles them one at a time, in order. There is never a moment where two turns of the same agent run concurrently and disagree about what happened. That guarantee is the foundation under the timeline: events can be numbered 0, 1, 2, … with no ambiguity because only one writer ever exists.

Virtual objects are also virtual: an object that isn't handling anything occupies no process, no thread, no connection. A million sleeping agents cost what a million database rows cost.

Durable sends

A durable send is a fire-and-forget message that cannot be lost. Restate records it before delivery and keeps trying until the target object processes it — across crashes on either side. When an agent spawns a child or sends a message to another agent, that's a durable send. There is no message broker to deploy and no delivery code to write; it is built into the coordination layer.

This is why the wake model can promise "the result arrives as a later wake": the child_finished message a child sends its parent is a durable send, so it arrives even if the parent's process was mid-deploy when the child finished.

What teaspill hides — and what shows through

Using teaspill, you never construct a Restate invocation, read its journal, or manage its state. Two things do show through, usefully:

• Registration. Your agent service announces itself through the gateway, and from then on Restate dials your service's URL directly for every invocation. That URL must be reachable from inside the stack — the one networking rule that bites everyone. The Self-hosting guide covers it.
• The ingress URL. Agent configuration carries the address agents use to reach each other — the ingressUrl field you'll meet in harness configuration. It points at the stack's coordination endpoint.

Next steps

Every agent — every virtual object — needs a name. Entities & addressing explains the one URL-shaped id that identifies an agent everywhere.