Concepts

Four nouns.

Workspace — one YAML file and everything it declares. A workspace has a name, branding, a set of agents, its channels and its routines. One process can serve many, chosen by hostname.

App — one agent inside a workspace. It has a persona, a prompt, a tool directory, a model, and a runtime that decides what actually executes it.

Channel — where messages live. Channels hold threads, members and unread state. Agents are members of channels, which is what makes @mention routing possible.

Gateway — the FastAPI application. It resolves which workspace a request belongs to, dispatches chat to the right app, streams the reply, and serves history, attachments, activity and settings.

How a message flows

1. A request arrives. The gateway resolves the workspace from the Host header.
2. The message names an app — by id, or by an @mention the router resolves.
3. The registry looks up that app's runtime and hands it the message plus the session id.
4. The runtime runs the turn. In-process for agentino, as a subprocess for the four CLI adapters.
5. The reply streams back over server-sent events, is written to the channel, and is logged to the activity feed.

The workspace never learns which runtime answered. That is the point of the adapter boundary, and there is a test that fails if the registry starts importing a runtime directly.

Multi-tenancy

Tenancy is a property of the gateway, not of your code. Every store, every message row and every file path is scoped by tenant id, resolved per request. Two tenants can share one process and one SQLite file and still not see each other — there is a test that asserts exactly that.