OmniRoute is a free, open-source gateway that sits between Hermes and every AI provider. One config file gives your Hermes agents access to 452 models — 90 of them free — with automatic token compression. Here's the exact setup, tested end to end.
OmniRoute is a small program that runs on your computer at localhost:20128. Think of it as a smart post office that knows how to reach every AI provider out there.
Normally, Hermes talks to one provider. You pay for every token, and if that provider goes down or rate-limits you, your agents stop.
With OmniRoute in the middle, Hermes talks to the gateway instead. The gateway compresses your request, picks a provider, and forwards it. If a model fails or runs out of quota, it moves to the next one automatically. Hermes never notices.
Three useful things happen on every request:
Your agents, prompts and commands all stay the same. Only the path changes — and most of the bill goes away.
Here's the full journey between typing a message in Hermes and getting an answer back.
Nothing changes on your end. Your commands, agents and prompts all work exactly as they do now.
Instead of going to a provider's API directly, Hermes sends the request to OmniRoute running on your machine.
Two compression engines run back to back. RTK cleans up repetitive tool output, Caveman trims wordy text. Together they cut 15–95% of the tokens before anything leaves your machine.
The profile's default is auto/coding:free — OmniRoute looks at your connected providers and picks the best free coding model that's healthy and has quota left. If one fails, it moves to the next.
The response streams back through OmniRoute to Hermes. To you it looks like a normal Hermes reply.
OmniRoute keeps its config in ~/.omniroute/. The Hermes profile lives in its own folder. Your existing Hermes setup stays untouched.
This guide is based on the OmniRoute repo and docs. Here's everything worth bookmarking:
Fair questions. Here's the honest picture before you spend 30 minutes on the setup.
The setup you're about to build has four parts. Each one does a specific job.
OmniRoute runs at localhost:20128 and connects to every provider. It's local, so it never goes down unless you close it.
RTK + Caveman cut 15–95% of tokens automatically on every request. No configuration needed.
452 models across 237 providers, 90+ free. Change one word in the config to switch.
A small Hermes config folder. Your existing setup stays untouched — switch in and out with one flag.
OmniRoute is an npm package. You install it once and it runs on your machine — no Docker, no server, no subscription.
npm install -g omnirouteThen start the gateway:
omniroute serve --no-open --no-trayThe --no-open flag stops OmniRoute from opening a browser tab every time it starts — worth having if it ever restarts on its own.
Now open http://localhost:20128 in your browser and set an admin password. The gateway is live.
You can register OmniRoute as a background service so it launches on boot and stays running. Set it up once in your system's launch agents and forget about it.
It's two commands and a password. If you've ever installed anything with npm, this is the same thing. The Hermes side in step 3 is two small text files.
OmniRoute connects to providers through its dashboard. Start with the free-forever ones — some don't even need a signup.
Open the dashboard → Providers. These cost nothing and stay that way:
oc/big-pickle, the model I verified this whole setup on.Click one, hit Connect, done. Connect two or three so the auto-routing has options to fall back across.
If you also want cheap paid frontier models for the occasional heavy task, grab a free key at openrouter.ai/keys and add it the same way. It unlocks 353 more models. Totally optional — the free stack runs Hermes fine without it.
Hermes needs a key to talk to OmniRoute. Create one in the dashboard (Settings → API Keys → Create) or from the terminal:
omniroute keys add hermes-profileCopy it — you'll paste it into a file in the next step.
Good enough that I ran the full Hermes agent loop on one — tool calls, shell commands, real agent work — and it handled everything. The free stack includes DeepSeek-R1, Kimi-K2, and Claude-class models on Kiro.
For the occasional task that really needs a frontier model, that's what the optional OpenRouter connection is for — and the compression cuts that bill too.
A Hermes profile is two files in one folder. One sets the routing, one holds the key.
Create ~/.hermes/profiles/omniroute/config.yaml:
model:
default: auto/coding:free
provider: openrouter
base_url: http://localhost:20128/v1
api_mode: chat_completions
credential_pool_strategies:
openrouter: fill_first
toolsets:
- hermes-cli
max_live_sessions: 16
agent:
max_turns: 90
gateway_timeout: 1800The important line is base_url — that's what sends Hermes to OmniRoute instead of a provider. And auto/coding:free means OmniRoute picks the best free coding model available.
Create ~/.hermes/profiles/omniroute/auth.json:
{
"version": 1,
"active_provider": "openrouter",
"credential_pool": {
"openrouter": [{
"id": "omniroute-gateway",
"label": "OmniRoute Gateway",
"auth_type": "api_key",
"priority": 0,
"access_token": "YOUR_OMNIROUTE_API_KEY_HERE",
"base_url": "http://localhost:20128/v1"
}]
}
}Paste the key from step 2 where it says YOUR_OMNIROUTE_API_KEY_HERE. This is OmniRoute's internal key — the gateway holds the actual provider keys itself.
hermes -p omnirouteHermes starts, reads the profile, and routes everything through the gateway. I tested the full agent loop this way — tool calls and shell commands, on free models, $0 spent.
If you'd rather have a one-word command:
hermes profile alias omnirouteNow typing omniroute in any terminal launches Hermes on the free gateway.
No. Profiles are fully separate. The omniroute profile only runs when you pass -p omniroute — your normal hermes command keeps using your default profile exactly as before.
Change the default: line in config.yaml, save, and start a new session. That's the whole process.
# Best free coding model, with automatic fallback — the default
default: auto/coding:free
# A specific free-forever model (OpenCode Zen)
default: oc/big-pickle
# Cheapest working model from everything connected
default: auto/cheapThe auto/ routes are OmniRoute's smart router. It scores your connected providers on health, quota and speed, then picks. If a model hits a limit mid-session, the route moves to the next one and you never see an error.
# Claude Haiku — cheap frontier model, still compressed
default: openrouter/anthropic/claude-haiku-4.5
# Claude Sonnet — for heavy reasoning work
default: openrouter/anthropic/claude-sonnet-4.6One tip from testing: skip auto/best-free as a Hermes default. It can pick free models that don't support tool-calling, and Hermes needs tools. The auto/coding:* routes only pick tool-capable models.
Two reasons. The compression cuts 15–95% of your tokens before they reach Anthropic, so your existing bill shrinks. And for tasks where Claude is overkill — summaries, drafts, quick lookups — a free model does the job and saves your Claude quota for work that needs it.
You don't configure anything — it runs on every request through the gateway. But it helps to know what it's doing.
Agent sessions are full of repetitive content — build logs, test output, git diffs, file listings. RTK filters and deduplicates all of it before it gets sent.
Then Caveman compresses the prose — filler words, redundant phrasing, anything that carries no meaning. Code blocks, URLs and structured data are always preserved exactly.
It depends on your sessions. Short one-off questions save around 15–30%. Long agent sessions with lots of repeated context save 60–95%. The OmniRoute dashboard shows the compression ratio on every request, so you can watch it live at localhost:20128.
The engines only remove things the model doesn't need — repeated boilerplate, filler words, duplicate tool output. Code and data pass through byte-for-byte. The model gets the same information in fewer tokens.
Everything in this guide is part of the Agent OS — the full system I run my business on. Inside the AI Profit Boardroom you get it pre-wired, plus the people to help when something doesn't work first try.
The Boardroom is 4,000+ founders and operators — agency owners, ecom founders, course creators — running this kind of stack in their own businesses. So far, 258 wins have been documented across 38 countries.
Members post their wins as they happen — cost savings, first agents shipped, client work automated. They're all collected in one doc you can read right now.
Read the member wins doc (158 pages) →90+ free models through one endpoint. The bulk of your Hermes usage costs nothing.
When you do use a paid model, compression cuts the tokens 15–95% first.
Switch with one word in a config file. Automatic fallback when anything fails.
It's a separate profile. Use -p omniroute when you want it, plain hermes when you don't.
The Free Hermes Engine™ handles your model costs. The rest of the Agent OS handles everything else — agents that work overnight on a kanban board, every AI tool you already use wired into one dashboard, and local models for work that should never touch an API.
If you'd rather build it with help than figure it out alone, that's what the Boardroom is for. 3,600+ people are already inside, and with five live calls a week you're never stuck for long.
Join the AI Profit Boardroom → skool.com/ai-profit-lab258 documented member wins · 38 countries · 5 live calls a week
