Orchestrator setup

The Orchestrator is the central coordinator of your Swarm mesh. It handles authentication, fans out queries to Aligner nodes, reranks results, and synthesizes responses with a local LLM.

Requirements

  • Python 3.11+
  • uv
  • Ollama with llama3.1:8b and llama3.2:3b pulled
  • ngrok (for external access via the web UI)

Installation

git clone https://github.com/SwayamDani/orchestrator
cd orchestrator
uv sync
source .venv/bin/activate

Configuration

Copy the example files:

cp config.example.yaml config.yaml
cp .env.example .env

.env (required)

| Variable | Description | |---|---| | SWARM_JWT_SECRET | Secret for signing JWT tokens (min 32 chars) | | SWARM_USERS | Comma-separated user:pass pairs | | SWARM_ADMINS | Comma-separated usernames with admin role | | SWARM_OLLAMA_URL | Ollama base URL (default: http://localhost:11434) |

config.yaml (nodes)

nodes:
  - name: my-laptop
    tailscale_ip: 100.x.x.x
    port: 8000
    role: personal    # or 'shared'
    security_level: A

Starting

./startup.sh

This runs uvicorn on port 8001 and starts an ngrok tunnel. The ngrok URL is printed to stdout.

Running manually (no ngrok)

uvicorn src.main:app --reload --port 8001

Important: The Orchestrator must run with a single uvicorn worker. It stores WebSocket broadcast state and the NodeRegistry in-process.