Getting started

Swarm is a federated RAG mesh that distributes AI inference across machines you own. This guide gets you from zero to a working mesh.

Prerequisites

Before you begin, you need:

  • Two or more machines you control (a laptop + a desktop works fine)
  • Tailscale installed and authenticated on every machine
  • Ollama installed on the machine that will run the Orchestrator
  • uv (Python package manager) on the Aligner machines
  • A Swarm license key (get one at swarm/pricing)

Step 1 — Pull Ollama models

On the machine that will run the Orchestrator, pull the required models:

ollama pull llama3.1:8b    # synthesis
ollama pull llama3.2:3b    # preprocessor + reranker

Step 2 — Deploy the Aligner

On each machine you want to index, clone the Aligner and run it:

git clone https://github.com/SwayamDani/aligner
cd aligner
uv sync
source .venv/bin/activate
./tools/run serve -d ./docs -m ./security.json

The Aligner listens on port 8000 by default. Make sure this port is accessible over your Tailscale VPN.

Step 3 — Configure the Orchestrator

On your main machine:

git clone https://github.com/SwayamDani/orchestrator
cd orchestrator
cp config.example.yaml config.yaml
cp .env.example .env

Edit .env and set at minimum:

SWARM_JWT_SECRET=your-secret-here
SWARM_USERS=alice:password123

Edit config.yaml to add your Aligner nodes under the nodes: key:

nodes:
  - name: laptop
    tailscale_ip: 100.x.x.x
    port: 8000
    role: personal
  - name: desktop
    tailscale_ip: 100.y.y.y
    port: 8000
    role: shared

Step 4 — Start the Orchestrator

uv sync
source .venv/bin/activate
./startup.sh

The Orchestrator starts on port 8001 and creates an ngrok tunnel for external access.

Step 5 — Open the web UI

  1. Copy your ngrok URL from the startup output.
  2. Open the web UI and enter your ngrok URL as the Orchestrator URL.
  3. Sign in with the username and password from SWARM_USERS.

You should see your nodes appear in the mesh canvas. Start querying!

Next steps