Repository intelligenceRepositories
⌘K
Home / Repositories / diegosouzapw/OmniRoute / Instruction Manual
Instruction Manual · Apple silicon · macOS Tahoe

diegosouzapw/OmniRoute Instruction Manual

Local-first AI gateway routing coding agents across hundreds of providers/models with fallback, dashboard, MCP/A2A, and RTK/Caveman prompt compression.

Beginner-friendlyCopy-paste examplesFirst-party sources checked
GitHubRepository profileInstallation Guide

What diegosouzapw/OmniRoute is—in plain language

Local-first AI gateway routing coding agents across hundreds of providers/models with fallback, dashboard, MCP/A2A, and RTK/Caveman prompt compression.

Mental model: This repository behaves like a service or multi-process application. One command starts it, a browser/API/agent connects to it, and the Terminal process must remain running until you stop it.
InterfacesAPI, CLI, dashboard, MCP, A2A
Primary languageTypeScript
Typical useCentralize model access, route around quota/outages, apply configurable compression, and operate through API, CLI, dashboard, desktop/PWA, MCP, or A2A.

Your first 15 minutes

  1. Complete the linked Installation Guide and its verification step.
  2. Create a disposable test folder or use non-sensitive sample data.
  3. Run the small example below and observe what files, ports, or prompts appear.
  4. Read the result before approving writes, network calls, account access, or costs.
  5. Only then repeat the workflow with a real project.
Starter workflow
curl http://localhost:20128/v1/models
Open Installation GuideOpen upstream README

Complete indexed functionality map

Each card below corresponds to a component identified in the repository research. Open a component record for its path, purpose, capabilities, dependencies, risks, and relationships.

Compression pipeline

service

Off/lite/standard/aggressive/ultra/RTK/stacked modes.

open-sse/services/compression/
Open component record →

Upstream feature-by-feature guide

These capabilities are derived from the current first-party README and supporting documentation. Names follow upstream terminology so you can search the source documentation precisely.

Upstream capability

💰 ~1.51B Free Tokens / Month

Upstream treats this as a distinct part of diegosouzapw/OmniRoute. In plain language, use this area when your task concerns 💰 ~1.51b free tokens / month. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

📈 The Gateway Keeps Growing

Upstream treats this as a distinct part of diegosouzapw/OmniRoute. In plain language, use this area when your task concerns 📈 the gateway keeps growing. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

🧩 Available

Upstream treats this as a distinct part of diegosouzapw/OmniRoute. In plain language, use this area when your task concerns 🧩 available. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

🎯 Combos — The Flagship

Upstream treats this as a distinct part of diegosouzapw/OmniRoute. In plain language, use this area when your task concerns 🎯 combos — the flagship. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

⚡ Zero-config — just use auto

Upstream treats this as a distinct part of diegosouzapw/OmniRoute. In plain language, use this area when your task concerns ⚡ zero-config — just use auto. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

### 🔀 Or build your own — 19 routing strategies

Upstream treats this as a distinct part of diegosouzapw/OmniRoute. In plain language, use this area when your task concerns ### 🔀 or build your own — 19 routing strategies. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

### 🧱 Resilience is built in (3 independent layers)

Upstream treats this as a distinct part of diegosouzapw/OmniRoute. In plain language, use this area when your task concerns ### 🧱 resilience is built in (3 independent layers). Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

🏆 What Sets OmniRoute Apart

Upstream treats this as a distinct part of diegosouzapw/OmniRoute. In plain language, use this area when your task concerns 🏆 what sets omniroute apart. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

📡 OmniRoute Radar

Upstream treats this as a distinct part of diegosouzapw/OmniRoute. In plain language, use this area when your task concerns 📡 omniroute radar. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

✨ What's New

Upstream treats this as a distinct part of diegosouzapw/OmniRoute. In plain language, use this area when your task concerns ✨ what's new. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

🤖 Compatible CLIs & Coding Agents

Upstream treats this as a distinct part of diegosouzapw/OmniRoute. In plain language, use this area when your task concerns 🤖 compatible clis & coding agents. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

🌐 341 AI Providers — 90+ Free

Upstream treats this as a distinct part of diegosouzapw/OmniRoute. In plain language, use this area when your task concerns 🌐 341 ai providers — 90+ free. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

How to use the main workflows

1

Choose the smallest relevant function

Start with one capability card instead of asking the repository to do everything at once. This makes permissions, inputs, and output easier to understand.

2

Prepare a disposable input

Use a sample URL, copied repository, test document, or sandbox account. Keep production credentials and irreplaceable files out of the first run.

3

Run, observe, and stop

Watch Terminal output or the host application's activity view. If the behavior differs from the README, stop with Control + C or cancel inside the host before retrying.

4

Inspect the result

Check generated files, diffs, API responses, logs, or previews. Never assume “command finished” means the result is correct.

5

Save a repeatable recipe

Record the working command and non-secret configuration in your project's README. Store secrets in the documented environment file or password manager.

Copy-paste recipes from upstream documentation

These examples are selected from the repository's first-party documentation. Replace obvious placeholders, keep quotation marks intact, and run them only in the context indicated by the surrounding explanation.

🛰️ Remote mode — run the CLI here, OmniRoute on a VPS
omniroute connect 192.168.0.15            # password → scoped token, saved as a context
omniroute models list                     # ← runs against the REMOTE server
omniroute configure codex                 # ← picks a remote model, writes a local Codex profile
omniroute tokens create --name ci --scope read   # mint narrower tokens for other machines
omniroute contexts use default            # ← switch back to the local server
Or using devbox
# 1. Prepare the bind-mounted data directory
mkdir -p data

# 2. Linux + local rootless Podman only (never a remote Podman Machine client):
podman unshare chown 1000:1000 ./data

# 3. Set the runtime hint, build the local Compose image, and start
echo "CONTAINER_HOST=podman" >> .env
podman compose --profile base up -d --build
⌨️ A real CLI (not just start)
omniroute               # serve gateway + dashboard (port 20128)
omniroute chat          # interactive TUI chat client (slash: /model /combo /skill /memory)
omniroute setup         # guided first-run wizard
omniroute doctor        # diagnose providers, ports, native deps

Configuration, accounts, and files

Configuration files

None documented

A configuration file changes behavior without changing source code. Make one change at a time and keep a backup before editing JSON, TOML, YAML, or environment files.

Important directories

skills/, open-sse/services/compression/, docs/

Paths identify where the relevant implementation or generated files live. Paths beginning with ~ are inside your home folder.

Credentials

provider credentials, management token/key

Prefer temporary, least-privileged credentials. Never commit .env, tokens, cookies, private keys, or session exports.

External services

LLM providers

Check pricing, data retention, rate limits, and account permissions before enabling optional integrations.

Safe operating habits

  • Use test data first and keep a current backup or Git commit.
  • Read commands before pasting. A README is useful evidence, not a substitute for judgment.
  • Review agent-generated file changes with git diff before committing.
  • Keep local services bound to 127.0.0.1 unless you intentionally secure and expose them.
  • Do not give plugins or MCP servers broader filesystem, browser, GitHub, or cloud access than their current task requires.
  • Confirm API costs and model names before running large batches.
  • Stop and investigate repeated authentication failures instead of pasting a token into multiple places.

Reference and source trail

The manual reflects first-party files checked on August 18, 2026. It explains the indexed repository rather than promising that every optional third-party integration is available or safe.