--- title: "Deploy OmniRoute" description: "One AI endpoint for coding tools with quota-aware fallback." category: "AI/ML" url: https://railway.com/deploy/omniroute-3 --- # Deploy OmniRoute One AI endpoint for coding tools with quota-aware fallback. **[Deploy OmniRoute on Railway](https://railway.com/template/omniroute-3)** Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/omniroute-3/manifest.json - **Creator:** onepush - **Category:** AI/ML ## Template content ### omniroute - **Image:** diegosouzapw/omniroute:3.8.51@sha256:8bd462c9f60d8eda79329cfbb6ea7ea723505fe7721beb944f3d43835409e218 - **Start command:** `/bin/sh -c "mkdir -p /app/data && chown -R 1000:1000 /app/data && cd /app && if command -v setpriv >/dev/null 2>&1; then exec setpriv --reuid=1000 --regid=1000 --init-groups env HOME=/home/node /app/check-permissions.sh node dev/run-standalone.mjs; else exec /app/check-permissions.sh node dev/run-standalone.mjs; fi"` - **Health check:** /healthz - **Public domain:** Yes ## Documentation # Deploy and Host self hosted OmniRoute (Open-Source AI Gateway) on Railway OmniRoute turns your provider accounts into one endpoint for Claude Code, Codex, Cursor, Cline, and other coding tools, with fallback, routing strategies, and token compression. This Railway template pins the 3.8.51 image by digest, keeps state on a volume at /app/data, and generates every secret, so there is nothing to configure. ## About Hosting OmniRoute open-source software on Railway (self hosted OmniRoute template) The template runs one service: diegosouzapw/omniroute:3.8.51, the latest stable release, pinned by digest instead of the mutable :latest tag. It listens on port 20128, answers health checks at /healthz, and stores everything in SQLite (WAL mode) on the /app/data volume. Provider credentials are encrypted at rest with AES-256-GCM. There is no Postgres or Redis to run. Other OmniRoute templates exist on Railway. This one's edge is boring on purpose: a fixed build that never drifts on redeploy, a volume so keys and settings survive, and generated secrets so the first thing you do is log in. ## Why Deploy OmniRoute, the OpenRouter alternative on Railway (Railway Free Trial) OpenRouter is a hosted marketplace: you buy credits and it picks the provider. OmniRoute is MIT licensed software you run yourself, with your own accounts and keys, your own routing rules, and usage data on your own volume. Railway's $5 trial is enough to deploy it, connect a provider, and point a coding tool at it. Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it. By deploying OmniRoute on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway. ### Railway vs Other Hosting Providers and VPS for OmniRoute self hosting | Provider | What You Get with Railway | What You Get with the Other Provider | |---|---|---| | DigitalOcean | HTTPS domain, volume, and secrets set up by the template | A Droplet where you install Docker, TLS, and backups yourself | | AWS | One service, per-second billing, no IAM or load balancer | EC2 or ECS plus EBS, security groups, and IAM for one container | | Hetzner | No OS patching or reverse proxy to maintain | The cheapest RAM per euro, with all admin work on you | ## Common Use Cases for hosted OmniRoute - **One endpoint for every machine:** laptop, desktop, and cloud dev boxes share the same providers, keys, and history. - **Quota-aware fallback:** route subscription first, then API keys, then cheap models, then free tiers, with circuit breakers and key cooldowns when something fails. - **Token compression:** RTK and Caveman compress tool output before it reaches the model. The project claims 15-95% savings on eligible workloads; measure your own. - **Free-tier pooling:** connect the free tiers you are eligible for; model "auto" builds a virtual combo from what is connected. - **Agent plumbing:** the built-in MCP server and A2A support let agents call OmniRoute as a tool, not just as an API. ## Dependencies for OmniRoute Docker hosted on Railway OmniRoute is a single TypeScript and Next.js 16 app on Node.js. Its only hard dependencies are the container image, a writable volume for SQLite, and outbound HTTPS to providers. Railway supplies the public domain and TLS, and the template fills every variable before first boot. ### Deployment Dependencies for Managed OmniRoute Service (AI Gateway) - **Image:** diegosouzapw/omniroute:3.8.51, pinned by digest, multi-arch amd64 and arm64. - **Port and health:** 20128, health check at /healthz. Dashboard at /dashboard, API at /v1. - **Volume:** /app/data holds the SQLite database and encrypted provider keys. Deleting it resets the instance. - **Generated secrets:** INITIAL_PASSWORD, JWT_SECRET, API_KEY_SECRET, OMNIROUTE_WS_BRIDGE_SECRET, MACHINE_ID_SALT. - **Fixed values:** PORT=20128, HOSTNAME=0.0.0.0, DATA_DIR=/app/data, BASE_URL and NEXT_PUBLIC_BASE_URL on the public domain, AUTH_COOKIE_SECURE=true, REQUIRE_API_KEY=true, OMNIROUTE_MEMORY_MB. ### Implementation Details for OmniRoute (Using OmniRoute official docker image) REQUIRE_API_KEY=true means every /v1 request needs a Bearer key from the dashboard, which matters because the service is on the public internet. The /v1 surface speaks OpenAI, Claude, Gemini, and Responses API formats. OMNIROUTE_MEMORY_MB sets the Node heap. Upstream says the 1024 MB image default is fine for the dashboard and light chat, but coding agents that use /v1/responses (Claude Code, Codex) need around 8192 MB of heap and a 10 GB container. Raise the variable and the Railway memory limit together; raising only the heap gets the process killed. ## How does OmniRoute compare against other AI gateway platforms ### OmniRoute vs 9Router - **Scope:** OmniRoute has the larger catalog (372 providers listed), 19 routing strategies, MCP, and A2A. 9Router is smaller and simpler. - **Shared ground:** Both are MIT, both run as one container with SQLite on port 20128, and both ship RTK token compression. - **Weight:** 9Router is lighter on memory. OmniRoute's extra features cost RAM under agent load. ### OmniRoute vs LiteLLM - **Stack:** OmniRoute is TypeScript; LiteLLM is a Python proxy with an MIT core and paid enterprise features. - **Storage:** LiteLLM uses Postgres for virtual keys, teams, and budgets. OmniRoute keeps everything in SQLite. - **Fit:** LiteLLM is stronger for multi-team budgets and spend controls. OmniRoute targets coding tools, subscriptions, and free-tier fallback. ### OmniRoute vs OpenRouter - **Hosting:** OpenRouter is SaaS only. OmniRoute is self-hosted. - **Billing:** OpenRouter sells credits and charges a fee on top. OmniRoute adds no margin; you pay providers and Railway. - **Control:** OpenRouter picks among its providers for you. OmniRoute lets you set strategies and fallback order across your own accounts. ### OmniRoute vs CLIProxyAPI - **Purpose:** CLIProxyAPI is a Go proxy that exposes CLI subscriptions like Gemini CLI, Codex, and Claude Code as an API. - **Breadth:** OmniRoute also connects subscriptions, then adds API keys, free tiers, compression, analytics, and a dashboard. - **Weight:** CLIProxyAPI is leaner if subscription bridging is all you need. ## How to use OmniRoute (the OSS AI gateway)? 1. Deploy the template and wait for /healthz to pass. 2. Copy INITIAL_PASSWORD from the service variables, open /dashboard, log in, and change it. 3. Connect providers: subscriptions, API keys, or free tiers you are eligible for. Providers flagged tos: avoid stay out of auto routing by default. 4. Create an API key, since REQUIRE_API_KEY is on. 5. Point your tool at https://your-domain/v1 with that key, and use model "auto" or a specific model. ## How to self host OmniRoute on other VPS Services (OmniRoute self hosting guide) ### Clone the Repository Run `git clone https://github.com/diegosouzapw/OmniRoute.git`, or skip source entirely and use `npm install -g omniroute` or the Docker image. ### Install Dependencies Install Docker, or Node.js 22 or 24 for npm and source builds. Docker avoids native module builds. ### Configure Environment Variables Set PORT, HOSTNAME, DATA_DIR, BASE_URL, INITIAL_PASSWORD, JWT_SECRET, API_KEY_SECRET, and MACHINE_ID_SALT (generate secrets with `openssl rand -hex 32`). On a public host, set AUTH_COOKIE_SECURE=true and REQUIRE_API_KEY=true, and size OMNIROUTE_MEMORY_MB for your workload. ### Start the OmniRoute Application Run `docker run -d -p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:3.8.51` with your env vars, then put Caddy or Nginx with TLS in front of port 20128. ## Official Pricing of OmniRoute (OmniRoute pricing) OmniRoute is MIT licensed and free. There is no paid plan, license key, or token markup. You pay your providers directly and pay for hosting. The free-tier totals in the README are estimates across third-party providers, each with its own limits and terms. ## OmniRoute cloud vs self hosted comparison (Pricing, features, costs, and more) There is no official managed OmniRoute cloud; self-hosting is the product. The real comparison is against hosted routers like OpenRouter: you trade a few minutes of setup for key custody, routing control, and no margin. ### Monthly cost of self hosting OmniRoute on Railway Railway bills per second for RAM, CPU, and storage. Light single-user use at 1-2 GB of RAM typically runs about $5-20 a month. Sizing up to 10 GB for coding agents costs much more, so raise memory only if you run agents through /v1/responses. ### System Requirements for Hosting OmniRoute on a VPS Dashboard and light chat: 1 vCPU and 2 GB of RAM. One coding agent: about 10 GB of RAM with an 8192 MB heap, per upstream docs. Disk is small; the SQLite database is usually tiny. ## Frequently Asked Questions (FAQs) ### Is OmniRoute free? Yes. It is MIT licensed with no paid tier. You pay providers and hosting. ### Where is the OmniRoute password on Railway? In the service variables as INITIAL_PASSWORD, generated per deploy. Change it after the first login. ### Why does OmniRoute crash under Claude Code or Codex? The heap is too small. Raise OMNIROUTE_MEMORY_MB and the Railway memory limit together, as the upstream Docker guide describes. ### Why do my tools get 401 errors? REQUIRE_API_KEY is on. Create a key in the dashboard and send it as the Bearer token. ### How do I update OmniRoute? Change the pinned tag to a newer release and redeploy. The /app/data volume carries your settings over. ### Is routing through free tiers and subscriptions allowed? It depends on each provider's terms. OmniRoute flags risky providers and keeps them out of auto routing by default. ## Similar templates - [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform. - [stella](https://railway.com/deploy/stella) — Self-host stella with web, API, Postgres, Redis, and object storage. - [Hermes Agent | OpenClaw Alternative with Dashboard](https://railway.com/deploy/hermes-agent-or-openclaw-alternative-wit) — Self-Hosted Hermes AI Agent for Telegram, Discord & Slack Open this page in a browser: https://railway.com/deploy/omniroute-3