Alayra-Nexus

One OpenAI-compatible endpoint. Every model. Zero key chaos.

Route Anthropic Claude, OpenAI GPT, Google Gemini, Groq, and OpenRouter
through a single hardened proxy. Pool multiple API keys per provider, load-balance
across them, auto-failover between tiers, and give every team their own scoped key —
with full usage analytics and cost tracking built in.

Built and maintained by Alayra Systems Pvt. Limited · Islamabad, Pakistan

---

Why Alayra Nexus?

Most teams hit the same wall: multiple AI providers, API keys scattered across engineers, no visibility into who spent what, and a hard-coded provider string that makes switching models painful.

Alayra Nexus is the infrastructure layer that sits between your application and every AI provider. Change one URL. Get load balancing, automatic failover, team-level access control, and a live cost dashboard — without touching your application code.

---

Features

Capability	Details
Key Pool Management	Store unlimited API keys per provider, encrypted at rest with AES-256-GCM
Intelligent Load Balancing	Automatic rotation across active keys; cooling and banned keys are automatically bypassed
Circuit Breaker	Per-key breaker with escalating cooldown, a single half-open recovery probe, separate 429 handling, and auto-ban on repeated auth failures
Cache-Aware Sticky Routing	Multi-turn conversations stay pinned to the same upstream so the provider's prompt cache isn't thrown away by round-robin
Content Guardrails	Optional, pluggable prompt/response filtering — redact PII or block banned content and injection patterns. Off by default
Tiered Failover	Premium → Standard → Fast chains; when the best key fails the next tier fires instantly
Cost-Aware Routing	Optional: within a tier, bias toward the cheapest healthy, in-headroom provider using registry pricing — a tiebreaker that never overrides health or cache affinity
OpenAI-Compatible API	Drop-in /v1/chat/completions — change one base URL, nothing else
Anthropic-Compatible API	/v1/messages too, so Claude Code and the Anthropic SDKs route through the same pool — streaming, tools, and all
Team Key Issuance	Create scoped access tokens per team, each with an independently configurable RPM limit
BYOK (Bring Your Own Key)	A team can register its own provider keys, encrypted at rest and routed only for that team's traffic — with optional fall-back to the shared pool, or hard isolation
Real-Time Rate Limiting	Per-key RPM enforcement via Redis with live utilization meters (per-key TPM budgets are configurable; enforcement is on the roadmap)
Cost Tracking	Per-request USD cost computed from model pricing, attributed to the requesting team
Full Analytics Dashboard	Request trends, token breakdowns, team leaderboard, provider split — powered by Chart.js

---

Supported Providers

Provider	Models
Anthropic	Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku, and all Claude variants
OpenAI	GPT-4o, GPT-4 Turbo, GPT-3.5 Turbo, o1, o3-mini
Google	Gemini 1.5 Pro, Gemini 1.5 Flash, Gemini 2.0 Flash
Groq	LLaMA 3.1 405B / 70B, Mixtral 8x7B, Gemma 7B
OpenRouter	Any model in OpenRouter's catalog via a single unified key
Custom	Any OpenAI-compatible endpoint via configurable base URL

---

Architecture

  Your Application / IDE / Agent / Script
           │
           │  POST /v1/chat/completions
           │  Authorization: Bearer <team-key>   ← optional, enables per-team analytics
           ▼
  ┌──────────────────────────────────────────────────────────┐
  │                   Alayra Nexus Gateway                  │
  │                                                          │
  │   ┌───────────────┐          ┌─────────────────────────┐ │
  │   │  Team Auth    │          │     Rate Limiter        │ │
  │   │  SHA-256 hash │          │   RPM / TPM via Redis   │ │
  │   └───────┬───────┘          └──────────┬──────────────┘ │
  │           └─────────────┬───────────────┘                │
  │                    ┌────▼───────┐                        │
  │                    │   Router   │                        │
  │                    │  Premium   │                        │
  │                    │  Standard  │  ← tiered failover     │
  │                    │   Fast     │                        │
  │                    └────┬───────┘                        │
  │        ┌────────────────┼──────────────┬──────────────┐  │
  │        ▼                ▼              ▼              ▼  │
  │    Anthropic          OpenAI        Google           Groq │
  │    (Claude)           (GPT)        (Gemini)      OpenRouter│
  └──────────────────────────────────────────────────────────┘
           │
           ▼
    Token usage → async buffer → batched PostgreSQL write
    Real-time metrics  → Redis
    Analytics          → Admin Dashboard

