pjandro/OmniRoute
1
0
Fork 0
mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-08-08 00:02:20 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
aa7b3913862cf2f32a5cd7f09c8ffb9be87c19d0
OmniRoute/docs/getting-started/QUICK-START.md
Diego Rodrigues de Sa e Souza 04683029a6 fix(build): exec native esbuild binary directly in prepublish (dast-smoke base-red) (#9558) 
* fix(build): exec native tool binaries directly in runBuildTool

#8858 routed every resolved local bin through process.execPath to avoid
Windows .cmd shims — but esbuild >=0.25 ships bin/esbuild as the NATIVE
platform executable (ELF on Linux), so Node parsed machine code as JS and
build:cli died with 'SyntaxError: Invalid or unexpected token', turning
dast-smoke red for every PR.

runBuildTool now sniffs the entry's magic bytes (ELF / Mach-O / PE) and
execs native binaries directly; JS entries keep going through this Node
binary (the .cmd-shim avoidance #8858 wanted).

Validation (RED->GREEN on this box):
- RED: node node_modules/esbuild/bin/esbuild --version -> SyntaxError (ELF)
- GREEN: the exact failing CI step reproduced via the new logic bundles
  open-sse/mcp-server/server.ts successfully (4.2MB output, 1.3s).

* fix(docs): add MDX frontmatter to the 20 remaining docs without it

Same failure class as AGENTROUTER_WAF (#9503) and DOCKER_RELEASE_CHANNELS
(this run's dast-smoke red): any doc without frontmatter breaks the
fumadocs MDX loader during next build, killing build:cli/dast-smoke for
every PR. Swept ALL of docs/ (i18n mirrors excluded) in one pass so this
class cannot recur one file at a time.

* docs(env): document OMNIROUTE_INTERNAL_SERVICE_TOKEN(+_FILE), OPENROUTER_PROVIDER_STATS_* and embedded-Redis binding vars

Pre-existing env/docs contract drift from recently merged features made
check:env-doc-sync red for any docs-touching PR. Values and defaults read
from the defining modules (internalServiceAuth.ts, openrouterProviderStats.ts).

* fix(build): resolve bundled npm-cli.js in the standard Unix layout + safe npm fallback off-Windows

The opencode-plugin step hard-failed on GitHub runners because
resolveBundledNpmEntry only looked next to the node binary (Windows zip
layout); hostedtoolcache Node keeps npm at <prefix>/lib/node_modules/npm.
Added that candidate, and when neither exists on non-Windows the step now
falls back to plain 'npm' — the .cmd-shim hazard #8858 avoids is
Windows-only.

* test(mutation): register xai-agent-tools-passthrough.test.ts in stryker tap.testFiles

The test landed on release/v3.8.50 covering
open-sse/handlers/chatCore/passthroughHelpers.ts without the stryker
registration, so Fast Quality Gates' drift detection reds any PR that
carries it. Mechanical registration so its mutant kills count.

---------

Co-authored-by: diegosouzapw <diegosouzapw@users.noreply.github.com>
2026-08-06 02:19:57 -03:00

5.5 KiB
Raw Blame History

title, version, lastUpdated
title version lastUpdated
Quick Start: Get OmniRoute Running in 3 Minutes 3.8.50 2026-08-06

Quick Start: Get OmniRoute Running in 3 Minutes

TL;DR: Install → Connect a free provider → Point your IDE to OmniRoute. Done.

Step 1: Install OmniRoute

Choose your preferred method:

Option A: npm (Recommended)

npm install -g omniroute

Option B: Docker

docker run -d --name omniroute -p 20128:20128 diegosouzapw/omniroute:latest

Option C: From Source

git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute
npm install
npm run dev

Step 2: Start OmniRoute

omniroute

OmniRoute starts at http://localhost:20128. The dashboard opens automatically.

Step 3: Connect a Free Provider

You can use OmniRoute without paying anything by connecting a free provider.

Option A: Kiro (Free Claude — No Credit Card)

  1. Open the dashboard at http://localhost:20128
  2. Go to Providers → Add Provider
  3. Select Kiro AI
  4. Click Connect (no API key needed!)
  5. Done! You now have free access to Claude models.

Option B: OpenCode Free (No Auth)

  1. Open the dashboard at http://localhost:20128
  2. Go to Providers → Add Provider
  3. Select OpenCode Free
  4. Click Connect (no API key needed!)
  5. Done! You now have free access to multiple models.

Option C: Pollinations (No Key Needed)

  1. Open the dashboard at http://localhost:20128
  2. Go to Providers → Add Provider
  3. Select Pollinations
  4. Click Connect (no API key needed!)
  5. Done! You now have free access to GPT-5, Claude, Gemini, and more.

Step 4: Verify It Works

From API Keys, create a new key. Store this key since it will not appear again. Do note that this key is for tools to access OmniRoute, not to access upstream providers.

curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"

You should see your connected models listed.

Step 5: Point Your IDE or CLI to OmniRoute

In your IDE or CLI tool, set:

Base URL: http://localhost:20128/v1
API Key:  [copy from Dashboard → Endpoints]
Model:    auto

That's it! Your IDE now uses OmniRoute with automatic provider selection.

IDE Example: VSCode/Continue.dev

  1. In VSCode, install the Continue.dev extension.
  2. Update your ~/.continue/config.yaml to add the following lines:
  - name: OmniRoute - Auto
    provider: openai
    model: auto
    apiBase: http://localhost:20128/v1
    apiKey: <YOUR_KEY>
  1. In the Continue.dev chat pane, select OmniRoute - Auto and you will make requests to OmniRoute.
  2. (Optional) Exercise for the reader - have your IDE update the config.yaml with all the other prebuilt configurations 😊

CLI Example: Codex CLI

  1. In your operating system, set the environment variable persistently. For macOS/Linux (add to your ~/.bashrc or ~/.zshrc):
export OMNIROUTE_API_KEY="<YOUR_KEY>"

For Windows (Command Prompt):

setx OMNIROUTE_API_KEY <YOUR_KEY>
  1. Now let's launch Codex, but configured for OmniRoute. Run:
omniroute launch-codex --model auto

You can do this manually via codex and command line parameters to specify endpoint and api key, but with the above command, OmniRoute takes care of everything for you.

  1. The CLI should be sending requests to OmniRoute now.

Confirm your tool is routing to OmniRoute

You can see the details of the request by clicking Monitoring/Logs from the left sidebar. Clicking through shows you more details. As a side note, you can see what info gets sent up from your favorite harness. This is helpful from an educational and debugging perspective.

What's Next?

Common Questions

"Do I need an API key?"

No! You can use free providers (Kiro, OpenCode Free, Pollinations) without any API key. Just connect them in the dashboard.

"What is auto?"

auto tells OmniRoute to automatically pick the best provider for each request. It considers speed, cost, quality, and availability. See the Auto-Combo Guide for details.

"How much does it cost?"

OmniRoute itself is free and open-source. You only pay for the providers you use. Many providers have free tiers — see the Free Tiers Guide.

"Can I use it with Claude Code / Cursor / Copilot?"

Yes! OmniRoute works with any tool that supports OpenAI format. Just set the base URL to http://localhost:20128/v1. See the CLI Tools Guide for specific setup instructions.

"What if a provider goes down?"

OmniRoute automatically skips failed providers and tries the next one. You don't need to do anything. See the Auto-Combo Guide for details.

Need Help?

Reference in New Issue View Git Blame Copy Permalink