Aurora - The Fastest AI Gateway

A fork focused on multi-IP setups & API integration

One API for every AI provider. Self-hosted. No vendor lock-in.

14 provider types • OpenAI & Anthropic compatible • Go • Apache 2.0 • Built for raw speed

Documentation

Full guides, written for this fork.

Quick deploy:

docker pull entbtw/aurora:latest
docker run -d --name aurora -p 8080:8080 -e AURORA_MASTER_KEY="your-secure-key" entbtw/aurora:latest

See Deployment for production (persistent config & state, network_mode: host for multi-IP).

What's new in this fork

Dashboard-driven operations — no more .env-only workflows for the things you change most. Everything below is managed from the UI and persists across restarts.

Warning: This fork contains custom features not present in the original aurorallm/aurora. Some features (dashboard redesign, session hub, UI enhancements) were vibecoded and may contain rough edges. Designed for advanced API integration workflows — use at your own discretion.

• Redesigned dashboard — full Catppuccin theme, mobile-responsive, compact/touch-friendly layout, clean auth/logo/sidebar, shared SearchInput fix in audit logs & usage.
• Provider CRUD — manage providers from the UI (base URL, API key, models, type). Per-provider bind_ip, pool_only, runtime enable/disable, live rename, duplicate protection. Status shows if a key is set without exposing it. OpenRouter list is now an allowlist; vLLM type added to the dashboard (was .env-only).
• Custom User-Agent — set a custom User-Agent header per provider for upstream attribution (e.g. OpenRouter recommends this for credits).
• Auto-fetch models toggle — disable automatic /models discovery per provider to use only explicitly configured model lists.
• Fallback chains — edit rules in the UI, applied at runtime; callable by name, exposed in /v1/models, order preserved on toggle/edit/delete.
• Provider pools — create/edit/delete with member selection and weighted / round-robin strategies; health-aware members, pool_only models, live registry rebuild.
• Response headers — configurable X-Actual-Provider / X-Actual-Model / X-Requested / X-Fallback-Chain, per-header toggles, custom headers, success/error/always modes, emitted on 429/401.
• Persistence — state saved to configs/provider-overrides.json, configs/pool-overrides.json, configs/fallback.json (env-overridable); Docker volumes keep it across recreation.
• Session Hub — header transformation engine with per-provider/pool session mapping, inbound→outbound unique ID generation, disk persistence with live toggle, and pool-aware binding via UI (see Session Hub below).

What Aurora Does

Aurora sits between your app and LLM providers. Your app sends requests using the standard OpenAI or Anthropic SDK — Aurora routes them to whichever provider you've configured. One format handles everything — you dont need to worry about provider-specific formats.

# Before: hardcoded provider
client = OpenAI(base_url="https://api.openai.com/v1", api_key="sk-...")

# After: Aurora Gateway
client = OpenAI(base_url="http://localhost:8080/v1", api_key="your-aurora-key")

No SDK changes. No format changes. Just swap the base_url.

Features

Routing & Providers

