How to Install OmniRoute — Complete Setup Guide

Before installing OmniRoute, confirm your environment meets these requirements:

Clone the OmniRoute repository from GitHub and install dependencies:

OmniRoute has 9.8k GitHub stars and is actively maintained. Check the releases tab for the latest stable version tag before deploying to production.

Copy the example environment file and add your provider API keys. OmniRoute reads all provider credentials from environment variables at startup.

Open .env and add your keys. A minimal two-provider setup looks like this:

OmniRoute supports 231+ providers. Check the .env.example file in the repository for the full list of supported provider environment variable names.

OmniRoute's routing behavior is defined in omniroute.config.js (or omniroute.config.json). Define your primary provider and fallback chain:

The target_ratio parameter controls compression aggressiveness. A value of 0.6 means OmniRoute will attempt to reduce the prompt to 60% of its original token count. Adjust based on your quality/cost tradeoff requirements.

Token compression is enabled in the config file (Step 4) and requires no additional setup. However, these settings let you tune the compression behavior for your specific workload:

Set preserve_code: true if your prompts contain code snippets or structured data — this prevents the compressor from mangling syntax-sensitive content.

Start OmniRoute in development mode to verify your configuration:

OmniRoute starts on port 4000 by default (override with OMNIROUTE_PORT). You should see startup logs confirming which providers are configured and that compression is active:

Point any OpenAI-compatible SDK at your OmniRoute instance by changing the base URL. No other code changes required. Here are examples for the most common clients:

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'any-string', // OmniRoute uses
  baseURL: 'http://localhost:4000/v1',  // your own keys
});

const res = await client.chat.completions.create({
  model: 'gpt-4o', // OmniRoute routes this
  messages: [{ role: 'user', content: 'Hello' }],
});

from openai import OpenAI

client = OpenAI(
    api_key="any-string",
    base_url="http://localhost:4000/v1",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)

The apiKey value in your client can be any non-empty string — OmniRoute uses the provider API keys from your .env file, not the value your application passes in. This keeps provider keys centralized in OmniRoute rather than distributed across your apps.