Quickstart

This quickstart creates a tiny flow and runs it end to end. The flow is deterministic, just one system node and no agents, so it advances to a terminal state on its own. You will verify it, boot a runtime, trigger it, and watch the trace.

Want an agent-backed flow built from scratch? Do Build your first flow instead. It walks through a support-ticket flow with classifier and resolver agents.

Prerequisites

The swarm binary on your PATH (see Installation).

That’s it — no database, no LLM credential, no API token.

No database — SQLite at .swarm/dev.db is the default; opt into Postgres later with --store postgres.
No LLM credential — the flow has no agents.
No workspace setup — an empty .swarm/data/ is auto-created next to the SQLite file.
No repository checkout — the platform spec is embedded in the binary.
No API token — the local runtime uses a built-in dev token on loopback.

Run the commands below from any directory.

Create a minimal flow

Four small files in a greeting-flow/ directory. A system node creates an entity and advances it to a terminal state.

greeting-flow/package.yaml

name: greeting-flow
version: 1.0.0
platform_version: ">=0.7.0 <0.8.0"
flows: []

greeting-flow/schema.yaml

stages:
  received:
    initial: true
  done:
    terminal: true
pins:
  inputs:
    events: [greeting.requested]

pins declares what this flow accepts from outside — here, one event. platform_version is the runtime range the bundle is written against.

greeting-flow/events.yaml

greeting.requested:
  swarm:
    source: external
  message: text

greeting-flow/nodes.yaml

greeter:
  event_handlers:
    greeting.requested:
      create_entity: true
      advances_to: done

No agents.yaml: this flow has no agents, just one system node, and the runtime accepts a bundle that omits it.

Verify the contracts

swarm verify --contracts ./greeting-flow

Expect verify ok. If a contract has a problem you get a named finding with a remediation line instead — fix and re-run. The static analyzer runs the same checks the runtime runs at boot.

Run it

Write a payload for the trigger event, then run the flow. swarm run start boots a runtime in process on loopback, publishes greeting.requested, and streams the run’s trace. It is the one-shot way to run a flow; for a long-running server you operate, use swarm serve (see Running the runtime).

echo '{"message": "hello"}' > payload.json
mkdir -p data
swarm run start --contracts ./greeting-flow --event greeting.requested \
  --payload payload.json --data ./data

--data names the read-only reference directory agents can see; the runtime requires one even when (as here) it is empty.Both payload.json and the runtime’s .swarm/ directory (store + workspace data) are created in the directory you run from. Use a scratch directory if you don’t want them in your project.The runtime logs using built-in dev API token on loopback on startup; only non-loopback binds need an explicit token, supplied via --api-token-file or serve.api_token_file in config.The trace shows greeting.requested arriving, the greeter node creating an entity, and the entity advancing to done (a terminal stage). Press Ctrl-C to stop the local runtime once you have seen it.

The in-process runtime binds 127.0.0.1:8081 and MCP on :8082. If another runtime is already using them, start a server on free ports and connect instead: swarm serve --contracts ./greeting-flow --data ./data --api-port 8091 then swarm run start --connect http://127.0.0.1:8091 --event greeting.requested --payload payload.json.

What just happened

swarm verify checked the bundle against the platform specification.
swarm run started a runtime (SQLite by default, stored under ~/.swarm/stores/projects/) and published your event.
The greeter node handled greeting.requested in one transaction: it created an entity and advanced it to done.
Every step was persisted, which is why the trace could stream it and a crash could replay it.

Next steps

Build a flow

A real flow with classifier and resolver agents.

Core concepts

The model behind what you just ran.

Operating Swarm

Trace, inspect, and run in production.

CLI reference

Every swarm command and flag.

For LLM agents helping a human author this: see Agentic flow authoring for the ranked artifacts to pull, the iteration loop to run, and anti-patterns to avoid.

Getting started

Core concepts

Build a flow

Handlers

Patterns

Operating Swarm

Prerequisites

What just happened

Next steps

Build a flow

Core concepts

Operating Swarm

CLI reference

​Prerequisites

​What just happened

​Next steps

Build a flow

Core concepts

Operating Swarm

CLI reference

Prerequisites

What just happened

Next steps