Architecture

Swarm has three main components that work together to deliver private, federated AI inference.

Components

| Component | Port | Role | |---|---|---| | Orchestrator | 8001 | Central coordinator: auth, RAG fan-out, LLM synthesis | | Aligner | 8000 | Edge RAG node: indexes local files, serves retrieval | | Server | 8002 | License management, user accounts, Tailscale provisioning |

Request lifecycle

When you send a query through the web UI:

  1. WebSocket connect — The browser opens a WebSocket to wss://your-orchestrator/ws/stream?token=<JWT>.

  2. Preprocessing — The Orchestrator's preprocessor model (llama3.2:3b) rewrites the query, extracts verticals, intent, and named entities.

  3. Federated fan-out — The FederatedRAG module sends POST /retrieve to all online Aligner nodes in parallel (3s timeout). Each request includes the security level, verticals, intent, and entities from preprocessing.

  4. Security filtering — Each Aligner filters chunks according to the caller's security level before returning results. The Orchestrator never receives data the caller is not authorized to see.

  5. Reranking — The reranker model (llama3.2:3b) scores all merged chunks from 0–1 and selects the top-k.

  6. Synthesis — The synthesizer model (llama3.1:8b) streams a response using the reranked chunks as context. Tokens are streamed back to the browser via the open WebSocket.

  7. Done — When synthesis completes, the Orchestrator sends a done message with source attribution, nodes queried, and escalation status.

Network topology

Internet
   │ HTTPS (ngrok)
   ▼
Orchestrator (port 8001)
   │ Tailscale VPN
   ├──► Aligner node-a (port 8000)
   ├──► Aligner node-b (port 8000)
   └──► Aligner node-c (port 8000)

All Aligner nodes are reachable exclusively via Tailscale private IPs. The Orchestrator never exposes Aligner addresses to clients.

State files

The Orchestrator stores state under ~/.swarm/:

| File | Contents | |---|---| | activation.json | License activation (chmod 600) | | tokens.json | Issued JWT tokens | | revoked.json | Revoked tokens | | logs/orchestrator.log | Log output |