Documentation

SwarmLab Docs

Everything you need to install SwarmLab, set up your first agents, and start shipping work. Skip around — each section stands alone.

Install

SwarmLab ships as a single static binary. Install it with one command:

curl -fsSL https://get.swarmlab.dev | sh

Verify the installation:

swarmlab --version
# SwarmLab v0.9.2 (build a3e1f08)

swarmlab doctor
# ✓ Binary OK
# ✓ Embedded Postgres available
# ✓ Port 3100 free
# ✓ Encryption key present

Tip: Run swarmlab doctor after every upgrade to confirm your environment is healthy. It checks binary integrity, database connectivity, port availability, and encryption key status.

First run

Start SwarmLab for the first time. It bootstraps an embedded Postgres instance, runs migrations, and opens the dashboard:

swarmlab start
# ⠋ Bootstrapping embedded Postgres...
# ✓ Database ready (v16.2)
# ✓ Migrations applied (14 tables)
# ✓ Dashboard → http://localhost:3100

On first launch SwarmLab generates a unique encryption key stored at ~/.swarmlab/encryption.key. This key is used to encrypt all provider API keys at rest with AES-256-GCM.

Warning:Back up ~/.swarmlab/encryption.key immediately. If you lose this file you will not be able to decrypt stored API keys and will need to re-enter them.

Quickstart

Go from zero to a working agent in four steps:

Step 1 — Add a provider key

swarmlab config set anthropic.api_key sk-ant-...

Step 2 — Create your first agent — give it a name, pick a model, and set its role

swarmlab agent create \
  --name "code-reviewer" \
  --role reviewer \
  --provider anthropic \
  --model claude-sonnet-4-20250514

Step 3 — Drop a task on the board or open a chat conversation to ask a question

swarmlab task create \
  --agent code-reviewer \
  --prompt "Review the latest PR for security issues"

Step 4 — Watch it work in Mission Control — live terminal output, spending, and status

swarmlab logs --follow

Agents→

Learn how to define agent roles, skills, and routing.

Workflows→

Chain multiple agents together with conditional logic.

Config file

SwarmLab reads its configuration from ~/.swarmlab/config.toml. Here is a full reference:

# ~/.swarmlab/config.toml

[server]
port = 3100
host = "127.0.0.1"
data_dir = "~/.swarmlab/data"

[scheduler]
max_concurrent = 8
retry_limit = 3
timeout_seconds = 300

[anthropic]
api_key = "sk-ant-..."
default_model = "claude-sonnet-4-20250514"

[openai]
api_key = "sk-..."
default_model = "gpt-4o"

[ollama]
host = "http://localhost:11434"
default_model = "llama3"

Note: API keys set via swarmlab config set are encrypted before being written to this file. If you edit the file directly, keys must be in plaintext and will be encrypted on the next swarmlab start.

Providers & keys

SwarmLab supports six adapters out of the box. Each connects to a different LLM provider or local runtime:

Adapter	Auth method	Description
`claude-local`	API key	Anthropic via local Claude Code CLI
`codex-local`	API key	OpenAI Codex running locally
`http/anthropic`	API key	Anthropic HTTP API (cloud)
`openai`	API key	OpenAI HTTP API (cloud)
`openrouter`	API key	OpenRouter multi-provider gateway
`ollama`	None (local)	Local Ollama instance

Set a provider key from the CLI:

# Anthropic
swarmlab config set anthropic.api_key sk-ant-...

# OpenAI
swarmlab config set openai.api_key sk-...

# OpenRouter
swarmlab config set openrouter.api_key or-...

All keys are encrypted at rest using AES-256-GCM with a per-installation encryption key. Keys never leave your machine.

Environment variables

Environment variables override config file values. Useful for CI and container deployments:

Variable	Default	Description
`SWARMLAB_PORT`	3100	Dashboard and API port
`SWARMLAB_DATA_DIR`	~/.swarmlab/data	Data and database directory
`ENCRYPTION_KEY`	(auto-generated)	Base64-encoded 256-bit encryption key
`ANTHROPIC_API_KEY`	(none)	Anthropic provider API key
`OPENAI_API_KEY`	(none)	OpenAI provider API key
`SWARMLAB_LOG_LEVEL`	info	Log verbosity: debug, info, warn, error

# Example: run on a custom port with debug logging
SWARMLAB_PORT=4200 SWARMLAB_LOG_LEVEL=debug swarmlab start

Agents

An agent is a named AI worker with a role, a model, file permissions, and a budget. Think of each one as a team member with a specific job. Agents pick up tasks automatically, work them, and hand off results to the next agent in line.

