README
¶
gomniroute
One local endpoint that speaks every major LLM wire protocol and fans requests out across ~200 upstream providers — as a single static binary with no dashboard, no daemons, and no native dependencies.
gomniroute serve # http://127.0.0.1:8787
gomniroute setup-claude # point Claude Code at it
gomniroute launch # or just launch Claude Code through it
What it is
A Go reimplementation of the routing core behind OmniRoute, built as a CLI product rather than a desktop one. The routing engine, provider catalog and resilience model carry over; the dashboard, the Electron wrapper and the background daemons do not.
| gomniroute | |
|---|---|
| Cold start to listening | 125 ms |
| Warm proxy overhead | ~1 ms |
| Idle memory | 27 MB |
| Install | one 15 MB binary, no runtime |
| Usage writes | batched, off the response path |
Those are measured, not projected. Cold start is dominated by parsing the embedded catalog on first use.
Not included: image, audio, video, music, OCR, rerank, moderation, batch and file endpoints; the WebSocket bridge; and any web or desktop interface. The MCP server exposes tools about this gateway — health, quota, routing, combos, usage — and nothing else.
Protocols
Every one of these is a first-class inbound format, translated to whatever the chosen upstream actually speaks:
POST /v1/chat/completions— OpenAI, and every SDK that targets itPOST /v1/messages— Anthropic Messages, which is what Claude Code usesPOST /v1/responses— OpenAI Responses, which is what Codex CLI usesPOST /v1beta/models/{model}:generateContent— GeminiGET /v1/models— discovery
Point any client's base URL at http://127.0.0.1:8787 and it works.
Providers
202 providers and 1,593 models, embedded in the binary. Four classes:
- API key — Mistral, Groq, Cerebras, OpenRouter, DeepSeek, and ~160 more
- OAuth subscription — Claude Code, Codex, GitHub Copilot, Kiro, Cursor, Windsurf and 13 others: sign in, no API key
- Keyless — providers that need no credential at all
- Web/cookie — browser-session providers, isolated and flagged
fragile; the binary runs fine without them
Routing
A request resolves to an ordered list of targets and walks it until one answers. How that list is ordered is the interesting part:
gomniroute combo create fast-cheap --strategy cost-optimized
gomniroute simulate 'auto/coding:free' # print the plan without dispatching
gomniroute explain-route 'claude-opus-5' # and why it's ordered that way
Twenty strategies, from priority (declaration order) through p2c,
headroom and quota-share to auto, which scores every candidate in the
catalog on thirteen weighted factors. Combos nest, so a shared fallback tail
is written once. simulate runs the real planner without sending anything,
because the planner is pure.
When something fails, three independent layers respond: a per-provider circuit
breaker, a per-account cooldown with backoff parsed from the upstream's own
Retry-After, and a per-account-per-model lockout for the case where one
model vanishes from an account that otherwise still works.
Free tiers
The catalog carries documented free allowances for 522 models across 20 providers, deduplicated by quota pool — models sharing a pool are counted once, which is the difference between a real number and a marketing one. Each provider also carries a terms-of-service verdict, because several free tiers prohibit exactly this kind of proxying.
gomniroute quota # what's left
gomniroute providers list --free
gomniroute is built for single-user local use. It is not a multi-tenant relay, and several providers' terms would forbid using it as one.
Getting started
go build -o bin/gomniroute ./cmd/gomniroute
gomniroute # no args: interactive menu
gomniroute connect mistral # paste an API key
gomniroute login claude # or sign in to a subscription
gomniroute status # what's configured and healthy
gomniroute serve
Then point a client at it:
gomniroute setup-claude # writes a Claude Code profile
gomniroute setup-codex # writes Codex CLI profiles
gomniroute launch # spawn Claude Code with the env injected
Everything lives in ~/.gomniroute: config.json, storage.sqlite, logs and
backups. Credentials are encrypted at rest.
Remote mode
Most CLI commands are clients of the management API, so they work identically against a gomniroute running somewhere else:
gomniroute contexts add work --base-url https://box.internal:8787
gomniroute --context work status
Documentation
- docs/ENVIRONMENT.md — environment variables
Install
brew tap kiliczsh/tap
brew install gomniroute
or with Go:
go install github.com/kiliczsh/gomniroute/cmd/gomniroute@latest
Or grab a prebuilt binary from the releases page — darwin/linux/windows,
amd64 and arm64, with SHA256 checksums. Installed binaries upgrade
themselves with gomniroute update --apply.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
gomniroute
command
Command gomniroute is a local-first router that fans a single gateway endpoint out across free-tier and paid LLM providers, coding agents point at directly instead of a single paid provider.
|
Command gomniroute is a local-first router that fans a single gateway endpoint out across free-tier and paid LLM providers, coding agents point at directly instead of a single paid provider. |
|
internal
|
|
|
agentsetup
Package agentsetup writes the configuration files coding agents read to find their model endpoint — gomniroute's main use case is standing in for a paid provider in front of a tool like Claude Code, Codex, or Cline.
|
Package agentsetup writes the configuration files coding agents read to find their model endpoint — gomniroute's main use case is standing in for a paid provider in front of a tool like Claude Code, Codex, or Cline. |
|
auth
Package auth authenticates inbound requests against gomniroute's own API keys, management password, and scoped CLI tokens, and drives outbound OAuth sign-in and token refresh for upstream provider accounts (see the oauth and refresh subpackages).
|
Package auth authenticates inbound requests against gomniroute's own API keys, management password, and scoped CLI tokens, and drives outbound OAuth sign-in and token refresh for upstream provider accounts (see the oauth and refresh subpackages). |
|
auth/oauth
Package oauth drives outbound sign-in to upstream provider accounts — Claude, Codex/ChatGPT, GitHub Copilot and the rest of the catalog's AuthOAuth providers — behind one uniform Provider contract, so the CLI's `auth login` command and the web management UI never need provider-specific branches beyond selecting which Provider to call.
|
Package oauth drives outbound sign-in to upstream provider accounts — Claude, Codex/ChatGPT, GitHub Copilot and the rest of the catalog's AuthOAuth providers — behind one uniform Provider contract, so the CLI's `auth login` command and the web management UI never need provider-specific branches beyond selecting which Provider to call. |
|
auth/refresh
Package refresh keeps OAuth-authenticated provider connections' access tokens valid, refreshing them ahead of expiry rather than discovering expiry as a failed chat request.
|
Package refresh keeps OAuth-authenticated provider connections' access tokens valid, refreshing them ahead of expiry rather than discovering expiry as a failed chat request. |
|
cli
Agent wires internal/agentsetup into the CLI — this is gomniroute's main use case: pointing a coding agent's config at the gateway instead of a paid provider directly.
|
Agent wires internal/agentsetup into the CLI — this is gomniroute's main use case: pointing a coding agent's config at the gateway instead of a paid provider directly. |
|
config
Package config owns gomniroute's on-disk configuration: where the data directory lives, the CLI context file, and .env loading.
|
Package config owns gomniroute's on-disk configuration: where the data directory lives, the CLI context file, and .env loading. |
|
executor
Package executor dispatches a translated request to an upstream provider over HTTP and returns its response as a stream.
|
Package executor dispatches a translated request to an upstream provider over HTTP and returns its response as a stream. |
|
logging
Package logging sets up gomniroute's process-wide slog.Logger: human readable on a terminal, structured JSON everywhere else (files, piped output, container logs), with size-based rotation into the data directory.
|
Package logging sets up gomniroute's process-wide slog.Logger: human readable on a terminal, structured JSON everywhere else (files, piped output, container logs), with size-based rotation into the data directory. |
|
mcp
Package mcp implements the Model Context Protocol server surface for gomniroute: an MCP client (Claude Code, an agent harness, an operator's own tooling) can inspect and drive routing, health, quota, cost and connection state through the same ~30 tools regardless of whether it talks to us over stdio or HTTP.
|
Package mcp implements the Model Context Protocol server surface for gomniroute: an MCP client (Claude Code, an agent harness, an operator's own tooling) can inspect and drive routing, health, quota, cost and connection state through the same ~30 tools regardless of whether it talks to us over stdio or HTTP. |
|
quota
Package quota tracks how much of each provider account's rate limit and free-tier allowance is left, so the router can skip an exhausted account before spending a round-trip discovering it, and can cap concurrency against a provider's real limit instead of learning it from 429s.
|
Package quota tracks how much of each provider account's rate limit and free-tier allowance is left, so the router can skip an exhausted account before spending a round-trip discovering it, and can cap concurrency against a provider's real limit instead of learning it from 429s. |
|
registry
Package registry holds gomniroute's provider catalog: the ~200 upstream providers it can route to, their wire formats, auth shapes, endpoints and model lists.
|
Package registry holds gomniroute's provider catalog: the ~200 upstream providers it can route to, their wire formats, auth shapes, endpoints and model lists. |
|
resilience
Package resilience turns raw upstream failures into routing decisions: what kind of error this was, whether it is worth retrying, and how long to back off before trying this account (or this provider) again.
|
Package resilience turns raw upstream failures into routing decisions: what kind of error this was, whether it is worth retrying, and how long to back off before trying this account (or this provider) again. |
|
route
Package route turns a client's requested model into an ordered list of concrete provider+account+model targets to try.
|
Package route turns a client's requested model into an ordered list of concrete provider+account+model targets to try. |
|
server
Package server implements gomniroute's HTTP surface: the multi-format inference gateway (OpenAI, Anthropic, Gemini, OpenAI Responses) and the management REST API the CLI and TUI drive.
|
Package server implements gomniroute's HTTP surface: the multi-format inference gateway (OpenAI, Anthropic, Gemini, OpenAI Responses) and the management REST API the CLI and TUI drive. |
|
sse
Package sse implements Server-Sent Events framing, streaming transforms, and the provider-facing correctness helpers gomniroute needs to relay a long-lived upstream stream to a client that may speak a different wire format, may have already disconnected, or may be waiting through a long prefill with nothing to read.
|
Package sse implements Server-Sent Events framing, streaming transforms, and the provider-facing correctness helpers gomniroute needs to relay a long-lived upstream stream to a client that may speak a different wire format, may have already disconnected, or may be waiting through a long prefill with nothing to read. |
|
store
Package store is gomniroute's persistence layer: a single SQLite file holding provider accounts, routing plans, health state and usage history.
|
Package store is gomniroute's persistence layer: a single SQLite file holding provider accounts, routing plans, health state and usage history. |
|
style
Package style centralizes gomniroute's terminal look — one place to keep the CLI's colors/spacing consistent instead of scattering lipgloss calls through every command.
|
Package style centralizes gomniroute's terminal look — one place to keep the CLI's colors/spacing consistent instead of scattering lipgloss calls through every command. |
|
translator
Package translator converts chat-completion requests and responses between the wire formats gomniroute's supported clients and providers speak (OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, Gemini generateContent, and the CLI-agent variants that ride on top of them).
|
Package translator converts chat-completion requests and responses between the wire formats gomniroute's supported clients and providers speak (OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, Gemini generateContent, and the CLI-agent variants that ride on top of them). |
|
tui
App is gomniroute's full-screen operator shell: a persistent frame — title bar, action menu, status block, help bar — around one swappable pane.
|
App is gomniroute's full-screen operator shell: a persistent frame — title bar, action menu, status block, help bar — around one swappable pane. |
|
usage
Package usage turns raw usage_history rows into cost, budget and reporting decisions: what a request cost, what a caller has left to spend, and how spend/latency/errors break down by provider, model and day.
|
Package usage turns raw usage_history rows into cost, budget and reporting decisions: what a request cost, what a caller has left to spend, and how spend/latency/errors break down by provider, model and day. |
|
webprov
Package webprov holds the web/cookie provider class: upstream providers whose only public surface is a browser-facing website rather than a documented API, driven either through a TLS-fingerprinted HTTP client impersonating a real browser (utls.go) or, when that alone is not enough to pass a provider's bot checks, an actual browser (browser.go).
|
Package webprov holds the web/cookie provider class: upstream providers whose only public surface is a browser-facing website rather than a documented API, driven either through a TLS-fingerprinted HTTP client impersonating a real browser (utls.go) or, when that alone is not enough to pass a provider's bot checks, an actual browser (browser.go). |
Click to show internal directories.
Click to hide internal directories.