mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-08-07 07:42:13 +03:00
04683029a6
* 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>
189 lines
5.5 KiB
Markdown
189 lines
5.5 KiB
Markdown
---
|
|
title: "Quick Start: Get OmniRoute Running in 3 Minutes"
|
|
version: 3.8.50
|
|
lastUpdated: 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)
|
|
|
|
```bash
|
|
npm install -g omniroute
|
|
```
|
|
|
|
### Option B: Docker
|
|
|
|
```bash
|
|
docker run -d --name omniroute -p 20128:20128 diegosouzapw/omniroute:latest
|
|
```
|
|
|
|
### Option C: From Source
|
|
|
|
```bash
|
|
git clone https://github.com/diegosouzapw/OmniRoute.git
|
|
cd OmniRoute
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
---
|
|
|
|
## Step 2: Start OmniRoute
|
|
|
|
```bash
|
|
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](http://localhost:20128/dashboard/api-manager), 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.
|
|
|
|
```bash
|
|
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](https://marketplace.visualstudio.com/items?itemName=Continue.continue) 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>
|
|
```
|
|
|
|
3. In the Continue.dev chat pane, select `OmniRoute - Auto` and you will make requests to OmniRoute.
|
|
4. (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`):
|
|
|
|
```bash
|
|
export OMNIROUTE_API_KEY="<YOUR_KEY>"
|
|
```
|
|
|
|
For Windows (Command Prompt):
|
|
|
|
```
|
|
setx OMNIROUTE_API_KEY <YOUR_KEY>
|
|
```
|
|
|
|
2. 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.
|
|
|
|
3. 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](http://localhost:20128/dashboard/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?
|
|
|
|
- **[Auto-Combo Guide](./AUTO-COMBO-GUIDE.md)** — Let OmniRoute pick the best AI for you
|
|
- **[Providers Guide](./PROVIDERS-GUIDE.md)** — Connect more providers (free and paid)
|
|
- **[Free Tiers Guide](./FREE-TIERS-GUIDE.md)** — Get free AI with no credit card
|
|
- **[Troubleshooting](./TROUBLESHOOTING.md)** — Fix common issues
|
|
|
|
---
|
|
|
|
## 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](./AUTO-COMBO-GUIDE.md) 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](./FREE-TIERS-GUIDE.md).
|
|
|
|
### "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](../reference/CLI-TOOLS.md) 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](./AUTO-COMBO-GUIDE.md) for details.
|
|
|
|
---
|
|
|
|
## Need Help?
|
|
|
|
- **[Troubleshooting](./TROUBLESHOOTING.md)** — Common issues and fixes
|
|
- **[Discord](https://discord.gg/U47eFqAXCn)** — Community support
|
|
- **[GitHub Issues](https://github.com/diegosouzapw/OmniRoute/issues)** — Report bugs
|