Introduction

teaspill is a self-hosted platform for durable AI agents — agents that keep working, and keep their memory, across process restarts, deploys, and crashes. You define agents in TypeScript, run a small Docker Compose stack, and spawn, message, and watch your agents from your own app.

The problems it removes

Your agent's process can die mid-run. An AI agent is a long chain of model calls, tool calls, and sub-agents — minutes or hours of work that an ordinary process loses the moment it crashes or redeploys. Retrying from the top is worse: side effects run twice and the conversation forgets what already happened. teaspill records every step an agent takes, so after a crash the run resumes from the last completed step — same conversation, no repeated side effects.

Multi-agent coordination turns into plumbing. The moment one agent delegates to another, you're building queues, registries, and callback tracking — and debugging the races between them. In teaspill, spawning a sub-agent and sending a message are built-in operations with guaranteed delivery: a parent spawns children, goes to sleep, and is woken when results come back.

Streaming agent activity to a UI means building an event pipeline. Users expect to watch an agent think, call tools, and answer token by token — which usually means hand-rolling websockets, buffers, and replay logic. Every teaspill agent writes a live timeline of everything it does, and your frontend subscribes to it: replay history, follow live output, or join a conversation that started an hour ago.

"Where is the state?" should have one answer. Systems like this tend to scatter the same state across caches, databases, and streams, then struggle to keep the copies agreeing. teaspill gives each kind of data exactly one owner — working state, history, and the registry each live in one place — so there is no replication to keep consistent and no ambiguity about which copy is true. The architecture overview shows the whole picture.

What using it looks like

You define each agent type in TypeScript with defineAgent: typed spawn arguments, typed state, a model loop, and any tools you add. A small serve() call turns your definitions into a running service and registers it with the platform. From then on, your backend, your UI, and the teaspill CLI drive agents through the gateway — the single front door; nothing talks to the internal services directly.

Under it all, teaspill is built on Restate, an open-source durable-execution engine that runs as one of the stack's services. You don't need to know Restate to use teaspill — when you get curious, Restate in five minutes covers what it does for you.

What's in the box

• @teaspill/agents-sdk — define, serve, and register agents in TypeScript.
• @teaspill/frontend-sdk — subscribe to timelines and live agent lists from a browser or server, plus React bindings and an actions client for spawn/send/control.
• The gateway — the single HTTP entrypoint: commands, streams, live queries, and registration, behind API-key auth.
• The teaspill CLI — a dev loop (teaspill dev) plus spawn/send/control/logs from your terminal.
• A reference deployment — a complete, copyable example of the two services you deploy, with demo agents included.
• The compose stack — five infrastructure services in one docker-compose.yml.

What teaspill is — and isn't

teaspill is a framework plus a self-hosted platform, not a SaaS. There is no hosted tier: you run the stack, your keys stay yours, and your data never leaves your infrastructure.

Two design stances follow from that, and it pays to know them up front. Each deployment serves one tenant — you isolate customers by running separate stacks, not by configuring tenancy inside one. And there is no built-in permissions model: the gateway authenticates callers with API keys, and your backend decides who may do what. Writes never bypass your code.

teaspill is also not a model provider. The native engine works with any provider; the demo agents use Anthropic models.

Next steps

Head to Installation to boot the stack — the quick start then takes you from an empty file to a live, multi-agent timeline. If you'd rather understand the machine before running it, start with Concepts and read in order.