feat: OmniRoute v1.0.0 — Intelligent AI Gateway & Universal LLM Proxy

OmniRoute is an intelligent API gateway that unifies 20+ AI providers behind a single
OpenAI-compatible endpoint. Features include intelligent routing with 6 strategies,
multi-format translation (OpenAI/Claude/Gemini/Responses API), circuit breakers,
semantic caching, combo fallback chains, real-time health monitoring, and a full
dashboard with provider management, analytics, and CLI tool integration.

Key highlights:
- 20+ providers (Claude Code, Codex, Gemini CLI, GitHub Copilot, iFlow, Qwen, Kiro, etc.)
- 6 routing strategies (Fill First, Round Robin, P2C, Random, Least Used, Cost Optimized)
- Export/Import database backup with full archive support
- Translator Playground with 4 modes (Playground, Chat Tester, Test Bench, Live Monitor)
- 100% TypeScript across src/ and open-sse/
- Docker support with multi-stage builds
- Comprehensive documentation and 9 dashboard screenshots

Author: diegosouzapw

.agent/workflows/git-workflow.md

@@ -0,0 +1,54 @@
+---
+description: Git workflow — NEVER commit directly to main. Always use feature branches.
+---
+
+# Git Workflow
+
+## ⚠️ CRITICAL RULE: NEVER commit directly to `main`
+
+## Steps
+
+1. **Before starting any work**, create a feature branch from `main`:
+
+   ```bash
+   git checkout main && git pull origin main
+   git checkout -b feature/<feature-name>
+   ```
+
+2. **During development**, commit to the feature branch:
+
+   ```bash
+   git add -A && git commit -m "<type>(<scope>): <description>"
+   ```
+
+3. **Before pushing**, verify the build passes:
+
+   ```bash
+   npm run build
+   ```
+
+4. **When the feature is complete and verified**, push the branch and STOP:
+
+   ```bash
+   git push origin feature/<feature-name>
+   ```
+
+5. **DO NOT** create a PR, merge, or push to `main`. Let the user handle that.
+
+## Branch naming convention
+
+- `feature/<name>` — new features
+- `fix/<name>` — bugfixes
+- `refactor/<name>` — refactoring
+- `docker/<name>` — Docker / infrastructure changes
+- `style/<name>` — UI / CSS changes
+
+## Commit types
+
+- `feat` — new feature
+- `fix` — bugfix
+- `refactor` — code refactoring
+- `style` — UI / CSS changes
+- `docker` — Docker / infrastructure
+- `docs` — documentation
+- `chore` — maintenance

.dockerignore

@@ -0,0 +1,32 @@
+# VCS
+.git
+**/.git
+
+# Editor
+.vscode
+**/.vscode
+
+# Dependencies and build output
+node_modules
+.next
+out
+build
+dist
+coverage
+
+# Runtime data and logs
+data
+logs
+
+# Local env files (inject at runtime via --env-file or -e)
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Debug logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*

.env.example

