Guided tutorials¶
Learn SwarmKit — the open-source AI platform runtime — from zero to production through 22 progressive levels. Levels 1–16 build on one workspace, adding complexity incrementally — every transcript in them is a real run, every YAML is validated against the schema and run on the mock provider in CI (examples/tutorials/), and every screenshot is the portal on that workspace; levels 17–22 each take one shipped capability — harness executors, funnels, command packs and attachments, agents calling agents, operations, the fleet — and are runnable on the mock provider where the level says so.
Prerequisites¶
# Install SwarmKit — [ui] is the web portal `swarmkit serve` hosts; Levels 1–10 need only the CLI
uv tool install "swarmkit-runtime[ui]"
# Verify
swarmkit --help
For real LLM calls (Level 3+), set an API key:
Levels¶
| Level | Topic | Features covered |
|---|---|---|
| 1 | Hello World | Install, workspace, one agent, validate, run |
| 2 | Archetypes | Reusable agent configs, model settings, prompts |
| 3 | Skills | Capability, decision, coordination skills |
| 4 | Multi-Agent | Hierarchy, delegation, parallel execution, DAG |
| 5 | MCP Tools | Custom MCP servers, permission tiers, sandboxing |
| 6 | Structured Delegation | Task plans, scopes, two-phase planning, dual model |
| 7 | Governance & Safety | Decision gates, IAM scopes, circuit breakers, HITL |
| 8 | Observability | Tracing, drift detection, debugging CLI, OTel |
| 9 | Conversations & Memory | chat, workspace memory, governed memory (swarmkit memory, reconcile, quarantine) |
| 10 | Knowledge & RAG | A search MCP server (FTS5, then ChromaDB), docs-reader, grounding, the knowledge server |
| 11 | Serve & HTTP API | swarmkit serve, REST endpoints, SSE, auth |
| 12 | Triggers & Canary | Cron, webhooks, canary deployments |
| 13 | Authoring & Review | init, author, edit/--thorough, the gap log, the review queue |
| 14 | Packaging & Distribution | mcp-serve, publish, install, expertise packages |
| 15 | Production Example | A webhook-driven handbook review using levels 1–14, run for real |
| 16 | Sequencing & Contracts | Correlated runs, defer and resume, gate state, resolving over HTTP, contracts, the reference orchestrator |
| 17 | Harness executors | Claude Code / opencode as a node, adapters, the governed gateway, relay + trust, sandbox |
| 18 | Funnels & approval | validate → judge → approve, role registry, quorum, --require-verified, cited-change, stop |
| 19 | Command packs & attachments | A binary as a skill, pack: grants, a file beside the input |
| 20 | Agents calling agents | agent skills, pack:workspace, A2A server + client, the portal's remote agents |
| 21 | Providers, storage & operations | Declarative providers, storage status/migrate, system, eval, knowledge-pack |
| 22 | Running a fleet | Control plane, enrolment (Mode A / B), adopt → deploy → drift, a gate from the panel, gap mining, telemetry — with a walkthrough video |
How to use¶
Each level has: - What you'll learn — features covered - Build it — step-by-step instructions with YAML - Run it — commands to test - What happened — explanation of the output
just demo-capstone runs every level's HTTP-reachable feature in one workspace (examples/capstone), on the mock provider, in under a minute. Runnable demos for levels 17–22 are just demo-* targets named in each level; just with no arguments lists them all. examples/ holds the workspaces the demos run.
Beyond the tutorials¶
After Level 22, see the SDLC walkthrough — a video tour of a production delivery workspace that combines the level features with the governance primitives: Funnels, multi-party approval, and Contracts. (Recorded before sequencing moved out of SwarmKit in 1.189.0; the artifact tour is current, the stage-graph sections are historical.)
Start with Level 1: Hello World.