Aurora Gateway

One gateway. Every provider. Open source.

Route AI traffic through a single OpenAI- and Anthropic-compatible API. Self-hosted. No vendor lock-in. Full source visibility.

CLI reference

aurora [flags]
aurora init [flags]
aurora update
aurora uninstall
aurora models <command> [flags]

| Command | Description | |---------|-------------| | aurora | Start the gateway server | | aurora init | Bootstrap config.yaml, .env, and data/ directory | | aurora update | Self-update to the latest npm version | | aurora uninstall | Remove aurora from your system | | aurora models sync | Download upstream model registry to local file | | aurora models diff | Show pricing diff between upstream and local snapshot | | aurora models show | Print effective pricing for a model |

| Flag | Description | |------|-------------| | -version | Print version information | | -help | Show full configuration reference and env vars | | -help-json | Dump environment variable schema as JSON |

| aurora init flag | Description | |-------------------|-------------| | -dir <path> | Target directory (default: current directory) | | -force | Overwrite existing files | | -with-models | Also download the model registry |

Quick start

npm (recommended)

# Install globally
npm install -g iaurora

# Scaffold a new project
mkdir my-gateway && cd my-gateway
aurora init

# Edit .env with your API key(s)
# Uncomment one of the provider keys:
#   GROQ_API_KEY=gsk_...
#   OPENAI_API_KEY=sk-...
#   etc.

# Start the gateway
aurora

The gateway boots on http://localhost:8080 with every free feature enabled. Open the dashboard at http://localhost:8080/admin/dashboard.

Docker

docker run --rm -p 8080:8080 \
  -e AURORA_MASTER_KEY="your-secure-key" \
  -e GROQ_API_KEY="gsk_..." \
  gurveeer/Aurora

For configurable deployments, mount your config.yaml and .env:

docker run --rm -p 8080:8080 \
  -v /path/to/config.yaml:/app/config.yaml \
  -v /path/to/.env:/app/.env \
  -e AURORA_CONFIG_PATH=/app/config.yaml \
  gurveeer/Aurora

From source

git clone https://github.com/gurveeer/Aurora.git && cd Aurora

# Build the dashboard UI (one-time)
pnpm --dir dashboard-ui install && pnpm --dir dashboard-ui run build

# Build the binary
go build -o bin/aurora ./apps/aurora

# Use the CLI's init command
./bin/aurora init -dir ./my-gateway
cd ./my-gateway

# Edit .env with keys, then start
../bin/aurora

What aurora init generates

my-gateway/
├── config.yaml              # Full config (all OSS features ON)
├── .env                     # Every env var documented
├── configs/
│   └── fallback.json        # Fallback routing rules (example)
└── data/
    └── user_pricing.yaml    # Model pricing overrides

All 15 config sections are active — nothing needs to be uncommented for the gateway to work. The generated files serve as living documentation: every option is listed with a description and its default value. Commented-out blocks show advanced features that need external infrastructure (Redis, PostgreSQL, vector stores).

Feature overview

| Feature | What it does | How to use | |---------|-------------|------------| | HTTP Gateway | OpenAI-compatible /v1/chat/completions, /v1/embeddings, /v1/models, etc. | Send any OpenAI SDK/client at it | | Admin Dashboard | Web UI for managing providers, API keys, models, combos | http://localhost:8080/admin/dashboard | | Model Discovery | Detects providers and their models from env vars automatically | Just set GROQ_API_KEY — models appear in /v1/models | | Passthrough Routes | Call provider APIs directly through the gateway | POST /p/groq/v1/chat/completions | | Anthropic Ingress | Native Anthropic-format /v1/messages endpoint | Send Anthropic SDK traffic directly | | Audit Logging | Records every request/response with retention | View in dashboard → Audit Logs | | Usage Tracking | Token counts, cost per request, historical analytics | View in dashboard → Usage | | Prometheus Metrics | Go runtime + request metrics | GET /metrics | | Guardrails | Content safety filters (system prompt, regex, PII redaction) | Configure in dashboard or guardrails in YAML | | Token Saver | Compresses responses to cut token spend | Set TOKEN_SAVER_ENABLED=true (already on by default) | | Swagger UI | Interactive API docs | http://localhost:8080/swagger/index.html | | pprof | Go performance profiling | http://localhost:8080/debug/pprof/ | | Fallback Routing | Auto-failover when a provider returns an error | Configured in fallback.json | | Resilience | Retries transient failures + circuit breaker | On by default (3 retries, 30s backoff) | | Combo Models | Send one prompt to multiple models, get all responses | Create via dashboard or API | | CLI Tools | Admin configuration via CLI commands | Enable apply_enabled for write access | | SQLite Storage | Zero-config embedded database for all persistence | Default — no setup needed |

Your first request

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(grep AURORA_MASTER_KEY .env | cut -d= -f2)" \
  -d '{
    "model": "groq/llama-3.3-70b-versatile",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Or using the admin dashboard at http://localhost:8080/admin/dashboard to test models interactively.

Providers

Providers are auto-discovered from environment variables. Set any of these keys in your .env and restart — the provider and its models appear automatically.

