claude through omniroute

[maanyahack]

How to setup claude code for free through omniroute

[pacocartones]

The simplest supported path is:

1. In OmniRoute, connect at least one provider that currently offers a model you can
   use under its own free tier or credits.

2. Go to Endpoints and create an OmniRoute API key.

3. Install Claude Code if needed:

   npm install -g @anthropic-ai/claude-code

4. Start Claude Code through OmniRoute:

   omniroute launch

omniroute launch injects the correct ANTHROPIC_BASE_URL and
ANTHROPIC_AUTH_TOKEN values for the local OmniRoute instance.

If you want a specific model rather than the default routing behavior, generate the
available Claude Code profiles first:

omniroute setup-claude
omniroute launch --profile <profile-name>

For a remote OmniRoute instance, use:

omniroute launch --remote http://HOST:20128 --api-key YOUR_OMNIROUTE_KEY

One important clarification: OmniRoute itself does not make paid Claude models free.
"Free" depends on the upstream provider/model you connect, its current quota and its
terms. OmniRoute supplies the compatible gateway and routing layer.

If configuring Claude Code manually, use the OmniRoute root URL — no /v1 suffix:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_OMNIROUTE_KEY"
  }
}

Restart Claude Code after changing these values because it reads them at startup.

If omniroute launch fails, please paste the exact error plus the OmniRoute version
and selected provider/model, without including any API key.

[maanyahack]

Can I use claude desktop also via this??

[leon-lourenco]

Apparently not. You cannot invoke Claude Code Desktop via Omniroute; when you launch it, the environment variable defining the proxy URL used by the Claude CLI (since the Desktop app, plugins, etc., operate in "separate environments") is automatically set to Anthropic's default.

It seems that, as of now, there is no native way to use Claude Code Desktop with Omniroute.

[diegosouzapw]

@maanyahack Two separate things:

1. Claude Desktop's built-in chat cannot be pointed at OmniRoute as its model provider -- Anthropic doesn't offer a supported base-URL override in the desktop app's chat. (Claude Code can, via omniroute launch; the desktop app can't.)
2. What you can do is connect Claude Desktop to OmniRoute's MCP server, so OmniRoute's tools work inside Claude Desktop: add to claude_desktop_config.json:

{
  "mcpServers": {
    "omniroute": {
      "command": "omniroute",
      "args": ["--mcp"]
    }
  }
}

See docs/guides/USER_GUIDE.md -> "Connect Claude Desktop".

If the goal is free models in a desktop chat UI, use a client that accepts an OpenAI-compatible base URL (Open WebUI, LibreChat, Jan...) pointed at http://localhost:20128/v1 with an OmniRoute API key.

[leon-lourenco]

Hi @diegosouzapw

Thanks for this repository. I have a question:

I’m using Omniroute to access Claude. Even though I’m on the free tier, I still see my Claude quota being consumed. Could you clarify why?

I also don't quite understand how the free tier usage works. Should I add as many providers as possible to increase my limits? Is there a way to see exactly what my limits are for each model (when integrating via API key)? I ask because, quite often, I get a message indicating the provider returned a 400, 429, etc., and processing simply stops.

If you can point me in the right direction, I’ll gather the necessary screenshots so we can debug this together. I’m trying to get a better understanding of the project so I can contribute. Thanks.

Thanks.

[diegosouzapw]

Hey @leon-lourenco!

Why quota is still consumed on "free tier": OmniRoute doesn't create free Claude access -- it routes through whatever provider/connection you configured. If that connection is your own Anthropic account (even a free/trial one) or an OAuth-based Claude subscription, usage against that account's quota happens exactly as if you called Anthropic directly. "Free" only applies when the target model itself is offered free by the upstream provider (e.g. some if/*, qoder, qwen models in the FREE tier table in docs/guides/USER_GUIDE.md).

Adding more providers: Yes, that's the intended lever -- each connection you add is a separate quota pool. With 2+ connections to the same provider/model, use a combo strategy (fill-first, round-robin, priority, etc.) so OmniRoute automatically spreads requests and falls back when one account hits 429. See docs/routing/AUTO-COMBO.md for the strategy table.

Seeing your limits per model: Dashboard -> Providers -> your connection card shows current rate-limit/cooldown status (rateLimitedUntil, testStatus) live. There's no single "here's your remaining quota" number for API-key providers, since most upstreams don't expose that -- OmniRoute tracks it reactively from response headers/errors instead.

On the 400/429 stopping mid-processing: that's connection cooldown kicking in (docs/architecture/RESILIENCE_GUIDE.md -> "Connection Cooldown") -- a 429 on one connection puts it on a short backoff while others keep serving, but if you only have one connection for that model, there's nothing to fall back to and the request surfaces the error. If you hit this often, paste one full error body (redact the key) plus which combo/model you were using and I can tell you whether it's a cooldown, a circuit-breaker trip, or a genuine account-quota exhaustion -- they look different in the dashboard.

Happy to have you dig into the code too -- open-sse/services/accountFallback.ts and open-sse/services/combo.ts are the core of this behavior if you want a starting point.