# agent definition (TOML)
[agent.code-reviewer]
role = "reviewer"
provider = "anthropic"
model = "claude-sonnet-4-20250514"
system_prompt = """
You are a senior code reviewer. Focus on security,
performance, and maintainability.
"""
skills = ["read-file", "diff-parse", "comment-pr"]
max_tokens = 4096
temperature = 0.2

7 built-in roles:

PlannerBreaks goals into milestones and assigns work
BuilderWrites and edits code with full filesystem access
ReviewerReads diffs and checks work against conventions
DesignerScoped to asset and styling files
ResearcherGathers information with read-only access
FrontendFocused on UI components and client-side code
BackendFocused on APIs, databases, and server-side logic

Skillsare reusable tool definitions that agents can invoke. Each skill maps to a function the agent can call during execution — such as reading a file, making an HTTP request, or posting a comment. You can define custom skills or use the built-in set.

Workflows

A workflow is a visual pipeline of connected steps. Unlike missions (which are planned by an AI lead), workflows are graphs you design yourself and re-run whenever you need them. Think CI/CD pipelines, but with AI agents doing the work.

Agent TaskRuns an agent with a prompt (the most common step)
HTTP RequestCalls any external API
CodeRuns a JavaScript snippet
If/ElseBranches the flow based on a condition
Human GatePauses for your approval before continuing

Workflows support four trigger types:

manual— triggered via CLI or dashboard
cron— scheduled on a recurring interval
webhook— triggered by an inbound HTTP POST
event— triggered by an internal system event

{
  "name": "pr-review-pipeline",
  "trigger": { "type": "webhook", "path": "/hooks/pr-opened" },
  "nodes": [
    {
      "id": "review",
      "type": "agent-task",
      "agent": "code-reviewer",
      "prompt": "Review the PR diff for security issues."
    },
    {
      "id": "gate",
      "type": "human-gate",
      "message": "Reviewer flagged issues. Approve to merge?"
    },
    {
      "id": "notify",
      "type": "http-request",
      "method": "POST",
      "url": "https://hooks.slack.com/...",
      "body": { "text": "PR review complete." }
    }
  ],
  "edges": [
    { "from": "review", "to": "gate" },
    { "from": "gate", "to": "notify" }
  ]
}

Approvals

Approvals are human checkpoints. They pause a workflow or task until you review what an agent did and decide whether to continue. If you're using worktrees, completed work automatically creates a merge request with a diff you can approve in one click.

Approve or reject from any connected bridge:

# Discord / WhatsApp bridge commands
approve r_a4f9
reject r_a4f9

# CLI
swarmlab run approve r_a4f9
swarmlab run reject r_a4f9

# Dashboard
# Click Approve / Reject on the pending gate card

Gates time out after 24 hours by default. Set a custom timeout with the timeout_minutes field in the HumanGate node definition.

CLI commands

The SwarmLab CLI is the primary interface for managing agents, tasks, and workflows:

Command	Description
`swarmlab start`	Start the server and dashboard
`swarmlab stop`	Gracefully shut down the server
`swarmlab doctor`	Check system health and prerequisites
`swarmlab config`	Get or set configuration values
`swarmlab agent`	Create, list, update, or delete agents
`swarmlab task`	Create tasks and assign them to agents
`swarmlab run`	Execute a workflow or approve/reject gates
`swarmlab logs`	Stream or query logs (--follow, --agent, --run)

Run any command with --help to see all available flags and subcommands.

Troubleshooting

Common issues and their solutions:

Port 3100 is already in use

Something else is already using port 3100. You can either close that process or tell SwarmLab to use a different port:

SWARMLAB_PORT=4200 swarmlab start

Encryption key not found

SwarmLab can't find your encryption key at ~/.swarmlab/encryption.key. If you have a backup, restore it now. Otherwise you can generate a fresh one, but any previously saved API keys will need to be re-entered:

swarmlab config reset-encryption-key

Agent task hangs or times out

Make sure your API key is set correctly. Run swarmlab doctor to check all connections. If everything looks good, the task might just need more time — try bumping the timeout:

swarmlab config set scheduler.timeout_seconds 600
swarmlab doctor

Ollama models not appearing

First, make sure Ollama is actually running on your machine. Then pull the model you want — it won't show up in SwarmLab until it's downloaded locally:

ollama pull llama3
swarmlab config set ollama.host http://localhost:11434

Ready to get started?

Explore pricing plans or dive deeper into everything SwarmLab can do.

View pricing Explore features