How to configure OmniRoute for a specific project structure: Environment, CLI, and Runtime Setup

To configure OmniRoute for any project structure, edit the .env file for core runtime settings, use the omniroute CLI to register providers and routing combos in the SQLite-backed Settings DB, and adjust CORS or feature flags via environment variables or the Dashboard—all without modifying source code.

The diegosouzapw/OmniRoute repository provides a modular Next.js/Node application that routes OpenAI-compatible LLM requests to your chosen provider. Whether you are deploying in a container, integrating into a monorepo, or running locally, you can tailor OmniRoute to your directory layout by interacting with three configuration layers: environment variables, the built-in CLI, and the runtime Settings database.

Bootstrap the Environment

All core runtime options—including port, data directory, and JWT secrets—live in the project root environment file. Copy the template and generate required secrets before starting the server.

# Copy the environment template

cp .env.example .env

# Generate a JWT secret for token authentication

openssl rand -base64 48 > jwt.secret
echo "JWT_SECRET=$(cat jwt.secret)" >> .env

# Configure custom data directory and port (optional)

echo "DATA_DIR=/var/omniroute/data" >> .env
echo "PORT=3000" >> .env

Source: .env.example defines the schema for all runtime variables.

Register AI Providers

Provider credentials and connection limits are stored in the Settings DB (src/lib/db/settings.ts) and managed via the OmniRoute CLI or Dashboard UI. This keeps secrets out of your codebase.

# Add OpenAI with rate limiting

omniroute providers add openai \
  --api-key $OPENAI_API_KEY \
  --name "OpenAI-Prod" \
  --rate-limit 3500

# Add a local Ollama instance

omniroute providers add ollama \
  --base-url http://localhost:11434/v1 \
  --name "Ollama-Local"

The CLI persists these entries to the same SQLite database the server reads, so changes reflect instantly in hot-reloaded dev mode (npm run dev) or production builds.

Reference: open-sse/config/providerRegistry.ts handles provider registration and default credential validation.

Define Routing Combos

Routing combos determine how requests distribute across providers. Define weighted, priority, or fusion strategies using the CLI; the logic resides in open-sse/services/combo.ts and persists in src/lib/db/comboTargets.ts.

# Create a weighted combo: 70% GPT-4, 30% Claude

omniroute combo create myCombo \
  --strategy weighted \
  --targets "openai:gpt-4:0.7" "anthropic:claude-3-sonnet:0.3"

Access the /dashboard/combos UI to edit these later without restarting the server.

Tune Feature Flags and Security

Feature flags for PII masking, compression, and auto-combo defaults are declared in src/shared/constants/featureFlagDefinitions.ts. Override them via the CLI or environment variables to match your project's compliance needs.

# Disable PII redaction for development

omniroute config set PII_REDACTION_ENABLED=false
omniroute config set PII_RESPONSE_SANITIZATION=false

For security boundaries, restrict local-only service routes (such as /api/services/*) to loopback addresses by setting environment variables read by src/server/authz/routeGuard.ts and src/server/cors/origins.ts:

echo "CORS_ALLOWED_ORIGINS=https://app.example.com" >> .env
echo "LOCAL_ONLY_ROUTES=true" >> .env

Adapt to Custom Directory Layouts

If your project uses a non-standard directory structure or lives in a monorepo, update the TypeScript path alias in tsconfig.json so the Next.js app router resolves imports correctly without changing source files.

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["my-code/**"]
    }
  }
}

The codebase uses @/* aliases throughout (src/app/...), so remapping this single configuration key adapts OmniRoute to any folder hierarchy.

Verify the Configuration

Start the server and validate the setup using the health endpoint defined in src/app/api/monitoring/health/route.ts:

npm install
npm run dev

# Test a chat completion

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

Check the Dashboard → Health page to confirm provider circuit-breakers and connection cooldowns report healthy status.

Summary

• Environment variables in .env control runtime fundamentals like PORT, DATA_DIR, and JWT_SECRET.
• The OmniRoute CLI writes provider credentials and combo strategies to the SQLite Settings DB (src/lib/db/settings.ts), keeping configuration external to source code.
• Feature flags and CORS settings are overridden via CLI commands or environment variables consumed by src/server/authz/routeGuard.ts and related modules.
• Custom project structures require only a tsconfig.json path mapping update to relocate the src/ alias.
• All changes apply dynamically; hot-reload in development or rebuild for production without editing implementation files.

Frequently Asked Questions

Where does OmniRoute store provider credentials and routing rules?

OmniRoute stores all runtime configuration in a SQLite database accessed through src/lib/db/settings.ts. You populate this database using the omniroute providers add and omniroute combo create CLI commands, or through the Dashboard UI, ensuring secrets never reside in the git-tracked source code.

How do I configure OmniRoute for a monorepo with a different source folder?

Update the paths compiler option in tsconfig.json to remap the @/* alias to your custom directory. For example, set "@/*": ["packages/omniroute/src/**"] to accommodate a monorepo layout. The Next.js app router and all internal imports will resolve correctly without further changes.

Can I run OmniRoute in a Docker container with custom ports and volumes?

Yes. Set PORT, DATA_DIR, and CORS_ALLOWED_ORIGINS via environment variables in your docker-compose.yml or Dockerfile. Mount a host volume to DATA_DIR to persist the SQLite Settings DB and logs across container restarts, referencing the provided Dockerfile for image build specifics.

How do I secure local-only routes when exposing OmniRoute to the internet?

Set LOCAL_ONLY_ROUTES=true in your .env file. This instructs src/server/authz/routeGuard.ts to restrict endpoints like /api/services/* to localhost requests only. Combine this with CORS_ALLOWED_ORIGINS to enforce strict origin policies on public endpoints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}