---
title: "Deploy OmniRoute OpenCode"
description: "Route the OpenCode agent through your own OmniRoute gateway"
category: "AI/ML"
url: https://railway.com/deploy/deploy-omniroute-for-opencode
---

# Deploy OmniRoute OpenCode

Route the OpenCode agent through your own OmniRoute gateway

**[Deploy OmniRoute OpenCode on Railway](https://railway.com/template/deploy-omniroute-for-opencode)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/deploy-omniroute-for-opencode/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 OpenCode (Self-Hosted AI Gateway for OpenCode) on Railway

This template deploys one OmniRoute service on Railway, giving the OpenCode terminal agent a single OpenAI-compatible /v1 endpoint on your own domain.

## About Hosting OmniRoute OpenCode open-source software on Railway (self hosted self-hosted OmniRoute gateway for the OpenCode terminal agent template)

This template runs one service, the official diegosouzapw/omniroute image pinned to 3.8.51, on port 20128 with a /healthz check.

Railway handles the build, the public HTTPS domain, the volume, and restarts.

## Why Deploy OmniRoute OpenCode, the OpenRouter alternative on Railway (Railway Free Trial)

OpenRouter routes every request through their service and adds a markup on top of model costs. Railway's $5 trial covers a first test of OpenCode before you commit to a monthly plan.

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 OpenCode 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 OpenCode self hosting

Railway gives you the container, a persistent volume and a public HTTPS domain without server work, which is what OpenCode needs for a stable /v1 endpoint.

| Provider | What You Get with Railway | What You Get with the Other Provider |
| --- | --- | --- |
| DigitalOcean | A one-click template with a public domain, generated secrets and a volume at /app/data. | A droplet you patch and firewall yourself, plus your own proxy and TLS for /v1. |
| AWS | One service with the /healthz check and no VPC or IAM setup first. | Fine-grained networking and scaling, but much more setup before OpenCode connects. |
| Hetzner | Managed deploys from the template, with no SSH or Docker install step. | Cheap fixed-price servers, but you handle OS updates, backups of /app/data and certificates. |

## Common Use Cases for hosted OmniRoute OpenCode

- **One endpoint for OpenCode:** Point OpenCode at a single self-hosted /v1 endpoint on your Railway domain instead of managing separate provider keys in every config. The OmniRoute API key is the only credential the agent needs.
- **Thinking variants for hard tasks:** For a tough refactor, run `opencode run "your prompt" --model omniroute/auto/coding --variant high` to use a thinking variant. Keep the default for quick edits.
- **Fallback on rate limits:** When one provider starts returning rate limit errors, the auto/fast or auto/coding combos can route to the next available model. You keep working without editing the OpenCode config.
- **Your own keys and routing:** Provider keys stay encrypted in SQLite on your own Railway service, so requests never depend on a third-party hosted model service.
- **Comparing output quality:** Switch the model string between providers and test the same coding task. The agent config stays the same, so the model is the only variable.

## Dependencies for OmniRoute OpenCode Docker hosted on Railway

This template runs as one Railway service built from the official OmniRoute Docker image, so there is nothing else to provision for the gateway.

### Deployment Dependencies for Managed OmniRoute OpenCode Service (AI Gateway)

The only service is `diegosouzapw/omniroute:3.8.51`, pinned to a digest, on port 20128 with health at `/healthz`. You bring your own provider accounts.

### Implementation Details for OmniRoute OpenCode (Using OmniRoute official docker image)

Fixed variables are `PORT=20128`, `HOSTNAME=0.0.0.0`, `DATA_DIR=/app/data`, `NEXT_PUBLIC_BASE_URL` and `BASE_URL` set to your public domain, `AUTH_COOKIE_SECURE=true`, and `REQUIRE_API_KEY=true`.

## How does OmniRoute OpenCode compare against other ways to route OpenCode through a self-hosted AI gateway

### OmniRoute OpenCode vs OpenCode Zen (OpenCode's Hosted Model Service)

- **Hosting model:** OmniRoute runs on your own Railway service, so your endpoint and provider keys stay under your control. Zen is hosted by OpenCode.
- **Provider choice:** OmniRoute reaches many providers through one /v1 endpoint using your own accounts.
- **Where Zen wins:** Zen needs no infrastructure or key setup. OmniRoute needs a deployed service and an API key first.

### OmniRoute OpenCode vs OpenRouter (Hosted API Aggregator Alternative)

- **Where requests go:** OpenRouter sees every request and bills through its own account. OmniRoute keeps routing on infrastructure you run.
- **Cost structure:** OmniRoute is MIT licensed, so you pay providers directly plus Railway hosting.
- **Where OpenRouter wins:** One bill and no hosting make it the easier path.

### OmniRoute OpenCode vs LiteLLM (Open-Source Python Proxy Alternative)

- **Runtime:** LiteLLM is an open-source Python proxy with an OpenAI-compatible API. OmniRoute is also self-hosted and OpenAI-compatible, with its own dashboard.
- **Storage:** OmniRoute keeps data in SQLite under /app/data on one service, with no Postgres or Redis to add.
- **Where LiteLLM wins:** If your team already runs Python proxies, LiteLLM fits that habit better.

### OmniRoute OpenCode vs 9Router (Open-Source AI Gateway Alternative)

- **Shared category:** 9Router is also an open-source AI gateway, so both expose one OpenAI-compatible endpoint across several providers.
- **Feature focus:** OmniRoute documents 19 routing strategies, a 4-tier fallback chain and circuit breakers. Compare those against 9Router before choosing.
- **Where 9Router wins:** If its routing behavior fits your workload better, it's a reasonable pick. Test both with your own OpenCode setup.

## How to use OmniRoute OpenCode (the OSS AI gateway)?

1. Deploy the template on Railway, then open your public Railway domain at `/dashboard`. Sign in with the generated `INITIAL_PASSWORD` from the service variables.
2. Go to `/dashboard/api-manager` and click **Create API Key**. Copy the key now, because you'll need it for OpenCode.
3. Point OpenCode at the gateway in one of two ways. Run `omniroute setup-opencode --remote https://your-railway-domain --api-key your-key` (add `--dry-run` first to preview the changes). Or write `~/.config/opencode/opencode.json` by hand:

```json
{
  "provider": {
    "omniroute": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://your-railway-domain/v1",
        "apiKey": "your-key"
      }
    }
  }
}
```

4. Test the route with a thinking variant:

```bash
opencode run "your prompt" --model omniroute/auto/coding --variant high
```

## How to self host OmniRoute OpenCode on other VPS Services (OmniRoute self hosting guide)

You can run the same OmniRoute image on any VPS with Docker. These steps assume Linux with Docker and Git, served behind your own HTTPS domain.

### Clone the Repository

```bash
git clone https://github.com/diegosouzapw/omniroute.git
cd omniroute
```

### Install Dependencies

Pull the pinned image so you run the same version as the template.

```bash
docker pull diegosouzapw/omniroute:3.8.51
```

### Configure Environment Variables

Replace your-domain with your host. Set these before the first start, since `REQUIRE_API_KEY=true` means OpenCode gets a 401 until you create a key in the dashboard.

```bash
export PORT=20128
export DATA_DIR=/app/data
export BASE_URL=https://your-domain
export NEXT_PUBLIC_BASE_URL=https://your-domain
export AUTH_COOKIE_SECURE=true
export REQUIRE_API_KEY=true
export INITIAL_PASSWORD=change-me-now
export JWT_SECRET=your-long-random-secret
export API_KEY_SECRET=your-second-random-secret
```

### Start the OmniRoute OpenCode Application

Mount a volume on `/app/data` so your SQLite database and encrypted provider keys survive restarts.

```bash
docker run -d --name omniroute -p 20128:20128 \
  -v omniroute-data:/app/data \
  -e OMNIROUTE_MEMORY_MB=8192 \
  --env-file omniroute.env \
  diegosouzapw/omniroute:3.8.51
```

Railway handles the HTTPS domain, the persistent volume and restarts for you.

## Official Pricing of OmniRoute OpenCode (OmniRoute pricing)

OmniRoute itself is free and open source under the MIT license, so there is no OmniRoute subscription to buy. Railway has a $5 free trial you can use to test the deployment before committing.

## OmniRoute OpenCode cloud vs self hosted comparison (Pricing, features, costs, and more)

Self hosting OmniRoute means you pay only for the Railway service and your model providers.

### Monthly cost of self hosting OmniRoute OpenCode on Railway

Light use at 1-2 GB of memory typically lands around $5-15 per month on Railway.

### System Requirements for Hosting OmniRoute OpenCode on a VPS

A VPS needs enough memory for that heap, roughly 10 GB for coding agents.

## Frequently Asked Questions (FAQs)

### Do I need the dashboard to create a key?

Yes, if `REQUIRE_API_KEY=true` is set, which the template does by default.

### Why do I get 401 Invalid API key?

The key you sent doesn't exist on that instance.

### Why do requests show /v1/v1 paths?

You're running an old helper version, around 1.0.0 or earlier, that appends `/v1` to a base URL that already ends in it.

### Which model ids should I use with auto/coding and auto/fast?

Use `omniroute/auto/coding` for coding tasks and `omniroute/auto/fast` when you want quicker, cheaper turns.

### What memory does the coding agent need?

The default `OMNIROUTE_MEMORY_MB=1024` is fine for the dashboard and light chat, but coding agents that use `/v1/responses` need about 8192 heap and roughly 10 GB of container memory, per the upstream docs.

### How does this compare to OpenCode Zen or OpenRouter?

OpenCode Zen is OpenCode's own hosted model service, and OpenRouter is a hosted aggregator behind one key.


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [Weaviate](https://railway.com/deploy/weaviate-1) — Vector database with hybrid search and an API key-protected API
- [Möbius v0.1 Personal AI OS](https://railway.com/deploy/mobius-v01-personal-ai-os) — Self-hosted AI agent that builds and runs apps for you, with memory.

Open this page in a browser: https://railway.com/deploy/deploy-omniroute-for-opencode