| Provider | Env var | Default models | |----------|---------|----------------| | OpenAI | OPENAI_API_KEY | gpt-4o, gpt-4o-mini | | Anthropic | ANTHROPIC_API_KEY | claude-sonnet-4, claude-opus-4 | | Google Gemini | GEMINI_API_KEY | gemini-2.5-pro, gemini-2.5-flash | | Groq | GROQ_API_KEY | llama-3.3-70b, qwen3-32b, whisper | | DeepSeek | DEEPSEEK_API_KEY | deepseek-chat, deepseek-reasoner | | OpenRouter | OPENROUTER_API_KEY | 300+ models | | xAI | XAI_API_KEY | grok-3, grok-3-mini | | Z.ai | ZAI_API_KEY | glm-4.5 | | MiniMax | MINIMAX_API_KEY | minimax-m1 | | Azure OpenAI | AZURE_API_KEY + AZURE_BASE_URL | Your deployments | | Oracle | ORACLE_API_KEY + ORACLE_BASE_URL | cohere.command-r-plus | | Ollama | OLLAMA_BASE_URL | Any local model | | vLLM | VLLM_BASE_URL | Any served model |

Custom base URL? Set OPENAI_BASE_URL, GROQ_BASE_URL, etc. in .env.

Multiple instances of the same provider? Use suffix notation: OPENAI_EAST_API_KEY, OPENAI_EAST_BASE_URL, OPENAI_WEST_API_KEY, etc.

Using the admin dashboard

Open http://localhost:8080/admin/dashboard to:

• Manage API keys — Create and revoke gateway-level API keys with usage limits
• Toggle models — Enable/disable specific models per provider
• Override pricing — Set custom input/output token costs per model
• View analytics — Request volume, token usage, latency, error rates
• Browse audit logs — Every request, who made it, what model, how many tokens
• Configure guardrails — Add content safety rules
• Create combos — Multi-model comparison and fallback groups
• Monitor cache — Hit rates for exact and semantic caches

Combo models

Combos let you send one prompt to multiple models simultaneously. The primary model responds; if it fails, fallback models are tried automatically.

Create via dashboard

1. Open http://localhost:8080/admin/dashboard
2. Go to Combos → Add Combo
3. Name it, select 2+ models, save

Create via API

curl -X POST http://localhost:8080/admin/api/v1/combos \
  -H "Authorization: Bearer $AURORA_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-combo","models":["groq/llama-3.3-70b-versatile","groq/qwen/qwen3-32b"],"enabled":true}'

Use a combo

curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer $AURORA_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"my-combo","messages":[{"role":"user","content":"Hello!"}]}'

Configuration

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

code defaults → config.yaml → .env / env vars

config.yaml

Generated by aurora init. Every section is documented inline:

| Section | What it controls | |---------|-----------------| | server | Port, base path, master key, passthrough, Anthropic ingress | | admin | Dashboard API and UI | | models | Discovery, overrides, allowlisting | | storage | SQLite (default), PostgreSQL, or MongoDB | | logging | Audit logging of requests/responses | | usage | Token tracking, pricing, retention | | metrics | Prometheus endpoint | | guardrails | Content safety filters | | cache | Model cache, response cache (exact + semantic) | | combos | Multi-model combo definitions | | cli_tools | Admin CLI integration | | token_saver | Output compression | | fallback | Provider failover rules | | resilience | Retry + circuit breaker | | workflows | Workflow refresh cadence |

.env

Every environment variable is listed with its purpose and default value. Free features are uncommented (set to their default or true). Features needing external infrastructure (Redis, PostgreSQL, vector stores) are commented out with instructions.

Using a different config profile

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

| Profile | Best for | External services | |---------|----------|-------------------| | aurora init (default) | First run, individual devs | None | | oss.local-power.example.yaml | Local power users with caching | Redis | | oss.team.example.yaml | Team deployment | PostgreSQL, Redis, Qdrant |

Response caching

Two optional layers. Both need Redis.

• Exact cache — Hashes the request body and returns cached response on identical requests. Header: X-Cache: HIT (exact).
• Semantic cache — Embeds prompts, searches a vector store for semantically similar requests. Supports Qdrant, pgvector, Pinecone, Weaviate. Header: X-Cache: HIT (semantic).

Bypass per-request: Cache-Control: no-cache

Docker Compose

# Infrastructure only (Redis, Qdrant, Postgres)
docker compose up -d

# Full stack (Aurora + infra)
docker compose --profile app up -d

Build from source

Prerequisites: Go 1.26.2+, Node.js ≥18, pnpm

git clone https://github.com/gurveeer/Aurora.git && cd Aurora

# Dashboard UI (required for admin dashboard)
pnpm --dir dashboard-ui install && pnpm --dir dashboard-ui run build

# Binary
go build -o bin/aurora ./apps/aurora

# Test
go test ./apps/... ./internal/...

After building, use aurora init to scaffold a project, or run directly with env vars:

export AURORA_MASTER_KEY="my-key"
export GROQ_API_KEY="gsk_..."
./bin/aurora

Self-update & uninstall

aurora update       # Updates iaurora npm package to latest version
aurora uninstall    # Removes iaurora npm package from your system

Enterprise

Aurora OSS covers gateway routing, analytics, and provider operations. Aurora Enterprise adds SSO, RBAC, tenant isolation, budget enforcement, compliance workflows, and production support. The Enterprise edition is a separate distribution — it cannot be enabled by editing files in this tree.

Community

| | | |---|---| | Discord | Questions, provider setup, roadmap | | GitHub Issues | Bug reports, feature requests | | GitHub Stars | Support the project |