Skip to main content
Swarm runs as a single Go binary. Local and development runs use file-backed SQLite by default, so no database service is required to start; Postgres is the opt-in backend for external and production deployments.

​
Requirements

Go 1.23. Docker is needed only for the workspace image used by the claude_cli backend; SQLite is the default store and needs no service.

​
Build and run

There are no prebuilt releases yet; install from source (Go 1.22+):
Then:
swarm serve uses SQLite at .swarm/dev.db by default, so no database service is required for local development. To opt into Postgres, add --store postgres and point the runtime at a Postgres 16 it can reach:
swarm serve is the long-running process: it runs the engine and serves the HTTP API, the health endpoints, and the MCP server. By default it binds http://127.0.0.1:8081. (The Quickstart’s swarm run start is the one-shot, in-process alternative; serve is what you operate.)
  • Credentials — the API token and LLM credential rules — are covered below.
  • CLI target. Every other swarm command targets the same address; point them elsewhere with --api-server, a named --context, or connection.api_server in config.
Configuration is explicit by design: flags and typed swarm.yaml keys, not ambient environment variables. (Retired SWARM_* variables fail with an error naming the replacement — see Configuration.)

​
Runtime store

Events, entity state, gates, timers, and sessions all live in a relational database. SQLite is the default for local and development runs (file-backed under ~/.swarm/stores/projects/<name>-<hash>/dev.db, no service needed); Postgres is the opt-in backend for external and production deployments. Persistence is the substrate, not an add-on: every event lands in the store, every entity state change lands in a separate mutation log, and runs are correlated by run_id, which is what makes replay and fork possible. Select the backend with --store sqlite or --store postgres (or store.backend in swarm.yaml). With Postgres, connection details are typed config (database.host, database.port, database.name, database.user, database.sslmode); the password is never read implicitly — declare its source explicitly with database.password_env: <VAR> and the named variable becomes the one accepted environment read.

​
Credentials and backend selection

Beyond swarm verify, you always need an API token, and an LLM credential once your flow runs agents:
  • An API token. A swarm serve/swarm run start bound to a loopback address like 127.0.0.1 (numeric, not a hostname) uses a built-in dev token (with bearer auth still enabled); any non-loopback bind requires an explicit token via --api-token-file / serve.api_token_file. Every command except swarm verify authenticates against this.
  • An LLM credential. Needed only when your flow has agents; an agent-free flow boots without one. Select a backend with the --backend flag on swarm serve/swarm run start (or llm.backend in config.yaml); env vars never select the backend. The default is anthropic; the alternatives are claude_cli and openai_compatible. See LLM backend and credentials for each backend’s required credential and tuning.
Credentials are read from the environment and a local credential store, and are never logged or persisted. See Configuration for the full list.

​
Verifying the install

swarm verify is the one command that works purely against files on disk, every other command targets the running runtime’s API.

Trigger your first run

Boot the runtime and watch a run execute.