A high-performance LLM Gateway and Observability platform.

Lumina is a proxy that sits between your client applications and LLM providers (OpenAI, Anthropic), providing:

• Single API Interface - Manage multiple models through one endpoint
• Cost Tracking - Monitor spend per virtual key with budget limits
• Observability - Full request/response logging with searchable history
• Reliability - Rate limiting and request throttling

┌─────────────┐     ┌─────────────┐     ┌─────────────────┐
│   Client    │────▶│   Lumina    │────▶│  LLM Provider   │
│ Application │◀────│   Gateway   │◀────│ (OpenAI/Claude) │
└─────────────┘     └─────────────┘     └─────────────────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌────────────┐
        │ Postgres │ │  Redis   │ │ OpenSearch │
        └──────────┘ └──────────┘ └────────────┘

The easiest way to run Lumina is using the pre-built Docker image:

docker run -d \
  -p 8080:8080 \
  -p 3000:3000 \
  -e DATABASE_URL=postgres://user:pass@host:5432/lumina \
  -e REDIS_URL=redis://host:6379 \
  -e OPENSEARCH_URL=http://host:9200 \
  -e JWT_SECRET=your-secret-key \
  -e ENCRYPTION_KEY=your-32-byte-key \
  rbnacharya/lumina:latest

The container includes both the Gateway API (port 8080) and Web Dashboard (port 3000).

Required Environment Variables:

Infrastructure Requirements: PostgreSQL 15+, Redis 7+, OpenSearch 2.x

To run Lumina with all required infrastructure using Docker Compose:

# Clone the repository
git clone https://github.com/rbnacharya/lumina.git
cd lumina

# Start all services
docker compose up -d

# Access the services
# - Gateway API: http://localhost:8080
# - Web Dashboard: http://localhost:3000

This starts Lumina along with PostgreSQL, Redis, and OpenSearch.

• Docker & Docker Compose
• Tilt (for development)
• Task (task runner)
• Go 1.22+ (for local development)
• Node.js 20+ (for frontend development)

1. Start all services with Tilt:

   task start-dev

2. Or use Docker Compose directly:

   task dev

3. Access the services:

   • Gateway API: http://localhost:8080
   • Web Dashboard: http://localhost:3000
   • OpenSearch Dashboards: http://localhost:5601

# Development
task start-dev      # Start with Tilt (recommended)
task stop-dev       # Stop Tilt
task dev            # Start with Docker Compose
task dev-down       # Stop Docker Compose
task logs           # View service logs

# Database
task migrate        # Run migrations
task migrate-down   # Rollback migrations
task migrate-create -- <name>  # Create new migration

# Testing
task test           # Run all tests
task test-backend   # Run Go tests
task test-frontend  # Run frontend tests

# Building
task build          # Build all production images
task build-gateway  # Build Go binary
task build-web      # Build Next.js

# Production
task prod-up        # Start production services
task prod-down      # Stop production services

# Utilities
task lint           # Run linters
task fmt            # Format code
task clean          # Clean build artifacts
task health         # Check service health

lumina/
├── apps/
│   ├── gateway/          # Go backend (API proxy)
│   └── web/              # Next.js frontend (Dashboard)
├── deployments/
│   ├── docker/           # Docker Compose files
│   └── k8s/              # Kubernetes manifests
├── scripts/              # Utility scripts
├── Taskfile.yml          # Task runner configuration
├── Tiltfile              # Tilt development configuration
└── go.work               # Go workspace

Environment variables for the gateway:

1. Create a virtual key in the dashboard
2. Use it in your LLM client:

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer lum_your_virtual_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

The gateway will:

1. Validate your virtual key
2. Look up the associated provider and real API key
3. Forward the request to the provider
4. Log the request/response to OpenSearch
5. Track token usage and costs

• Supported Providers: OpenAI (Chat Completions), Anthropic (Messages API)
• Features: Key management, cost tracking, request logging, rate limiting
• Infrastructure: PostgreSQL, Redis, OpenSearch

• Model Pricing Configuration - Admin interface to upload and manage per-model pricing (initially via JSON config files, later via dashboard)
• Google Gemini Support - Add Gemini models as a supported provider
• Image Generation - Support for DALL-E, Stable Diffusion, and other image generation APIs
• Accurate Cost Calculation - Real-time cost tracking based on configurable model pricing

For support, please:

• Create an issue on GitHub
• Contact me at rbnacharya@gmail.com

MIT