P Promptdeck Guides Verified August 31, 2026 · OmniRoute 3.8.50
Step-by-step setup guide

How to Use OmniRoute with Claude Code

Put a local AI gateway between Claude Code and the providers you choose, then keep coding when one provider is unavailable or runs out of quota.

Claude Code→OmniRoute→your providers
In short

Install OmniRoute → connect providers → launch Claude Code through OmniRoute → use auto/coding for routing/fallback.

The setup at a glance

HOW TO INSTALL OMNIROUTE

Set up OmniRoute as an AI gateway for Claude Code with multi-provider routing and automatic fallback.

Claude Code
OmniRoute AI Gateway
AI Providers
Install Connect Providers Configure Routing Launch Claude Code
01
The idea

What OmniRoute does

OmniRoute is a self-hosted AI gateway. Claude Code sends its requests to OmniRoute, and OmniRoute forwards each request to a model from a provider you connected.

One local endpoint

Your coding tool talks to one address while OmniRoute handles the different provider connections behind it.

Automatic alternatives

A routing combo—or the built-in auto model—can move work to another healthy option when the first cannot answer.

Important: OmniRoute does not make paid models free. Cost and quota depend on each upstream provider, its current terms, and the accounts you connect.

02
Prerequisites

Before you start

  • A Mac, Windows, or Linux computer with terminal access.
  • Node.js 22.22.2 or newer for the current OmniRoute release.
  • The Claude Code CLI installed. This guide uses the terminal CLI, not Claude Desktop.
  • At least one provider account or API key—or a no-auth provider currently shown in OmniRoute.

If Claude Code is not installed yet, use Anthropic’s current official installation guide ↗. Finish that installation before continuing.

03
Install

Install OmniRoute

Open your terminal and install the current npm package globally:

Terminal
npm install -g omniroute

When it finishes, start OmniRoute:

Terminal
omniroute

Keep this terminal window open. Closing it stops the local OmniRoute server unless you later set it up as a background service.

04
Local control panel

Open the dashboard

OmniRoute normally opens its dashboard automatically. If it does not, open this address in your browser:

Local dashboard
http://localhost:20128

This address works only on the computer where OmniRoute is running. The API lives at http://localhost:20128/v1, but Claude Code’s gateway root is configured without the /v1 suffix.

05
Add model access

Connect your providers

  1. Open Providers. In the dashboard, choose Providers and connect at least one option using its supported sign-in or API-key flow.
  2. Confirm a model appears. Use the provider’s test control if shown. A connected account is not useful until OmniRoute can list at least one available model.
  3. Create an endpoint key. Open Endpoints, create a local OmniRoute API key, and copy it somewhere secure. Do not paste it into public posts or screenshots.

Provider availability, free tiers, model names, and quotas change. Use the live Providers and Free Tiers screens as the source of truth on the day you set this up.

06
Launch

Connect to Claude Code

The simplest supported method is OmniRoute’s launcher. In a second terminal, move into your project folder and run:

Terminal
omniroute launch

The launcher finds the active local OmniRoute context, checks that the gateway is healthy, injects the correct environment settings, and starts Claude Code.

Newer general launcher

OmniRoute 3.8.50 also includes omniroute run <target>, a general launcher for several coding CLIs. For Claude Code, the equivalent command is:

Terminal
omniroute run claude

For a first setup, keep using omniroute launch. It remains the clearest Claude-specific command; use omniroute run claude when you prefer the newer shared launcher pattern.

Optional: create model profiles

If you want a reusable Claude Code profile for each connected model, generate them first:

Terminal
omniroute setup-claude

Then launch one of the profile names OmniRoute shows you:

Terminal
omniroute launch --profile YOUR_PROFILE

Why use the launcher? Claude Code expects the gateway root—http://localhost:20128—without /v1. omniroute launch handles that detail and injects the local access token without storing it in a profile.

07
Resilience

Set up automatic routing and fallback

Fastest option: use auto/coding

Choose auto/coding when you want OmniRoute to build a coding-focused virtual route from your connected providers. The general auto model is a balanced alternative.

More control: build a combo

  1. Open Combos. Create a new combo in the dashboard.
  2. Add at least two models. Put your preferred model first and a genuinely separate provider second.
  3. Choose the order or strategy. A simple priority order is easiest to understand; other strategies optimize for health, quota, speed, or cost.
  4. Save and select the combo. Use its model ID when launching or configuring a profile.

When a target is unavailable, rate-limited, or fails in a way the combo recognizes, OmniRoute can skip to the next eligible target. Fallback is not a guarantee: every connected option can still be unavailable at the same time.

08
Verify

Test that it works

✓OmniRoute’s terminal is still running and the dashboard loads at localhost:20128.
✓The Providers screen shows at least one connected, healthy provider and its models.
✓omniroute launch opens Claude Code without a gateway or authentication error.
✓Ask Claude Code a small question, then confirm the request appears in OmniRoute’s activity or logs with the expected requested and actual model.
✓If you created a combo, temporarily disable or reorder the first target and send another small request to confirm another target is used.

For a direct gateway check, your Endpoints screen provides the key needed to request http://localhost:20128/v1/models. Never share the real key in a screenshot or support message.

09
A sensible starting point

Recommended free setup

Starter recipe

Two independent options + auto/coding

Connect one provider that OmniRoute’s live dashboard currently marks as free or no-auth, then add a second free option from a different provider pool. Start Claude Code with auto/coding; only build a manual combo if you care about an exact order.

This setup is more resilient than adding several accounts that all depend on the same upstream service. Recheck each provider’s terms, privacy policy, data handling, and quota before sending private code.

No permanent quota promise: this guide intentionally does not hard-code a provider count or monthly token total. OmniRoute’s catalog and upstream free tiers change, so figures that are accurate today can be wrong later.

10
Common fixes

Troubleshooting

The dashboard does not open

Confirm the terminal running omniroute is still open and has not printed an error. Then visit http://localhost:20128 manually. If the port is already in use, stop the conflicting app or start OmniRoute on another port using its current CLI options.

omniroute is not recognized

Close and reopen your terminal after installation. If it still fails, check that npm’s global binary folder is on your system PATH, then reinstall the package without using an unrelated package named “omnirouter.”

Claude Code ignores OmniRoute

Exit Claude Code completely and relaunch it with omniroute launch. Claude Code reads gateway environment variables at startup. For manual configurations, ANTHROPIC_BASE_URL must be the root http://localhost:20128, not an address ending in /v1.

Authentication fails

Create or copy the local key from OmniRoute’s Endpoints screen. Profiles do not store the token; launch them with omniroute launch --profile PROFILE_NAME so OmniRoute can inject it safely.

The model picker is empty

First confirm models appear in OmniRoute. Then update Claude Code and relaunch it through OmniRoute. Some non-Anthropic model IDs may not appear in Claude Code’s native picker; use an OmniRoute profile or set the model through the launcher instead.

Fallback never happens

Confirm your combo contains at least two enabled targets, that the second target has working credentials and quota, and that Claude Code is actually using the combo’s model ID. Check OmniRoute’s logs for the requested and actual model.

A “free” provider asks for payment

Stop and check the provider’s current pricing page. Free access is controlled by the provider, not Promptdeck or OmniRoute. Choose another option shown by the live dashboard rather than assuming an old quota still exists.