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

> Configure OmniRoute for your project structure. Set up environments, use the CLI for routing, and manage runtime settings via environment variables without code changes.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-17

---

**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.

```bash

# 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/settings.ts)) and managed via the **OmniRoute CLI** or Dashboard UI. This keeps secrets out of your codebase.

```bash

# 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) and persists in [`src/lib/db/comboTargets.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/comboTargets.ts).

```bash

# 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/featureFlagDefinitions.ts). Override them via the CLI or environment variables to match your project's compliance needs.

```bash

# 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/routeGuard.ts) and [`src/server/cors/origins.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/cors/origins.ts):

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/tsconfig.json) so the Next.js app router resolves imports correctly without changing source files.

```jsonc
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/monitoring/health/route.ts):

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/routeGuard.ts) and related modules.
- **Custom project structures** require only a [`tsconfig.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.