Skip to main content
Division Swarm runs fleets of LLM agents as a single, durable, stateful system, built for the conditions that break demos: processes crash, costs run away, and a fleet of agents has to coordinate over hours or days without stepping on each other. You declare the system as a bundle of YAML contracts, a static analyzer validates them against the platform specification before the runtime boots, and a deterministic engine runs it. The defining decision is that the LLM does not run the system. Agents reason in small, scoped sessions and emit their results as events; deterministic code, never the model, decides what each result changes, so an agent can never leave the system in a state it only claimed to reach. This is more than an orchestrator that decides which agent runs next. Work is modeled as entities (an order, a ticket, a candidate business), each moving through a lifecycle of declared stages: guarded transitions, gates that must clear before the next step, timers that fire when something sits too long. An entity waits in a stage for days — on a timer or a human — then resumes exactly where it left off. And the parallelism is declarative: fan a batch out and each item gets its own flow instance with its own agent, hundreds advancing concurrently without touching each other, while a declared join decides when the batch is finished, ignores duplicate results, and enforces a deadline. Every transition, with its data writes and the events it emits, commits in one all-or-nothing transaction, and the whole history can be replayed or forked from the log. That is the shape of an operating system. An OS doesn’t make your programs correct; it makes them runnable: it schedules them, keeps them apart, tracks what they use, saves their state, and brings them back after a crash. Swarm is that layer for autonomous agents, running as a single Go binary, with SQLite by default for local and development runs and Postgres as the opt-in backend for production. Deterministic routing is one piece of it; the operating system is the rest.

​
How it works

A flow declares its states, events, agents, system nodes, tools, and policy as contracts. At boot, the engine loads the bundle, runs it through the static analyzer, and starts the event loop. From there:
  • System nodes are deterministic code. They subscribe to events, run a fixed handler pipeline, advance stages, and emit new events. No LLM decides what fires next.
  • Agents are LLM sessions. They subscribe to events, reason inside a scoped session, call tools, and emit events. They never write state directly; they emit, and a handler decides what gets written.
  • Humans decide through typed decision gates: a stage waits for a verdict, every outcome is declared, and the platform shows the decision as a card — a small typed form a person approves or rejects from the CLI, the API, or a chat channel on your phone (Telegram ships as the first channel pack). The platform itself never decides for you.
  • The outside world connects through packs — prebuilt provider integrations: webhooks arrive as typed, normalized events, and provider APIs become declared tools — signature checks, credentials, and rate limits owned by the platform, not your code.
Each event runs through a fixed handler pipeline and commits in a single transaction, so a crash mid-handler leaves no partial state. Because every event and every state change is persisted, any run can be replayed turn by turn or forked from a point in its history. And because determinism is the substrate, the whole thing is testable without spending a token: swarm test drives real flows through scripted scenarios, and the embedded mock backend runs agent turns with zero LLM credentials and zero Docker.

​
Design positions

Swarm makes a few opinionated choices and holds them:

Deterministic control loop

Routing is derived from declared subscriptions, not chosen by an LLM. Guards and rules use a strongly typed, non-Turing-complete expression language.

One transaction per transition

Guard, accumulate, compute, commit, emit: all-or-nothing. No partial state survives a crash.

Isolated agents

Each agent runs in a scoped session and sees only the events it subscribes to. Agents talk through a chain (coordinator → manager → worker) instead of one shared chat, so context windows stay small.

Replayable and forkable

Every event and state mutation is persisted. Reconstruct any run, or fork it from any point against new contracts.

Composable flows

A flow is a self-contained package with typed input and output pins. Wire flows together without refactoring.

Humans as a first-class actor

Typed decision gates with every outcome declared — approve from your phone, reject with required reasons, and nothing auto-decides. Autonomy is a dial, not a switch.
The tradeoff: a Swarm flow cannot be re-wired by an LLM at runtime. That rigidity is the point. See Why Swarm for when this is the right trade.

​
Where to go next

Why Swarm

When this tradeoff fits, and when it does not.

Quickstart

Boot the runtime and trigger your first run.

Core concepts

Flows, events, handlers, agents, and the engine.

Build a flow

A support-ticket flow from scratch.