Alayra-Nexus

The gateway builds from the repo and serves the dashboard from a single service, so a managed deploy is three plugins and four variables:

1. New Project → Deploy from GitHub repo → pick this repository. Railway builds the image.
2. Add the PostgreSQL and Redis plugins to the project.
3. On the gateway service → Variables, set (use each plugin's private connection URL):
   • DATABASE_URL = ${{Postgres.DATABASE_URL}}
   • REDIS_URL = ${{Redis.REDIS_URL}}
   • MASTER_ENCRYPTION_KEY = 64 hex chars — generate fresh, never reuse: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
   • ADMIN_PASSWORD = a strong install secret (claims the first owner account)
4. Settings → Networking → Generate Domain for a public https://…up.railway.app URL.

Railway's proxy sets X-Forwarded-Proto, so the dashboard's Connect page prints the correct https:// base URL with no extra config. Behind a proxy that doesn't, pin it with PUBLIC_URL. The container runs its own migrations on boot; open the domain and it greets you with the owner-account setup screen.

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

</details>

# 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.

The dashboard is a Vite + Preact app in web/, built to static assets that the gateway serves at / — there is no separate web server to run. To work on the dashboard with hot reload, cd web && npm run dev (it proxies API calls to a gateway running on :3000).

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://<your-host>:3000/v1. Add a custom model named alayra-nexus-1.

Cline / Roo Code (VS Code)

API Provider → OpenAI Compatible → Base URL http://<your-host>:3000/v1, API Key = your team key, Model ID alayra-nexus-1.

Continue.dev

{
  "models": [
    {
      "title": "Alayra Nexus",
      "provider": "openai",
      "model": "alayra-nexus-1",
      "apiBase": "http://<your-host>:3000/v1",
      "apiKey": "<your-team-key>"
    }
  ]
}

OpenAI SDK — Python

from openai import OpenAI

client = OpenAI(base_url="http://<your-host>:3000/v1", api_key="<your-team-key>")
resp = client.chat.completions.create(
    model="alayra-nexus-1",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

OpenAI SDK — Node

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://<your-host>:3000/v1",
  apiKey: "<your-team-key>",
});
const resp = await client.chat.completions.create({
  model: "alayra-nexus-1",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(resp.choices[0].message.content);

curl

curl http://<your-host>:3000/v1/chat/completions \
  -H "Authorization: Bearer <your-team-key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"alayra-nexus-1","messages":[{"role":"user","content":"Hello"}]}'

Streaming works everywhere — add "stream": true (or the client's streaming flag). Running Nexus behind TLS? Use your https://…/v1 URL instead.

Environment Variables

[!IMPORTANT] Generate MASTER_ENCRYPTION_KEY with:

hljs language-bash

Copy

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

This key encrypts every provider API key stored in your database. Keep it secret. Keep a backup. Never reuse it across deployments.

Rate limits, explained

Alayra Nexus has two independent limits, and it's important not to confuse them:

Your gateway's real ceiling is the sum of your active keys' RPM limits — pool more keys and that ceiling rises. The abuse guard should always sit comfortably above that number, never below it.

[!IMPORTANT] Size ABUSE_RATE_LIMIT_MAX above the busiest single credential's expected rate, not your whole pool's. Because the guard is keyed per credential (each team key gets its own bucket), a fleet of team keys can collectively far exceed this number — but if you route most traffic through one key, give that key headroom. The default of 12000 per minute (200 req/s) suits most self-hosters; raise it if a single key legitimately drives more.

The guard is Redis-backed, so the limit stays correct even when you run multiple Nexus replicas behind a load balancer, and it fails open — if Redis is briefly unreachable, requests are allowed through rather than blocked.

Resilience & routing

Teams & budgets

Group your scoped access keys into teams, and give each team a USD budget cap per day, week, or month. Enforcement happens on the admission path — before a request ever reaches a provider:

• A key that belongs to a team over its budget gets 429 with the current spend, the cap, and a Retry-After for when the window resets (UTC).
• A suspended team's keys get 403 immediately.
• Spend is tracked in Redis and seeded from your real usage history, so setting a cap mid-month starts from what the team has actually spent — and budgets survive a Redis restart.
• Keys without a team (and teams without a cap) behave exactly as before — nothing changes until you opt in.

[!NOTE] Cost is only knowable after a response completes (streaming), so enforcement is check-then-spend: requests already in flight when the cap is crossed can overshoot it by their own cost. That's the standard trade for budget caps on a streaming gateway.

Manage teams from the dashboard's Teams tab — create and budget teams, issue and assign scoped access keys, and read per-team usage — or drive the same operations over the admin API (/admin/teams).

BYOK — bring your own key

A provider key can be owned by a team instead of living in the shared pool. An owned key serves only that team's traffic; nobody else can route through it. Set the owner when you add the key (Pools → + Key → Owner), or pass ownerTeamId to POST /admin/providers/:providerId/keys.

Routing then works in two passes:

1. The team's own keys first, in the usual tier order with LRU within a tier.
2. The shared pool, but only if the team allows it.

Per-team, byokFallback decides what happens when a team's own keys are all rate-limited, cooling, or banned:

A BYOK key is not a parallel proxy — it is a scoped pool. Owned keys flow through the exact same admission control, circuit breaker, guardrails, SSRF checks, and analytics pipeline as pooled keys. There is one request path.

Two guarantees worth stating explicitly:

• A caller with no team can never be routed through an owned key, even when the shared pool is completely exhausted.
• The response cache is partitioned by owner. A response produced by one team's private key is never replayed to another team or to the shared pool, so an isolated team only ever sees responses its own keys paid for.

BYOK spend is still costed, attributed, and counted against the team's budget cap — set budgetUsd: null for a team that funds its own keys and shouldn't be capped.

[!WARNING] Deleting a team deletes its owned provider keys along with it. This is deliberate: releasing a private credential into the shared pool would let every other caller route through it. The team's access keys survive, losing only their budget cap.

Watch adoption with the nexus_byok_requests_total{result} metric — a sustained fallback rate means a team is under-provisioned on its own credentials.

API Reference

POST /v1/chat/completions   OpenAI Chat Completions (streaming + non-streaming)
POST /v1/messages           Anthropic Messages (streaming + non-streaming)
POST /v1/embeddings         OpenAI Embeddings — for RAG / vector search
POST /v1/completions        OpenAI legacy completions — fill-in-the-middle / autocomplete
POST /v1/images/generations OpenAI Images — billed per image, not per token
POST /v1/audio/speech       OpenAI TTS — returns audio, billed per character
POST /v1/audio/transcriptions  OpenAI STT — multipart upload, billed per file
GET  /v1/models             Model discovery (OpenAI + Anthropic shape)

curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-team-key>" \
  -d '{
    "model": "alayra-nexus-1",
    "messages": [{ "role": "user", "content": "Hello" }],
    "stream": true
  }'

Dashboard

The built-in web dashboard (served at /, a Vite + Preact app) gives you full operational control — no CLI required for day-to-day work:

_{The Health tab — the gateway's own vitals: process, Redis, and PostgreSQL latency, cache-hit rates, and the readiness checks your load balancer sees.}

• Overview — live gateway telemetry: request/token/cost trends, active keys and models, top teams, and recent admin activity by name
• Nexus — provider pools and the model registry: per-key RPM utilization meters, add/test/ban keys, and each model's tier, capability flags, context window, and per-1M token pricing
• Connect — the base URL (verified against your browser's own address bar), the API-key hint with one-click rotation, endpoint reference, and filled-in quick-start snippets
• Analytics — request and token trend charts, stacked model breakdown, cost area chart, input/output comparison, team leaderboard, response-cache savings, CSV export, and a custom date-range picker
• Teams — teams with budgets and routing tier, scoped access keys, and per-team usage stats
• Enterprise — operator branding / white-labelling and per-company controls
• Security — your sign-in security (password, TOTP two-factor with QR enrolment, active sessions) and admin API tokens
• Caching — the optional exact-match response cache: toggle, TTL, and live hit-rate
• Health — the gateway's own vitals: process, Redis, and PostgreSQL latency and readiness checks
• Logs — the read-only audit trail: every state-changing action, who did it, and the result
• Settings — system configuration: routing weights, guardrails, network/SSRF policy, notifications, and compliance/retention
• Admin — people and roles (owner / admin / viewer), invites, single sign-on, and the factory reset

Observability

A Prometheus-compatible /metrics endpoint exposes the gateway's operational shape, so it drops straight into an existing ops stack.

• Metrics: request rate and duration (by outcome and tier), upstream time-to-first-byte, input/output tokens, prompt-cache (sticky) hit rate, per-provider request and error rates (rate-limit / auth / server / timeout), pool utilization (active / cooling / banned keys), plus standard Node process metrics (CPU, memory, event-loop lag, GC).
• Auth: /metrics is not world-readable like /health. Scrape it with a bearer token — set a dedicated METRICS_TOKEN (recommended), or it falls back to ADMIN_PASSWORD. It is exempt from the abuse guard's rate limit but never from auth.

# prometheus.yml
scrape_configs:
  - job_name: alayra-nexus
    authorization:
      credentials: <your METRICS_TOKEN>
    static_configs:
      - targets: ['your-host:3000']

OTEL_EXPORTER_OTLP_ENDPOINT=http://your-collector:4318 \
node --require @opentelemetry/auto-instrumentations-node/register dist/server.js

Security Model

Accounts and roles

The gateway has accounts. Everyone who administers it signs in as themselves, with their own email, password and second factor — so the audit trail records who did each thing, and one person can be removed without disturbing anyone else.

First run. A fresh gateway has no accounts, so the dashboard opens on a setup screen. It asks for ADMIN_PASSWORD from your server's environment: that is the proof you are the person who installed this gateway rather than the first stranger to find the port. You create the owner account, and are handed a recovery key — shown once, and the way back if you forget your password.

After that, ADMIN_PASSWORD is refused as a sign-in. It keeps two jobs: claiming a fresh gateway, and authorising a full reset. Everything else goes through an account.

[!NOTE] Upgrading changes nothing until you choose. On a gateway that has not been claimed, sign-in behaves exactly as it did before: ADMIN_PASSWORD, and the second factor if you enrolled one. When you claim, your existing authenticator and unused recovery codes carry over to your new account — nothing to set up again.

Three roles.

Invites are links, not emails: an owner creates one and hands it over however they like (email delivery is optional in this gateway, so an email-only invite would be a flow that silently never works for most deployments). Each works once, expires after 7 days, and the invitee chooses their own password — the owner never learns it.

Removing someone revokes the admin API tokens they created and kills their sessions on the next request. What they did stays in the audit trail under their name: a record of who did what has to outlive the account.

Single sign-on provisions an account from the email claim on first sign-in. The claim's role applies only to a new account — for one that already exists, what an owner set in the Users tab wins, so an identity provider's groups cannot silently re-promote someone.

Locked out? Your recovery key resets a forgotten password. Your recovery codes stand in for a lost authenticator. Lose both, and the documented way back is a full reset of the gateway, which erases everything in it.

</details>

# 1. Enrol — returns a secret and an otpauth:// URI for your authenticator app
curl -X POST -H "Authorization: Bearer $TOKEN" http://localhost:3000/admin/auth/totp/enrol

# 2. Confirm with a code from the app — returns 10 single-use recovery codes
curl -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"code":"123456"}' http://localhost:3000/admin/auth/totp/confirm

// each rule: name, pattern (regex), action (block|redact),
// appliesTo (input|output|both, default both), optional replacement
[
  { "name": "email", "pattern": "[a-z0-9._%+-]+@[a-z0-9.-]+\\.[a-z]{2,}", "action": "redact", "replacement": "[REDACTED_EMAIL]" },
  { "name": "injection", "pattern": "ignore (?:all |the )?previous instructions", "action": "block", "appliesTo": "input" }
]

# Development
npm run dev

# Type check
npx tsc --noEmit

# Unit tests (backend, then dashboard)
npm test
cd web && npm test

# End-to-end: builds both packages, then drives the COMPILED gateway against a real
# Postgres + Redis (docker compose up -d postgres redis) and a real browser. Uses its
# own databases and Redis DBs — your local gateway's data is never touched.
cd e2e && npm install && npx playwright install chromium && npx playwright test

# Schema changes
npx prisma migrate dev --name your_migration_name