• 14 provider types — OpenAI, Anthropic, Gemini, Groq, DeepSeek, OpenRouter, xAI, Z.ai, MiniMax, Azure OpenAI, Oracle, Ollama, vLLM, Jina
• Auto-discovery — set an API key as an env var, restart, provider + all its models appear automatically
• Auto-fetch toggle — disable per-provider model auto-discovery to use only explicitly configured model lists
• Custom User-Agent — set a custom User-Agent header per provider for upstream attribution or branding
• Provider pools — group multiple keys/endpoints, load-balance with round-robin or weighted distribution, health-aware failover
• Model aliases — rename/remap any model to a custom identifier across the entire gateway
• Model overrides — enable or disable specific models per user path, persisted via dashboard or user_pricing.yaml
• Fallback — automatic failover on 5xx/429, or manual rules (from config or external JSON) mapping failed provider+model to backups
• Resilience — exponential backoff with jitter, circuit breaker per provider (closed → open → half-open), per-provider override of global retry/circuit-breaker settings
• Multiple instances — run OPENAI_EAST_API_KEY and OPENAI_WEST_API_KEY as separate providers
• Custom base URLs — override any provider's endpoint (corporate proxies, regional endpoints)
• Passthrough — /p/{provider}/* for full upstream API access (not just chat completions); filter which provider types get passthrough routes
• Config-driven workflows — per-request routing, caching, guardrail, audit, usage, budget, and fallback behavior controlled by persisted workflow documents

API Surface

• OpenAI-compatible — /v1/chat/completions, /v1/embeddings, /v1/rerank, /v1/models, /v1/files, /v1/batches
• Responses API — /v1/responses with full CRUD, cancel, input items, compact
• Anthropic-compatible — /v1/messages, /v1/messages/count_tokens (native Anthropic wire format); optional dedicated ingress at /v1/messages
• Streaming — SSE streaming for all endpoints, preserved end-to-end
• Keep-only-aliases mode — hide raw provider models from /v1/models and expose only aliased names
• Configured provider models mode — fallback (add listed models to auto-discovered) or allowlist (only serve explicitly listed models)

Caching

• Exact cache — SHA-256 hash match on request, Redis-backed, async writes
• Semantic cache — vector similarity with configurable threshold, supports Qdrant, pgvector, Pinecone, Weaviate
• Prompt cache — forwards cache_control to Anthropic/OpenAI/Gemini native prompt caching; configurable modes (auto, manual, off), component toggles, and minimum token threshold
• Model registry cache — local filesystem + Redis, offline-safe; supports vendored JSON snapshots with per-field user pricing overrides

Security & Guardrails

• Master key — top-level gateway auth
• Managed API keys — scoped, rate-limited, per-key model authorization, usage stats
• Rate limiting — per-key rate limiting backed by in-memory or Redis
• PII redaction — email, phone, SSN, credit card detection and masking
• Prompt injection blocking — detects and blocks injection attempts
• System prompt protection — inject, override, or decorate system prompts
• Regex blocking — custom pattern matching with block or sanitize actions
• Length limits — character/token count enforcement on requests
• LLM-based altering — guardrail that rewrites message content via an auxiliary LLM call (anonymization, custom prompts)
• Guardrail direction & ordering — run before provider dispatch (input), after response (output), or both; same-order guardrails run in parallel
• Batch guardrails — apply configured guardrails to inline items in /v1/batches requests

Observability

• Audit logging — full request/response capture, buffered writes, configurable retention (body/header logging, buffer size, flush interval), live SSE stream
• Usage analytics — per-model token counting, cost tracking, daily aggregation by model/user-path, pricing recalculation action
• Prometheus metrics — aurora_requests_total, aurora_request_duration_seconds, aurora_requests_in_flight, plus gateway phase timing
• Admin dashboard — React SPA built into the Go binary (Catppuccin, fully mobile-responsive): full provider CRUD, fallback chains, provider pools, response-header config, plus models, aliases, guardrails, cache, usage, audit, auth keys, workflows, console, playground
• pprof endpoints — Go runtime profiling at /debug/pprof/* (heap, goroutine, mutex, block, threadcreate)
• Structured logging — configurable format (JSON/text), level (debug/info/warn/error), source info, service metadata

Cost Control

• Token saver — policy-driven output compression (profiles: concise, caveman, ultra, wenyan); scoped to specific models/providers via include/exclude filters; configurable on-error behavior (allow/block)
• Pricing management — per-model pricing overrides, recalculation, import/export
• Usage budgets — per-key usage tracking and limits, per-request budget enforcement via workflow feature flags

Developer Experience

• Single binary — docker pull entbtw/aurora (this fork) or run from source with Go
• CLI — run from source, or drive via config files + the dashboard
• CLI tools API — admin REST endpoints for CLI configuration sync, gated separately
• Swagger docs — /swagger/index.html (build-tag gated)
• Config profiles — pre-built configs for local, local-power, and team deployments
• 3-layer config — code defaults → config.yaml → env vars (env vars win)

Session Hub

Header transformation engine for API integration workflows where upstream services require unique client identifiers per account.

• Per-provider/pool binding — attach transformation rules to specific providers, pools, fallbacks, or all targets (*)
• 6 header modes — map (stable inbound→outbound per provider), generate (fresh ID each request), passthrough, static, random_from_list, remove
• Pool-aware — rules bound to a pool automatically apply to all member providers
• Inbound header forwarding — client session headers are forwarded through the translation layer so map mode works even when the provider path drops arbitrary inbound headers
• Lock-free hot path — Apply() is a single atomic map read; benchmarked at ~495 ns/op (negligible)
• Persistent or in-memory — toggled live via API or dashboard (PUT /admin/api/v1/sessionhub/storage {"mode":"disk"})
• Dashboard UI — Settings → Session Hub: binding overview from live server targets (pools/providers), add rule by selecting target, live mapping viewer, storage toggle

How it works

1. Client sends request to Aurora (e.g. with x-opencode-session: ses_abc123)
2. Gateway intercepts the inbound session header and stores it in request context
3. Request is routed to a pool member (e.g. opencode-zen → vllm-zen-backup)
4. Provider's outbound headerSetter fires: session hub applies rules for that provider/pool
5. map mode: inbound ses_abc123 → unique outbound ses_xR4f8k2m... per provider (stable, deduplicated)
6. generate mode: fresh random ses_... per request (always unique)
7. Additional headers (x-opencode-client, user-agent) are injected per rule
8. Outbound request goes to upstream with transformed headers

Config

Rules are persisted in configs/session-hub-rules.yaml (gitignored). Live edits via API or dashboard are auto-saved.

enabled: true
mapping_storage: disk          # "memory" or "disk"
providers:
  opencode-zen:                # matches pool name or provider name
    enabled: true
    headers:
      - name: x-opencode-session
        mode: map              # stable inbound→outbound per provider
        prefix: "ses_"
        length: 28
      - name: x-opencode-client
        mode: static
        value: cli
      - name: user-agent
        mode: static
        value: "opencode/1.18.26 ai-sdk/openai/2.0.0 runtime/bun/1.0.0"

API

Header modes

Quick Start

Start routing AI traffic in 60 seconds.

Recommended — Docker (published image):

docker pull entbtw/aurora:latest
docker run -d --name aurora -p 8080:8080 -e AURORA_MASTER_KEY="your-secure-key" entbtw/aurora:latest

Full examples below. For production (persistent state, multi-IP) see the Deployment guide.

The quickest way to configure providers from scratch is the dashboard: http://localhost:8080/admin/dashboard → Providers → Add provider. For env-var driven setups:

Option A — inline env vars

AURORA_MASTER_KEY=your-secure-key \
  OPENAI_API_KEY=sk-... \
  ANTHROPIC_API_KEY=sk-ant-... \
  GEMINI_API_KEY=... \
  GROQ_API_KEY=gsk_... \
  DEEPSEEK_API_KEY=... \
  OPENROUTER_API_KEY=... \
  XAI_API_KEY=... \
  ZAI_API_KEY=... \
  MINIMAX_API_KEY=... \
  AZURE_API_KEY=... \
  ORACLE_API_KEY=... \
  OLLAMA_API_KEY=... \
  VLLM_API_KEY=... \
  JINA_API_KEY=... \
  LOGGING_ENABLED=true \
  METRICS_ENABLED=true \
  GUARDRAILS_ENABLED=true \
  TOKEN_SAVER_ENABLED=true \
  aurora

$env:AURORA_MASTER_KEY="your-secure-key"; `
$env:OPENAI_API_KEY="sk-..."; `
$env:ANTHROPIC_API_KEY="sk-ant-..."; `
$env:GEMINI_API_KEY="..."; `
$env:GROQ_API_KEY="gsk_..."; `
$env:DEEPSEEK_API_KEY="..."; `
$env:OPENROUTER_API_KEY="..."; `
$env:XAI_API_KEY="..."; `
$env:ZAI_API_KEY="..."; `
$env:MINIMAX_API_KEY="..."; `
$env:AZURE_API_KEY="..."; `
$env:ORACLE_API_KEY="..."; `
$env:OLLAMA_API_KEY="..."; `
$env:VLLM_API_KEY="..."; `
$env:JINA_API_KEY="..."; `
$env:LOGGING_ENABLED="true"; `
$env:METRICS_ENABLED="true"; `
$env:GUARDRAILS_ENABLED="true"; `
$env:TOKEN_SAVER_ENABLED="true"; `
aurora

set AURORA_MASTER_KEY=your-secure-key ^
  && set OPENAI_API_KEY=sk-... ^
  && set ANTHROPIC_API_KEY=sk-ant-... ^
  && set GEMINI_API_KEY=... ^
  && set GROQ_API_KEY=gsk_... ^
  && set DEEPSEEK_API_KEY=... ^
  && set OPENROUTER_API_KEY=... ^
  && set XAI_API_KEY=... ^
  && set ZAI_API_KEY=... ^
  && set MINIMAX_API_KEY=... ^
  && set AZURE_API_KEY=... ^
  && set ORACLE_API_KEY=... ^
  && set OLLAMA_API_KEY=... ^
  && set VLLM_API_KEY=... ^
  && set JINA_API_KEY=... ^
  && set LOGGING_ENABLED=true ^
  && set METRICS_ENABLED=true ^
  && set GUARDRAILS_ENABLED=true ^
  && set TOKEN_SAVER_ENABLED=true ^
  && aurora

Option B — Docker

Published image: entbtw/aurora · tags latest, v1.0.0.

docker pull entbtw/aurora:latest

docker run -d --name aurora -p 8080:8080 \
  -e AURORA_MASTER_KEY="your-secure-key" \
  -e OPENAI_API_KEY="sk-..." \
  -e ANTHROPIC_API_KEY="sk-ant-..." \
  -e GEMINI_API_KEY="..." \
  -e GROQ_API_KEY="gsk_..." \
  -e DEEPSEEK_API_KEY="..." \
  -e OPENROUTER_API_KEY="..." \
  -e XAI_API_KEY="..." \
  -e ZAI_API_KEY="..." \
  -e MINIMAX_API_KEY="..." \
  -e AZURE_API_KEY="..." \
  -e ORACLE_API_KEY="..." \
  -e OLLAMA_API_KEY="..." \
  -e VLLM_API_KEY="..." \
  -e JINA_API_KEY="..." \
  -e LOGGING_ENABLED=true \
  -e METRICS_ENABLED=true \
  -e GUARDRAILS_ENABLED=true \
  -e TOKEN_SAVER_ENABLED=true \
  entbtw/aurora:latest

For production setups (persistent config/state, multi-IP host networking) see the Deployment guide.

Verify it's alive

After starting, confirm the gateway is up and the dashboard loads:

# Health check
curl -s http://localhost:8080/health

# Dashboard
open http://localhost:8080/admin/dashboard

# Session Hub status (should show storage_mode: disk or memory)
curl -s http://localhost:8080/admin/api/v1/sessionhub/status \
  -H "Authorization: Bearer your-master-key"

If health returns {"status":"ok"} — the gateway is running. Now add a provider via the dashboard or env vars, then test a model call:

Test your gateway

# OpenAI format
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-master-key" \
  -d '{"model":"groq/llama-4-scout-17b-16e-instruct","messages":[{"role":"user","content":"Hello!"}]}'

# Anthropic format with streaming
curl http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-master-key" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "anthropic/claude-sonnet-5-20260630",
    "max_tokens": 1024,
    "stream": true,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

# Embeddings
curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-master-key" \
  -d '{"model":"openai/text-embedding-3-small","input":"Hello world"}'

# Reranking (Jina)
curl http://localhost:8080/v1/rerank \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-master-key" \
  -d '{"model":"jina/jina-reranker-v2-base-multilingual","query":"test","documents":["doc1","doc2"]}'

Dashboard: http://localhost:8080/admin/dashboard

Docs (this fork): Getting Started · Deployment · Session Hub · Docker image

Source: github.com/entitybtw/aurora · Image: hub.docker.com/r/entbtw/aurora

Base project (upstream): aurorallm/aurora · aurorallm.online/docs

Providers

Providers are auto-discovered from environment variables. Set any provider's _API_KEY and restart — the provider and its default models appear automatically.

Security note: The env var names below are documentation references. Actual secrets go into your .env file (in .gitignore) or your deployment secrets manager — never commit them.

Per-provider configuration

Every provider supports *_MODELS to override auto-discovered models:

OPENAI_MODELS=gpt-5.6-sol,gpt-5.6-terra,gpt-5.6-luna

Custom base URL:

OPENAI_BASE_URL=https://my-corp-openai-proxy.example.com/v1

YAML provider config supports additional options:

providers:
  openai:
    type: openai
    api_key: "${OPENAI_API_KEY}"
    base_url: "https://api.openai.com/v1"
    # Custom User-Agent header for upstream attribution
    user_agent: "MyApp/1.0"
    # Disable auto-fetching models from /models endpoint (use only configured list)
    auto_fetch_models: false
    models:
      - gpt-4o
      - gpt-4o-mini

Multiple instances of the same provider (underscores become hyphens in the provider name):

OPENAI_EAST_API_KEY=sk-...     # → provider: openai-east
OPENAI_WEST_API_KEY=sk-...     # → provider: openai-west

Azure requires API version:

AZURE_API_VERSION=2024-10-21

OpenRouter extras:

OPENROUTER_SITE_URL=https://github.com/entitybtw/aurora
OPENROUTER_APP_NAME=Aurora Gateway

Configuration

The gateway loads settings in this priority order (later wins):

code defaults → config.yaml → .env / environment variables

Generated by aurora init, every section of config.yaml is documented inline:

Config profiles

Pre-built configs in configs/editions/:

export AURORA_CONFIG_PATH=configs/editions/oss.team.example.yaml

Complete env var reference

CLI Reference

Run the built binary directly (from source: go build -o aurora ./apps/aurora, then ./aurora). The npm iaurora wrapper is the upstream package and isn't republished by this fork.

Repository Structure

aurora/
├── apps/              # Application entrypoints
├── internal/          # Core packages (providers, gateway, storage, guardrails, etc.)
├── dashboard-ui/      # React admin dashboard (Vite)
├── configs/           # Configuration profiles and examples
├── documentation/     # Markdown docs (Getting Started, Deployment, Session Hub, Docker)
├── docs-assets/       # Images, models.json, assets
├── monitoring/        # Prometheus + Grafana configs
├── bench-results/     # Benchmark data
├── release/           # Release scripts
└── scripts/           # Build and utility scripts

License

This project is licensed under the Apache 2.0 License — see the LICENSE file for details.

Community fork of Aurora. Session Hub features and multi-account integration built by entitybtw. The upstream project is built by the Aurora team.