Deploy OmniRoute

Deploy and Host OmniRoute on Railway

OmniRoute is an open-source AI gateway that puts one OpenAI-compatible /v1 endpoint in front of every model provider you use. Rather than scattering API keys, base URLs, retry logic, and spend tracking across each application, you connect your own provider credentials once and point every client at a single address. A Next.js dashboard sits on a routing engine handling provider selection, failover chains, format translation, prompt compression, rate limiting, and cost analytics. Self-host OmniRoute to keep credentials on infrastructure you control.

This template runs one Railway service, omniroute, from the official image diegosouzapw/omniroute:3.8.48. There is no database container — all state lives in SQLite, so a volume is mounted at /app/data with DATA_DIR set to match. HTTPS terminates at the Railway edge and forwards to port 20128, which serves /login and /dashboard for the UI and /v1/* for API traffic.

Getting Started with OmniRoute on Railway

Open the generated Railway domain; every unauthenticated path redirects to /login. OmniRoute is gated by one dashboard password rather than user accounts, so sign in with the generated INITIAL_PASSWORD from the Variables tab, then change it under Configuration → Security. A fresh gateway has no providers connected, so the first real step is Dashboard → Providers → add a provider and paste your own API key; this is a bring-your-own-key gateway and ships no credentials. Then open API Keys and issue a gateway key, since REQUIRE_API_KEY is true and every /v1 call must present one. Confirm the Endpoints page shows https:///v1, not localhost, then verify with /v1/models — it returns your models with a valid key and 401 without — and point any OpenAI SDK at that base URL.

About Hosting OmniRoute

Every model vendor brings its own SDK, auth scheme, error shape, rate limit, and billing portal, and that cost compounds the moment a codebase talks to more than one. Self-hosting fits when credentials must not leave your perimeter, when a team wants one shared endpoint with revocable per-client keys, or when you need routing policy hosted aggregators do not expose.

• OpenAI-compatible /v1 API — chat completions, model listing, and the Responses API, with format translation between provider shapes.
• Routing strategies and fallback combos — priority, weighted, round-robin, cost-optimised; combos chain providers so a failing upstream hands the request onward.
• Scoped keys, compression, and analytics — per-app keys you revoke without touching provider credentials, token trimming on long agent sessions, and per-provider cost and latency.

Why Deploy OmniRoute on Railway

Railway removes the plumbing around a self-hosted gateway.

• One-click deploy from the pinned diegosouzapw/omniroute:3.8.48 image.
• A volume at /app/data keeps SQLite state across restarts and redeploys.
• Free HTTPS domain with automatic TLS, so /v1 is reachable immediately.
• Usage-based pricing — pay for the CPU and RAM the gateway uses.
• Built-in logs, metrics, and one-click rollbacks.

Common Use Cases of OmniRoute

• A shared team gateway for coding agents. Point Claude Code, Codex CLI, Cursor, and Cline at one /v1 URL and rotate a vendor credential in one place, not a dozen editor configs.
• Multi-provider resilience. A fallback combo behind one model alias fails over to your secondary vendor instead of surfacing an outage.
• A stable endpoint in front of changing models. Apps call one base URL while the dashboard attributes token spend by provider, key, and application.

Dependencies for OmniRoute

• omniroute — diegosouzapw/omniroute:3.8.48, the official multi-arch (amd64/arm64) image. Dashboard and routing engine in one Node.js process on port 20128; the domain's target port must match or requests never reach the app.
• Volume at /app/data — storage.sqlite, db_backups/ (written before each migration), and logs/. First boot writes about 90 MB.

Two image lines ship per release: the base tag used here (3.8.48, ~460 MB) and -web (~915 MB), which only adds Chromium for browser-session providers. Pin a semver tag — latest and main move.

OmniRoute Environment Variables Reference

Deployment Dependencies

• diegosouzapw/omniroute — repo github.com/diegosouzapw/OmniRoute (MIT)
• Node.js 22+ bundled; SQLite via better-sqlite3

Hardware Requirements for Self-Hosting OmniRoute

Proxying is I/O-bound, so memory matters more than CPU. Set OMNIROUTE_MEMORY_MB to about half the container's limit — Node otherwise sizes its heap from the host's RAM, not the container's, and gets OOM-killed under load.

Self-Hosting OmniRoute with Docker

The same setup runs anywhere Docker does:

docker run -d --name omniroute --restart unless-stopped \
  --stop-timeout 40 -p 20128:20128 -v omniroute-data:/app/data \
  -e DATA_DIR=/app/data -e HOSTNAME=0.0.0.0 \
  -e NODE_ENV=production -e REQUIRE_API_KEY=true \
  -e INITIAL_PASSWORD="change-me-on-first-login" \
  -e JWT_SECRET="$(openssl rand -base64 48)" \
  -e API_KEY_SECRET="$(openssl rand -hex 32)" \
  diegosouzapw/omniroute:3.8.48

Keep the 40-second stop timeout — OmniRoute checkpoints SQLite on shutdown, and killing it early drops recent writes. Then confirm it answers:

curl -s https://your-app.up.railway.app/v1/chat/completions \
  -H "Authorization: Bearer YOUR_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"ping"}]}'

How Much Does OmniRoute Cost to Self-Host?

OmniRoute is free and MIT-licensed — no paid tier, seat charge, or per-request fee. Your real costs are the infrastructure it runs on and whatever your providers charge for the tokens you send; the gateway routes with your own API keys and never bills for inference. On Railway you pay usage-based pricing for CPU, memory, egress, and the volume — typically a few dollars a month for a small team.

Troubleshooting Self-Hosted OmniRoute on Railway

• State resets on every restart. The container could not write to the volume, so the app silently fell back to an in-memory database while still serving HTTP 200. Fix: set RAILWAY_RUN_UID=0, redeploy, then confirm a gateway key survives a restart — a green deploy is not proof of persistence.
• Keys or sessions break after redeploy. JWT_SECRET or API_KEY_SECRET changed; both must stay fixed.

FAQ

What is OmniRoute?

An open-source, MIT-licensed AI gateway exposing one OpenAI-compatible /v1 endpoint that routes to the providers you connect with your own API keys, plus a dashboard for routing rules, scoped keys, compression, and analytics.

What does this Railway template deploy?

One omniroute service from diegosouzapw/omniroute:3.8.48 on port 20128, with a volume at /app/data. Secrets are generated at deploy time, REQUIRE_API_KEY is true, and BASE_URL points at your Railway domain.

Why does this template use a volume instead of a Postgres database?

All state lives in a SQLite file under DATA_DIR, and this image has no Postgres driver path, so a managed database would add cost without being used.

How do I connect Claude Code, Cursor, or an OpenAI SDK to self-hosted OmniRoute?

Set the client's base URL to https:///v1 and its API key to a gateway key from the API Keys page. Any tool accepting a custom base URL works.

Do I need to bring my own provider API keys?

Yes. The gateway ships with no credentials and no providers connected, so /v1/chat/completions cannot route anything until you add a provider with your own key.