Architecture

teaspill is a small number of parts with sharply drawn jobs: a gateway in front, Restate coordinating every agent in the middle, two service planes you deploy — one running your agents, one running their workspaces — and read-side stores that everything flows out to, never back from. This page is the map; each stop links to the Concepts page that teaches it properly.

The map

          your backend · your UI · the teaspill CLI
                            │
                            │  HTTP — API key, or read token (reads only)
                            ▼
                     ┌─────────────┐
                     │   gateway   │  the single front door
                     └──┬───────┬──┘
       commands &       │       │      reads
       registration     │       │      (timelines, live queries)
                        ▼       └────────────────────────────────┐
                 ┌─────────────┐                                 │
                 │   Restate   │  coordination:                  │
                 │             │  runs every agent durably       │
                 └──────┬──────┘                                 │
                        │  dials your registered                 │
                        │  services directly                     │
            ┌───────────┴───────────┐                            │
            ▼                       ▼                            │
   ┌─────────────────┐     ┌─────────────────┐                   │
   │ agent-loop plane│     │  executor plane │                   │
   │   your agents   │     │    workspaces   │                   │
   └────────┬────────┘     └────────┬────────┘                   │
            │                       │                            │
            │    projections — one way                           │
            ▼                       ▼                            │
   ┌─────────────────┐   ┌──────────────────────────────┐        │
   │ durable streams │   │ Postgres catalog ──► Electric │       │
   │    (history)    │   │  (registry + archive)  (sync) │       │
   └────────┬────────┘   └───────────────┬──────────────┘        │
            │                            │                       │
            └──────── reads answered by the gateway ─────────────┘

Follow a command through it. Your backend POSTs a spawn to the gateway; the gateway hands it to Restate; Restate dials your agent-loop service and runs the new agent's first wake as a durable invocation. Everything the agent does is projected outward — events to the history store, its row to the catalog. Reads take the other path: your UI reads timelines and live queries back through the gateway straight from those stores, never through Restate. At no point does anything read those stores to decide what an agent does next.

One owner per concern

Three stores, three jobs — and no piece of data with two homes:

The rule this table encodes: when you wonder "where does X live?", there is exactly one answer, and the other stores hold at most a projection of it. Projections & the catalog teaches the read side in full.

The two planes you deploy

The compose stack from Installation is infrastructure — you configure it, but you don't write code in it. Your code lives in two independently deployed, independently scaled planes:

• The agent-loop plane hosts your defineAgent definitions behind serve(). It scales with how many agents run model loops concurrently. Replicas are interchangeable — an agent's state lives in Restate, not in the process.
• The executor plane hosts workspaces — the sandboxed environments where agents run commands and edit files. It scales with workspace demand: heavy shell work doesn't compete with model loops for the same machines. Workspaces & execution covers it.

Both register themselves with Restate through the gateway, and Restate dials them directly from then on. A deployment can be a compose service, a host process, or a fleet — the Self-hosting guide walks through each shape.

Design principles

Five stances shape everything above. Knowing them makes the rest of the docs predictable.

Projections flow one way. Everything you can read — timelines, catalog rows — is written outward from agent handlers, exactly once. Nothing is ever synced back in. One-way flow means there are no replication loops to keep consistent, and a slow or broken reader can never affect a running agent.

History is never control flow. Roughly: the timeline is for you and your UI; the platform writes it and never reads it to decide anything. The agent's own durable state is the single source of truth for behavior.

Writes never bypass your backend. teaspill has no platform-level permissions model, on purpose. The gateway authenticates callers (API keys; read tokens can only read), and your code decides who may spawn, send, or control what. There is no second authorization system to configure, audit, or contradict yours.

One deployment is one tenant. You isolate customers by running separate stacks, not by trusting tenancy configuration inside a shared one. Small blast radius, no cross-tenant bug class.

Control is four verbs, not process signals. Outside intervention is interrupt, pause, resume, or archive — agents aren't OS processes, and anything richer you want to say to one is an ordinary typed message. Lifecycle & control covers all four, plus how archived agents come back.

Where to go deeper

The Concepts section teaches this picture one idea at a time, in reading order: durable agents & the wake model, Restate in five minutes, entities & addressing, timelines & events, projections & the catalog, workspaces & execution, harnesses, multi-agent patterns, and lifecycle & control. If you only read one, read the first — the wake model is the idea the rest lean on.