@@ -0,0 +1,120 @@
+# OmniRoute environment contract
+# This file reflects actual runtime usage in the current codebase.
+
+# ═══════════════════════════════════════════════════
+#   REQUIRED SECRETS — Generate strong values!
+# ═══════════════════════════════════════════════════
+# Generate with: openssl rand -base64 48
+JWT_SECRET=
+# Generate with: openssl rand -hex 32
+API_KEY_SECRET=
+
+# Initial admin password — CHANGE THIS before first use!
+INITIAL_PASSWORD=CHANGEME
+DATA_DIR=/var/lib/omniroute
+
+# Storage (SQLite)
+STORAGE_DRIVER=sqlite
+# Generate with: openssl rand -hex 32
+STORAGE_ENCRYPTION_KEY=
+STORAGE_ENCRYPTION_KEY_VERSION=v1
+LOG_RETENTION_DAYS=90
+SQLITE_MAX_SIZE_MB=2048
+SQLITE_CLEAN_LEGACY_FILES=true
+
+# Recommended runtime variables
+PORT=20128
+NODE_ENV=production
+INSTANCE_NAME=omniroute
+
+# Recommended security and ops variables
+MACHINE_ID_SALT=endpoint-proxy-salt
+ENABLE_REQUEST_LOGS=false
+AUTH_COOKIE_SECURE=false
+REQUIRE_API_KEY=false
+
+# Input Sanitizer (FASE-01 — prompt injection & PII protection)
+# INPUT_SANITIZER_ENABLED=true
+# INPUT_SANITIZER_MODE=warn    # warn | block | redact
+# PII_REDACTION_ENABLED=false
+
+# Cloud sync variables
+# Must point to this running instance so internal sync jobs can call /api/sync/cloud.
+# Server-side preferred variables:
+BASE_URL=http://localhost:20128
+CLOUD_URL=
+# Backward-compatible/public variables:
+NEXT_PUBLIC_BASE_URL=http://localhost:20128
+NEXT_PUBLIC_CLOUD_URL=
+
+# Optional outbound proxy variables for upstream provider calls
+# Lowercase variants are also supported: http_proxy, https_proxy, all_proxy, no_proxy
+# SOCKS5 proxy support
+ENABLE_SOCKS5_PROXY=true
+NEXT_PUBLIC_ENABLE_SOCKS5_PROXY=true
+# HTTP_PROXY=http://127.0.0.1:7890
+# HTTPS_PROXY=http://127.0.0.1:7890
+# ALL_PROXY=socks5://127.0.0.1:7890
+# NO_PROXY=localhost,127.0.0.1
+
+# TLS fingerprint spoofing (opt-in) — mimics Chrome 124 TLS handshake via wreq-js
+# Reduces risk of JA3/JA4 fingerprint-based blocking by providers (e.g., Google)
+# Requires wreq-js to be installed (included in dependencies)
+# ENABLE_TLS_FINGERPRINT=true
+
+# Optional CLI runtime overrides (Docker/host integration)
+# CLI_MODE=auto
+# CLI_EXTRA_PATHS=/host-cli/bin
+# CLI_CONFIG_HOME=/root
+# CLI_ALLOW_CONFIG_WRITES=true
+# CLI_CLAUDE_BIN=claude
+# CLI_CODEX_BIN=codex
+# CLI_DROID_BIN=droid
+# CLI_OPENCLAW_BIN=openclaw
+# CLI_CURSOR_BIN=agent
+# CLI_CLINE_BIN=cline
+# CLI_ROO_BIN=roo
+# CLI_CONTINUE_BIN=cn
+
+# Provider OAuth Credentials (optional — override hardcoded defaults)
+# These can also be set via data/provider-credentials.json
+# CLAUDE_OAUTH_CLIENT_ID=
+# GEMINI_OAUTH_CLIENT_ID=
+# GEMINI_OAUTH_CLIENT_SECRET=
+# GEMINI_CLI_OAUTH_CLIENT_ID=
+# GEMINI_CLI_OAUTH_CLIENT_SECRET=
+# CODEX_OAUTH_CLIENT_ID=
+# CODEX_OAUTH_CLIENT_SECRET=
+# QWEN_OAUTH_CLIENT_ID=
+# IFLOW_OAUTH_CLIENT_ID=
+# IFLOW_OAUTH_CLIENT_SECRET=
+# ANTIGRAVITY_OAUTH_CLIENT_ID=
+# ANTIGRAVITY_OAUTH_CLIENT_SECRET=
+
+# API Key Providers (Phase 1 + Phase 4)
+# Add via Dashboard → Providers → Add API Key, or set here
+# DEEPSEEK_API_KEY=
+# GROQ_API_KEY=
+# XAI_API_KEY=
+# MISTRAL_API_KEY=
+# PERPLEXITY_API_KEY=
+# TOGETHER_API_KEY=
+# FIREWORKS_API_KEY=
+# CEREBRAS_API_KEY=
+# COHERE_API_KEY=
+# NVIDIA_API_KEY=
+
+# Embedding Providers (optional — used by /v1/embeddings)
+# NEBIUS_API_KEY=
+# Provider keys above (openai, mistral, together, fireworks, nvidia) also work for embeddings
+
+# Timeout settings
+# FETCH_TIMEOUT_MS=120000
+# STREAM_IDLE_TIMEOUT_MS=60000
+
+# CORS configuration (default: * allows all origins)
+# CORS_ORIGINS=*
+
+# Logging
+# LOG_LEVEL=info
+# LOG_FORMAT=text

.github/dependabot.yml

@@ -0,0 +1,31 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    commit-message:
+      prefix: "deps"
+    open-pull-requests-limit: 10
+    groups:
+      production:
+        dependency-type: "production"
+      development:
+        dependency-type: "development"
+    ignore:
+      - dependency-name: "react"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "react-dom"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "next"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "eslint"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "eslint-config-next"
+        update-types: ["version-update:semver-major"]
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/workflows/ci.yml

@@ -0,0 +1,110 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run lint
+
+  security:
+    name: Security Audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - name: Dependency audit
+        run: npm audit --audit-level=high --omit=dev
+      - name: Check for known vulnerabilities
+        run: npx is-my-node-vulnerable || true
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+
+  test-unit:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+    needs: build
+    strategy:
+      matrix:
+        node-version: [20, 22]
+    env:
+      JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-test-api-key-secret-long
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+      - run: npm ci
+      - run: npm run test:unit
+
+  test-coverage:
+    name: Coverage
+    runs-on: ubuntu-latest
+    needs: build
+    env:
+      JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-test-api-key-secret-long
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run test:coverage
+      - name: Check coverage threshold
+        run: |
+          echo "Coverage report generated. Check output for threshold compliance."
+
+  test-e2e:
+    name: E2E Tests
+    runs-on: ubuntu-latest
+    needs: build
+    env:
+      JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-test-api-key-secret-long
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npx playwright install --with-deps chromium
+      - run: npm run build
+      - run: npm run test:e2e

.github/workflows/codex-review.yml

@@ -0,0 +1,22 @@
+name: Codex PR Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  request-codex-review:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - name: Request Codex Review
+        uses: actions/github-script@v8
+        with:
+          script: |
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.payload.pull_request.number,
+              body: '@codex review'
+            });