README.md

PilotSwarm Documentation

Five sections, in reading order. Pick your door.

1. Quick Start

Running in minutes.

• Docker Quickstart — the fastest path: browser portal + SSH TUI + two workers from one pilotswarm-starter image
• Local Setup — from source: install, PostgreSQL, first run

2. User Guide

Driving sessions as an end user — scenario-based, from "say hello" to multi-hour multi-agent workflows.

• Terminal UI track · Browser portal track
• Keybindings — TUI controls and slash commands

3. Architecture

How the system works. Start at the layering map, then descend.

• Layering — One Way In — every user-facing surface rides the Web API; the map of the whole system
• Architecture deep dive — durable runtime, CMS, client, worker
• Orchestration design (+ the loop, oriented)
• System reference — file map, lifecycle, schema, invariants
• Facts store design · Session creation policy · TUI architecture
• Internals — CMS schema, session manager

4. API Reference

The Web API — the one integration surface — and every client over it.

• Web API Reference — every operation, auth, errors, WebSocket streaming (generated from the operations table)
• Building a Custom UX — your own UI over the API: bootstrap, subscribe, replay, browser sign-in
• Choosing a Client — raw HTTP vs ApiClient vs SDK clients vs MCP: which to use when

5. Developer Guide

Building on PilotSwarm, deploying it, and contributing to it.

Building apps

• SDK apps (+ agents, facts & graph)
• CLI/TUI apps (+ agents)
• Plugin architecture & layering · Builder agent templates
• Examples — runnable samples incl. the DevOps Command Center

Deploying

• Deploying to AKS (+ topology)
• Portal Entra app roles · Knowledge harvester · Observability

Reference

• Configuration — env vars, storage, worker/client options
• Agent contracts — prompt/tool/runtime rules that stay true across code, docs, tests

Contributing to PilotSwarm

• Working on PilotSwarm — repo map, workflows, checklists
• TUI implementor guide
• Local test spec · integration test plan · facts table tests

---

Design records (not onboarding material): proposals — open designs · proposals-impl — implemented designs, kept as history · bugreports · _archive — retired point-in-time docs.