Configuration

Swarm is configured by CLI flags and swarm.yaml; environment variables are not a configuration source. swarm verify is the only command that runs without a runtime or a token. Every other command targets the runtime’s API and needs a bearer token.

Connecting to the runtime

The runtime exposes one HTTP listener serving health, readiness, /v1/rpc, /v1/ws, and the MCP routes. Its default address is http://127.0.0.1:8081. Configuration is one file format — swarm.yaml — discovered in layers, later layers overriding earlier ones:

user-global $XDG_CONFIG_HOME/swarm/swarm.yaml
project ./swarm.yaml
local operator ./.swarm/swarm.yaml (machine-local overrides; keep it out of git)
explicit --config <path> (or SWARM_CONFIG, the one accepted env pointer)

Flags override config. Ambient environment variables are not a configuration source (see Retired settings).

string

Base URL of the runtime. Default http://127.0.0.1:8081. Config: connection.api_server.

string

File holding the bearer token. Required for every command except swarm verify. Config: connection.api_token_file (client side) / serve.api_token_file (server side). An inline --api-token is not accepted, to keep secrets out of shell history.

swarm run

swarm run start reaches a runtime in one of two ways:

Local (default). With no --connect, it boots a runtime in process on 127.0.0.1:8081. Override the port with --api-port <n>.
Connected. With --connect <url>, it attaches the run to an already-running runtime (started by swarm serve) instead of booting its own.

Either way, a bearer token is required.

Local startup flags

These flags configure a runtime that swarm serve or swarm run start boots in-process. They have no effect when attaching to a running runtime with --connect.

string

Explicit swarm.yaml config file; overrides the discovered layers listed above, then built-in defaults apply for anything unset.

Older releases read a separate config.yaml next to the running binary. That two-file model was unified into the layered swarm.yaml described on this page.

string

Path to the agent-visible read-only /data reference directory. Resolution order: --data > workspace.data_source in swarm.yaml > the auto-default .swarm/data/ (created next to .swarm/dev.db if it doesn’t exist, so the runtime starts with no /data configuration). Available on both swarm serve and swarm run start.

--store and --backend are documented under Runtime store and LLM backend and credentials.

The configuration file: `swarm.yaml`

One schema, discovered in layers (later overrides earlier):

Layer	Path	Typical use
user-global	`$XDG_CONFIG_HOME/swarm/swarm.yaml`	personal defaults across projects
project	`./swarm.yaml`	committed project configuration
local operator	`./.swarm/swarm.yaml`	machine-local overrides; keep out of git
explicit	`--config <path>` (or `SWARM_CONFIG`)	scripts, tests, alternates

Keys are trust-tiered:

Tier	Example keys	Accepted from
Project-safe	LLM backend/models, runtime tuning, budgets, loopback listeners	Any layer
Sensitive	Public/wildcard listener binds, host-escaping paths, elevated workspace capabilities	Local-operator/user layers, or a flag

A committed swarm.yaml in a cloned repo cannot expose your machine. The top-level sections (swarm doctor reports which layers loaded and what each supplied):

connection.* — CLI target: api_server, api_token_file, contexts
serve.* — listeners and server token: api_listen_addr, mcp_listen_addr, api_token_file
paths.* — contracts_path, platform_spec_path, prompt and tooling paths
store.* / database.* — backend selection and Postgres parameters
llm.* — backend profile, model aliases per backend, session rotation, provider rate/concurrency limits, claude_cli settings
workspace.* — backend preference, data_source, image settings
runtime.* — recovery_on_startup, decision-card cadence (first reminder, urgency, reminder interval, input draft TTL)
budget.* — global/per-entity/system monthly caps, human-task budgets
sharding.* — parallelism bounds for sharded agent workloads
provider_triggers.* / channels.* — pack directories

Runtime section shape

runtime:                      # event loop and recovery tuning
  max_concurrent_agents: 16
  event_poll_interval: 100ms
  recovery_on_startup: true

database:                     # Postgres connection (used when store.backend is postgres)
  host: 127.0.0.1
  port: 5432
  name: swarm
  user: postgres
  password: postgres
  sslmode: disable
  pool_size: 10

store:
  backend: sqlite             # sqlite (default) | postgres
  sqlite:
    path: .swarm/dev.db       # auto-created if missing

workspace:
  data_source: ./reference    # default: auto-created at .swarm/data/
  backend: ""                 # workspace-isolation backend (claude_cli uses Docker)

llm:
  backend: anthropic          # anthropic | claude_cli | openai_compatible (default anthropic)
  models:                     # alias -> { backend: concrete-model } overrides
    regular:
      anthropic: claude-3-5-sonnet
      claude_cli: sonnet
      openai_compatible: gpt-4o
  session:
    lock_ttl: 10s
    rotate_after_turns: 40
    rotate_on_parse_failures: 3
  claude_api:                 # tuning for the anthropic backend
    default_model: claude-3-5-sonnet
    haiku_model: claude-3-5-haiku
    max_retries: 3
    retry_backoff: 1s
  claude_cli:                 # tuning for the claude_cli backend
    command: claude
    timeout: 30m
    output_format: json
    retries: 2
    no_session_persistence: false
    use_tmux: false
  openai_compatible:
    base_url: https://api.example.com
    default_model: gpt-4o
    low_cost_model: gpt-4o-mini

