Installation¶

Get StrataRouter up and running in minutes.

Requirements¶

Minimum Requirements¶

OS: Linux, macOS, or Windows (64-bit)
Python: 3.8+ (3.9+ recommended)
Memory: 512MB RAM minimum
CPU: 1 core (2+ recommended for production)
pip: Python package manager (comes with Python)

Recommended for Production¶

OS: Ubuntu 20.04+ or Debian 11+
Python: 3.10+
Memory: 4GB+ RAM
CPU: 4+ cores with SIMD support (AVX2 / NEON)
Storage: 10GB+ SSD

Optional Dependencies¶

PostgreSQL 13+ — for state persistence and audit logs
Redis 6+ — for distributed semantic caching
Docker 20+ — for containerized deployment

Warning

We recommend using a virtual environment to isolate your StrataRouter installation and avoid dependency conflicts.

Python (Recommended)¶

Quick Install¶

pip install stratarouter

Verify the installation:

python -c "import stratarouter; print(stratarouter.__version__)"

Virtual Environment Setup¶

# Create virtual environment
python -m venv venv

# Activate it
source venv/bin/activate   # macOS/Linux
venv\Scripts\activate      # Windows

# Install StrataRouter
pip install stratarouter

Install with Provider Extras¶

StrataRouter supports multiple embedding providers. Install with the extras you need:

OpenAIAnthropicGoogleHugging FaceRuntime FeaturesAll Providers

pip install "stratarouter[openai]"

pip install "stratarouter[anthropic]"

pip install "stratarouter[google]"

pip install "stratarouter[huggingface]"

pip install "stratarouter[runtime]"

pip install "stratarouter[all]"

Rust Crate¶

Add to your Cargo.toml:

[dependencies]
stratarouter-core = "0.2"
stratarouter-runtime = "0.1"

Or use cargo add:

cargo add stratarouter-core
cargo add stratarouter-runtime

Docker¶

Pull and Run¶

docker pull stratarouter/stratarouter:latest

docker run -d \
  -p 8080:8080 \
  -e DATABASE_URL="postgresql://localhost/stratarouter" \
  -e OPENAI_API_KEY="your-key" \
  stratarouter/stratarouter:latest

Docker Compose (Production)¶

# docker-compose.yml
version: '3.8'

services:
  stratarouter:
    image: stratarouter/stratarouter:latest
    ports:
      - "8080:8080"
      - "9090:9090"  # Prometheus metrics
    environment:
      - DATABASE_URL=postgresql://postgres@db/stratarouter
      - REDIS_URL=redis://redis:6379
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    depends_on:
      - db
      - redis
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  db:
    image: postgres:15
    environment:
      - POSTGRES_DB=stratarouter
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

Start the stack:

cp .env.example .env
# Edit .env with your settings
docker-compose up -d
curl http://localhost:8080/health

Kubernetes (Helm)¶

helm repo add stratarouter https://charts.stratarouter.dev
helm install stratarouter stratarouter/stratarouter \
  --set env.OPENAI_API_KEY=$OPENAI_API_KEY \
  --set env.DATABASE_URL=$DATABASE_URL

Or using a bare Kubernetes manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: stratarouter
spec:
  replicas: 3
  selector:
    matchLabels:
      app: stratarouter
  template:
    metadata:
      labels:
        app: stratarouter
    spec:
      containers:
      - name: stratarouter
        image: stratarouter/stratarouter:latest
        ports:
        - containerPort: 8080
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: stratarouter-secrets
              key: database-url

See Production Deployment for the full Kubernetes guide.

Build from Source¶

For the latest features or to contribute:

1. Clone the Repository

git clone https://github.com/agentdyne9/stratarouter
cd stratarouter

2. Install Rust (required for core)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

3. Install Python Dependencies

pip install -e ".[dev]"

4. Build Rust Core

cd core
maturin develop --release
cd ..

5. Run Tests

pytest tests/

Framework Integrations¶

Install additional frameworks to integrate with StrataRouter:

LangChainLangGraphCrewAIAutoGen

pip install langchain langchain-openai

pip install langgraph

pip install crewai

pip install pyautogen

Verify Installation¶

Check that everything is installed correctly:

import stratarouter

print(f"[OK] StrataRouter version: {stratarouter.__version__}")
print(f"[OK] SIMD enabled: {stratarouter.simd_enabled}")

# Quick smoke test
from stratarouter import Router
router = Router(dimension=384)
print("[OK] Core: ready")

# CLI check
stratarouter --version
stratarouter health

Tip

SIMD enabled means StrataRouter is using hardware-accelerated vector operations for maximum performance. This is expected on all modern x86-64 and ARM systems.

Database Setup¶

PostgreSQL (Optional — for state persistence)¶

# Ubuntu/Debian
sudo apt-get install postgresql
createdb stratarouter
stratarouter migrate  # Run migrations

# Or Docker
docker run -d \
  -e POSTGRES_DB=stratarouter \
  -e POSTGRES_PASSWORD=password \
  -p 5432:5432 \
  postgres:15

Redis (Optional — for distributed caching)¶

# Ubuntu/Debian
sudo apt-get install redis-server
redis-server

# Or Docker
docker run -d -p 6379:6379 redis:7

Environment Variables¶

Create a .env file for your settings:

# LLM Provider Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...

# Optional: Database & Cache
DATABASE_URL=postgresql://localhost/stratarouter
REDIS_URL=redis://localhost:6379

# Optional: Observability
PROMETHEUS_PORT=9090
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Troubleshooting¶

ImportError: No module named 'stratarouter'

Make sure you're in the correct virtual environment:

which python
pip list | grep stratarouter

# Reinstall if needed
pip uninstall stratarouter
pip install stratarouter

Build fails with 'linker not found' or 'libclang not found'

Install build tools for your OS:

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install build-essential python3-dev

macOS:

xcode-select --install

Windows: Install Microsoft C++ Build Tools or Visual Studio with C++ support.

'maturin' command not found

pip install maturin
export PATH="$HOME/.local/bin:$PATH"  # macOS/Linux

SIMD not enabled

Your CPU needs SIMD support (AVX2 on x86, NEON on ARM)
Rebuild with: RUSTFLAGS="-C target-cpu=native" maturin develop --release
StrataRouter still works without SIMD but at reduced performance

Installation hangs or is slow

pip install --no-cache-dir stratarouter
# or
pip install --upgrade pip && pip install stratarouter

Permission denied error

Don't use sudo with pip. Use a virtual environment instead:

python -m venv venv
source venv/bin/activate
pip install stratarouter

Rust compilation errors

rustup update
rustc --version  # Should be 1.70+
cargo clean && cargo build --release

Platform-Specific Notes¶

macOSLinuxWindows

Apple Silicon (M1/M2/M3):

# Ensure native Python (not Rosetta)
python --version
pip install stratarouter

Intel Mac: Standard installation works fine.

brew install postgresql redis  # Optional dependencies

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install python3-dev build-essential libssl-dev pkg-config
pip install stratarouter

RHEL/CentOS:

sudo yum install python3-devel gcc gcc-c++ openssl-devel
pip install stratarouter

Using PowerShell (Recommended):

python -m venv venv
.\venv\Scripts\Activate.ps1
pip install stratarouter

WSL2 (Best experience): Use the Linux instructions above.

Native Windows: Requires Microsoft C++ Build Tools for building from source.

Upgrading¶

# Upgrade to the latest version
pip install --upgrade stratarouter

# Verify upgrade
python -c "import stratarouter; print(stratarouter.__version__)"

See Changelog for version-specific migration notes.

What's Next?¶

Quickstart

Build your first semantic router in 5 minutes.

→

Core Concepts

Understand how semantic routing works.

→

Configuration

Configure thresholds and performance options.

→

Production Deployment

Docker, Kubernetes, and cloud deployment.

→

Having trouble? Open an issue on GitHub or ask on Discord.