---

Quick Start

Option A — Published image (fastest, no clone)

A multi-arch image (amd64 + arm64) is published to the GitHub Container Registry. If you already have Postgres and Redis, run the gateway with one command:

docker run -d --name alayra-nexus -p 3000:3000 \
  -e DATABASE_URL="postgresql://user:pass@host:5432/nexus" \
  -e REDIS_URL="redis://host:6379" \
  -e MASTER_ENCRYPTION_KEY="$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")" \
  -e ADMIN_PASSWORD="change-me" \
  ghcr.io/alayra-systems-pvt-limited/alayra-nexus:latest

Pin a version for production (e.g. :1.2.0) rather than :latest.

Option B — Docker Compose (brings its own Postgres + Redis)

Nothing to clone and nothing to compile: Compose downloads the published image and starts Postgres and Redis alongside it.

curl -O https://raw.githubusercontent.com/Alayra-Systems-Pvt-Limited/Alayra-Nexus/main/docker-compose.yml

# Two secrets. Keep MASTER_ENCRYPTION_KEY safe — without it your stored
# provider keys can never be decrypted again.
cat > .env <<EOF
MASTER_ENCRYPTION_KEY=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
ADMIN_PASSWORD=change-me
NEXUS_VERSION=1.2.0
EOF

docker compose up -d

Dashboard is live at http://localhost:3000. The container applies its own database migrations on startup, and prints your generated Nexus API key on first run — docker compose logs nexus to see it.

DATABASE_URL and REDIS_URL are set by Compose; you do not need to supply them. Omit NEXUS_VERSION to track latest, but pin it in production.

git clone https://github.com/Alayra-Systems-Pvt-Limited/Alayra-Nexus.git
cd alayra-nexus
cp .env.example .env   # set MASTER_ENCRYPTION_KEY and ADMIN_PASSWORD

docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build

---

Option C — Manual Setup

Prerequisites: Node.js 20+, PostgreSQL 15+, Redis 7+

git clone https://github.com/Alayra-Systems-Pvt-Limited/Alayra-Nexus.git
cd alayra-nexus

npm install

cp .env.example .env
# Edit .env with your values

# Generate a secure MASTER_ENCRYPTION_KEY (run this once and save it):
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Postgres and Redis must be running. Don't have them locally? Start just the
# two dependencies with Compose and run the gateway from source:
docker compose up -d postgres redis

# Run database migrations
npm run migrate

# Start
npm run dev          # development — hot reload via tsx
npm run build && npm start   # production

Dashboard is live at http://localhost:3000

[!TIP] Cannot reach Redis / Cannot reach PostgreSQL on startup? Both are hard dependencies — Redis holds rate-limit counters, circuit-breaker state, sticky routing, budgets and the response cache; Postgres holds everything else. The startup error names the one that's missing and the command that starts it.

To look at the dashboard alone, with no database and no gateway, serve it directly and click Preview demo:

npx serve frontend

Opening frontend/index.html from your filesystem will not work — browsers refuse to load ES modules from a file:// origin.

---

Connect your tools

Alayra Nexus speaks both the OpenAI API (/v1/chat/completions) and the Anthropic Messages API (/v1/messages), so almost any tool that lets you set a custom base URL works — including Claude Code. You only need three values:

• Base URL: http://<your-host>:3000/v1
• API key: a team key from the dashboard (sent as Authorization: Bearer <key>, or x-api-key: <key>)
• Model: alayra-nexus-1

[!NOTE] Cursor (and some other cloud tools) route requests through their own servers, so they cannot reach http://localhost:3000 — they need a publicly reachable HTTPS base URL. Local tools such as Cline, Continue.dev, and Claude Code call your gateway directly and work against localhost. This is a Cursor constraint, not a Nexus one — LiteLLM has the same requirement.

Claude Code

Claude Code speaks the Anthropic Messages API. Point it at the gateway:

export ANTHROPIC_BASE_URL="http://<your-host>:3000"
export ANTHROPIC_AUTH_TOKEN="<your-team-key>"
claude

Requests route through the same pool, failover, budgets, and analytics as everything else. On startup Claude Code reads GET /v1/models to populate its model picker.

Cursor

Settings → Models → enable OpenAI API Key, paste your team key, tick Override OpenAI Base URL and set it to `http://:3000/v1