extensions:                   # typed extensions; inline, namespaced per extension
  # ...

CLI flags override config keys (--store > store.backend, --backend > llm.backend, --data > workspace.data_source). There are no env-var equivalents. See the sections below for each subsystem’s precedence.

Backend selection is --backend or llm.backend only; for the removed spellings, see Retired settings.

Runtime store

The runtime stores events, entity state, gates, timers, and sessions in a relational database. SQLite is the default for local and development runs (file-backed at .swarm/dev.db, no service needed); Postgres is the opt-in backend for external and production deployments. Select the backend with --store sqlite or --store postgres, or store.backend in swarm.yaml; the flag overrides the config key.

string

Runtime store backend: sqlite (local/dev default, file at store.sqlite.path, default .swarm/dev.db) or postgres (external/production opt-in).

object

Postgres connection parameters (used when postgres is selected): database.host, database.port, database.name, database.user, database.sslmode, database.pool_size. Defaults: 127.0.0.1, 5432, swarm, postgres, disable. The password is never read implicitly: declare database.password_env: <VAR> and exactly that named environment variable becomes the accepted source (see Retired settings).

LLM backend and credentials

Select the LLM backend with the --backend flag on swarm serve or swarm run start, or with llm.backend in swarm.yaml. Environment variables never select the backend (see Retired settings). The default backend when nothing is set is anthropic. A flow with no agents boots without any credential.

Backend	Required credential	Notes
`anthropic`	`ANTHROPIC_API_KEY`	The Anthropic API transport. Credential is checked at the first agent turn.
`claude_cli`	`CLAUDE_CODE_OAUTH_TOKEN`	Drives the Claude CLI as a subprocess. Validated at boot when the bundle declares agents. Also needs the tool-gateway variables `SWARM_TOOL_GATEWAY_URL`, `SWARM_TOOL_GATEWAY_CONTAINER_URL`, `SWARM_TOOL_GATEWAY_TOKEN` (the repository `.env` provides them).
`openai_compatible`	`OPENAI_COMPATIBLE_API_KEY`	Any Chat Completions-compatible HTTP JSON endpoint. Also needs `llm.openai_compatible.base_url` (or `SWARM_OPENAI_COMPATIBLE_BASE_URL`) and `SWARM_OPENAI_COMPATIBLE_DEFAULT_MODEL`. `SWARM_OPENAI_COMPATIBLE_LOW_COST_MODEL` is optional, used when budget policy throttles an actor.

Credentials are read from the environment and a local credential store, and are never logged or persisted. For the removed profile ids, see Retired settings.

Storage

string

Runtime-private root for git repositories written by artifact_repo_commit (a deployment-environment variable, not a config key — one of the few the runtime reads directly). Default /var/lib/swarm/artifacts. Never mounted into agent sessions.

Budget caps

The budget_*_percent thresholds in policy.yaml are percentages of a monthly USD cap, set in the budget: configuration section. A scope is monitored only when its cap is above zero. See Budget and cost.

swarm.yaml

budget:
  global_monthly_cap: 500       # USD per month across the deployment
  per_entity_monthly_cap: 5     # USD per month per entity
  system_monthly_cap: 100       # USD per month for platform/system work

Sharding

When a node fans a workload across multiple instances of an agent (Agent sharding), the sharding: section bounds the parallelism so it cannot run away. The defaults apply when a key is omitted.

swarm.yaml

sharding:
  max_shards_per_job: 8         # most shards a single job may split into
  max_concurrent_shards: 12     # most shards running at once across the runtime
  per_shard_timeout: 30m        # a shard that exceeds this is treated as failed
  per_shard_budget_cents: 0     # optional spend cap per shard (0 = none)
  max_retries_per_shard: 0      # retries before a shard is given up on
  circuit_breaker_threshold: 0  # shard failure rate that trips the breaker (0 = off)

Retired settings

These spellings are removed and fail with a teaching error naming the replacement:

Removed	Replacement
Ambient `SWARM_*` configuration variables	The CLI flag or `swarm.yaml` key named in the error (`SWARM_CONFIG` remains the one accepted env pointer)
`llm.runtime_mode`	`llm.backend`
`SWARM_LLM_BACKEND` / `SWARM_LLM_RUNTIME_MODE`	`--backend` flag or `llm.backend`
Backend profile ids `api` / `cli_test` (`--backend api` is rejected with `unsupported llm backend profile`)	`anthropic` / `claude_cli`
`SWARM_DB_` / `PG` implicit password fallbacks	`database.password_env: <VAR>`

Contract reference

Language reference

Operations reference

Connecting to the runtime

swarm run

Local startup flags

The configuration file: `swarm.yaml`

Runtime section shape

Runtime store

LLM backend and credentials

Storage

Budget caps

Sharding

Retired settings

​Connecting to the runtime

​swarm run

​Local startup flags

​The configuration file: swarm.yaml

​Runtime section shape

​Runtime store

​LLM backend and credentials

​Storage

​Budget caps

​Sharding

​Retired settings

Connecting to the runtime

swarm run

Local startup flags

The configuration file: `swarm.yaml`

Runtime section shape

Runtime store

LLM backend and credentials

Storage

Budget caps

Sharding

Retired settings