Skip to content
Layerr Layerr

Quickstart

Layerr is a self-hosted AI orchestration gateway. This guide takes you from zero to your first routed request in three steps.

Prerequisites

Section titled “Prerequisites”
  • Docker and Docker Compose (for the recommended path)
  • At least one LLM provider API key (Anthropic, OpenAI, OpenRouter, or a local Ollama instance)
  • Node.js 22+ (if running without Docker)

Step 1: Run Layerr

Section titled “Step 1: Run Layerr”

With Docker Compose (recommended):

Terminal window
git clone https://github.com/aspyrelabs/layerr
cd layerr
cp .env.example .env
docker compose up

Layerr runs as a single Node process. One server (server.ts) serves the UI, all /api/* routes, and the OpenAI-compatible /v1/* routes from one port:

ServicePortPurpose
layerr3000UI + /api/* orchestration routes + OpenAI-compatible /v1/*

The port defaults to 3000 and is configurable via the PORT environment variable. Open http://localhost:3000 to access the UI.

Without Docker:

Terminal window
npm install
npm run dev

The single process listens on PORT (default 3000).

Step 2: Add Your First Provider

Section titled “Step 2: Add Your First Provider”
  1. Open the UI at http://localhost:3000
  2. Create an account (or use the default admin credentials from your .env)
  3. Go to Settings → Providers → Add Provider
  4. Select your provider type and paste your API key

Layerr validates the key before saving it. If validation passes, the provider is immediately available for routing.

Quick local setup with Ollama:

Terminal window
# Pull a model and Layerr will auto-detect it
ollama pull llama3.2

Add http://localhost:11434 as a provider with type Ollama — no API key needed.

Step 3: Make Your First Request

Section titled “Step 3: Make Your First Request”

Use the chat UI or send directly to the OpenAI-compatible proxy:

Via the chat UI:

Open http://localhost:3000, start a conversation, and Layerr will classify your intent and route to the best available provider automatically.

Via the API (OpenAI-compatible):

Terminal window
curl http://localhost:3000/v1/chat/completions \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{ "role": "user", "content": "Write a binary search in TypeScript" }],
    "stream": true
  }'

Using "model": "auto" lets the intent classifier choose. The response includes x-layerr-model and x-layerr-intent headers showing which model was selected and why.

What Happens on Each Request

Section titled “What Happens on Each Request”

Every request goes through the Intelligence Layer pipeline:

  1. Intent classification — which of the 8 categories is this? (CODING, REASONING, CREATIVE, VISION, GENERAL, DOCUMENT, FAST, SECURITY)
  2. Workload analysis — language, complexity, and context signals
  3. Workspace profile — your saved provider preferences and budgets
  4. Strategy selection — cost, speed, quality, or balanced
  5. Scoring — candidate models scored against the workload
  6. Execution — request sent, streaming response returned
  7. Explainability — routing decision recorded and explained
  8. Replay — full trace stored for comparison and debugging
  9. Adaptive learning — outcomes feed back into future scoring
  10. Quality evaluation — response quality assessed against expectations
  11. Provider economics — cost and savings tracked per request
  12. Entitlements & security — capability and permission checks enforced throughout

Open the Replay tab after any request to see the full decision trace.

Next Steps

Section titled “Next Steps”