Self-hosting
Self-host OmniRoute on a VPS with Docker
OmniRoute is free, but it only answers while a machine keeps it running. This guide follows the project's official self-host flow and turns it into an always-on gateway on a small Linux VPS, with the security steps to do first and the RAM each workload needs.
- Platform
- OmniRoute
- Best for
- Developers and creators who want free or low-cost access to many LLM providers without juggling separate API keys, subscriptions, and rate limits.
- Hands-on
- Controlled benchmark pending
Quick answer
Use OmniRoute's official self-host Compose file (OmniRoute plus Redis, loopback-only) on any Linux VPS with Docker. Before anything else set REQUIRE_API_KEY=true, read the generated INITIAL_PASSWORD from the logs, and keep port 20128 on 127.0.0.1 behind an HTTPS reverse proxy such as Caddy. Plan for at least 2 GB of RAM for the dashboard and light chat, and about 10 GB or more if coding agents like Claude Code or Codex run through it.
Starting point: Free and open source (MIT). · Free tier: Yes — Entirely free and open source (MIT, github.com/diegosouzapw/OmniRoute).
This evaluation is built on verified documentation and official pricing data, paired with a repeatable test workflow you can run directly in your own project.
Worth evaluating when
- Developers who already route Claude Code, Cursor or Codex through OmniRoute on a laptop and want it reachable around the clock
- Anyone who chose OmniRoute over a hosted gateway such as OpenRouter and needs somewhere to run it
- Small teams sharing one gateway and its pooled free tiers
Check before paying
- With REQUIRE_API_KEY=false (the default) and a public bind, anyone who finds the port can spend your provider quotas
- Coding agents need far more memory than the 1 GB default heap; undersized servers crash with a V8 heap error
- Free provider tiers have their own terms and limits; OmniRoute pools them but does not change them
- You own uptime, backups and upgrades; there is no vendor SLA
Why run OmniRoute on a VPS
OmniRoute is a free, MIT-licensed gateway that puts hundreds of providers, including many free tiers, behind one OpenAI-compatible endpoint with automatic fallback. It is a server: when your laptop sleeps or changes network, every tool pointed at http://localhost:20128/v1 stops working.
A small Linux VPS keeps the gateway online for a fixed monthly price. You still pay providers directly, or use their free tiers; the VPS is the only fixed cost, which is the trade-off versus a hosted pay-as-you-go gateway such as OpenRouter.
How much server you need
OmniRoute's own sizing table: the dashboard and light chat run on the image's default 1 GB heap in a container with at least 2 GB of RAM. One coding agent using /v1/responses (Claude Code, Codex and similar) needs about an 8 GB heap in a container of 10 GB or more, and two long concurrent agent sessions need 12 to 16 GB.
Matched to Hostinger's VPS line as checked on October 4, 2026: KVM 1 (1 vCPU, 4 GB RAM, 50 GB NVMe) covers the dashboard and chat use; KVM 2 (2 vCPU, 8 GB) fits a moderate heap of around 4 GB; KVM 4 (4 vCPU, 16 GB) is the first plan with room for a coding agent. Introductory prices were $6.49, $8.99 and $12.99 a month on a two-year term, renewing at $11.99, $14.99 and $28.99. Any provider's Linux VPS with the same RAM works the same way.
Install with the official self-host Compose file
From release v3.8.51 OmniRoute ships a one-command self-host setup: a Compose file that runs the published image plus Redis, bound to localhost only. On the server, in an empty directory: set BASE=https://raw.githubusercontent.com/diegosouzapw/OmniRoute/v3.8.51, download $BASE/docker-compose.selfhost.yml and $BASE/.env.selfhost.example with curl -fsSLO, then cp.env.selfhost.example.env.
Edit two lines in.env: REQUIRE_API_KEY=true and APP_BIND_HOST=127.0.0.1. Then start it with docker compose -f docker-compose.selfhost.yml up -d, and check health with curl -fsS http://127.0.0.1:20128/healthz, which should return {"status":"ok"}.
With the API key requirement on, the dashboard generates an INITIAL_PASSWORD on first boot. Read it with docker logs omniroute | grep -i password, log in, and change it. If you ever lose it, docker exec -it omniroute node bin/reset-password.mjs resets it.
Lock it down before you rely on it
Port 20128 serves both the dashboard and the /v1 proxy. The project's own rule is to never bind it to 0.0.0.0 while REQUIRE_API_KEY is false, because that publishes an open proxy that spends your provider quotas. The safer pattern is to leave APP_BIND_HOST at 127.0.0.1 and put Caddy or Traefik in front for HTTPS on your domain; OmniRoute's Docker guide includes a Caddy example that provisions certificates automatically.
Allow only SSH and HTTPS in the VPS firewall. Redis is not published to the host by default; keep it that way. Mint scoped tokens (read, write or admin) for each machine or teammate instead of sharing the dashboard password; OmniRoute's remote mode lets your laptop's CLI drive the server with such a token.
Point your tools at the server
Add providers in the dashboard under Providers; keys are encrypted at rest. Then set your IDE or agent's OpenAI base URL to https://your-domain/v1 (or http://127.0.0.1:20128/v1 over an SSH tunnel) with an OmniRoute API key in the Authorization header. Using model auto lets OmniRoute pick a healthy provider per request.
Raise OMNIROUTE_MEMORY_MB in.env if you see FATAL ERROR: Reached heap limit, and size the server a few hundred MB above the heap.
Backups and updates
All state lives in the./data directory: SQLite databases, audit trail and encrypted provider keys. SQLite auto-backup is on by default; copy./data off the server on a schedule as well.
The latest image tag follows the newest stable release. For a server you depend on, pin a version tag, read the release notes, then pull and restart. Test new versions on the dashboard before pointing agents at them.
Run it 24/7 on your own server
OmniRoute runs on your own machine, so it stops answering when your laptop sleeps. A small Linux VPS with Docker keeps it online for scripts, agents and teammates, with a fixed monthly cost instead of per-token markup.
- Start with the smallest plan that runs Docker; upgrade only if you add users or local models.
- Keep the gateway bound to localhost or behind a firewall, and store provider keys as environment variables.
- Monthly billing lets you test before committing to a long term.
Some links are affiliate links. We may earn a commission if you buy through them. Payment never changes our rankings or editorial verdicts.
Related comparisons
Compare OmniRoute against the tools creators most often weigh it against.
Related guides
More AI Gateway workflows from the same verified catalog.
Run a same-input test
Start on the smallest plan that fits
Use about 4 GB of RAM for chat use, 16 GB if coding agents will run through it.
Lock it before exposing it
Set REQUIRE_API_KEY=true, keep 127.0.0.1, and put HTTPS in front before any tool connects from outside.
Verify health and memory
Check /healthz, then watch memory under your real agent workload and raise OMNIROUTE_MEMORY_MB if needed.
Official sources
These external sources support the product and pricing record. Recheck them before purchasing because plans and limits change.
Frequently asked questions
Is OmniRoute free to self-host?
Yes. OmniRoute is MIT-licensed open source with no subscription. Your costs are the server and any paid providers you connect; free provider tiers stay free under their own limits.
How much RAM does OmniRoute need?
Per the project's sizing table, at least 2 GB for the dashboard and light chat, about 10 GB for one coding agent, and 12 to 16 GB for two long concurrent agent sessions.
Which port does OmniRoute use?
Port 20128 serves the dashboard and the /v1 proxy, 20129 the server-to-server API and 20132 live WebSocket updates. The self-host setup binds all three to 127.0.0.1.
Is it safe to expose OmniRoute to the internet?
Only after setting REQUIRE_API_KEY=true and logging in with the generated password, and preferably behind an HTTPS reverse proxy with port 20128 kept on localhost.