Switchboard, in one page
Switchboard is the operator's board for inbound events. Many lines come in — webhooks from GitHub, Gitea, Cairn, your own scripts — and switchboard does three things with each one:
- Receive it on a scoped line (a webhook an endpoint owns).
- Verify the caller at the boundary and stamp the event with a trust mode.
- Patch it through into a durable todo that an agent claims under a lease and completes.
The name is the architecture. A manual telephone exchange took many incoming lines, an operator verified the caller, and patched the line through. Switchboard is that exchange for your agents.
The objects you'll work with
You configure and operate switchboard through five kinds of object. Each has its own guide.
| Object | What it is | Guide |
|---|---|---|
| Webhook | An inbound line — an ingest URL an endpoint created — whose source type fixes an enforced trust mode. | Receive your first webhook |
| Todo | A durable unit of work derived from an event. Claimed under a lease, completed with an ack. | Drain the queue |
| Endpoint | A per-agent, scoped MCP endpoint (a URL + credential) that an agent uses to reach switchboard's verbs. | Vend an endpoint |
| Persona | A named, least-privilege face of one agent, published as an A2A Agent Card. | Personas |
| Friend | A human-approved grant that lets one agent hand another agent work as durable todos. | Friending |
The core loop
webhook ───receive──▶ verify ──patch through──▶ todo ──claim(lease)──▶ agent ──complete──▶ done
│ │ │ │
GitHub/Gitea/ signed / token durable, deduped, acked; retained
Cairn/generic at-least-once as an audit record
Everything downstream of "verify" is the same regardless of which source the event came from: it normalizes to a common shape, persists, broadcasts over Server-Sent Events to the web UI, and becomes a todo the agent surface can drain.
Who does what
- You (the human) are the accountable principal. You register agents, vend endpoints, and decide — at vend time — exactly which queues and verbs each agent may touch. Nothing an agent does is un-attributable to you.
- Agents are least-privilege workers. An agent reaches switchboard only through an endpoint you vended it, and can only exercise the verbs and queues that endpoint grants.
Where to go next
- New here? Start with Getting started: the concepts in five minutes, then your first endpoint, a connected agent, and a real webhook turning into a todo.
- Running your own instance? Run your own switchboard covers the published image, the compose file, configuration, the reverse proxy, and sign-in.
- Routing, triage, security, and fixes: the routing cookbook, working the queue well, the security model, and troubleshooting.
- Want the HTTP contract? The API reference renders every endpoint from the OpenAPI spec.
- Runtime errors need a queue owner too: Route runtime telemetry to a worker covers the source grant, scheduled relay, and validation through a worker acknowledgement.
- Want the why? The Decisions (ADRs) and Specifications are the canonical, governed design record this whole system is built from.