---
title: "Deploy OpenCodex"
description: "Use Codex CLI and Claude Code with any LLM through one keyed proxy hub"
category: "AI/ML"
url: https://railway.com/deploy/opencodex
---

# Deploy OpenCodex

Use Codex CLI and Claude Code with any LLM through one keyed proxy hub

**[Deploy OpenCodex on Railway](https://railway.com/template/opencodex)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/opencodex/manifest.json

- **Creator:** Two Workspaces
- **Category:** AI/ML

## Template content

### opencodex https://raw.githubusercontent.com/two-workspaces/opencodex/main/icon.png

- **Source:** https://github.com/two-workspaces/opencodex
- **Health check:** /healthz
- **Public domain:** Yes

## Documentation

# Deploy and Host OpenCodex on Railway

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/opencodex?referralCode=sLjDXb&utm_medium=integration&utm_source=button&utm_campaign=opencodex)

OpenCodex is a universal provider proxy for OpenAI Codex and Claude Code. It lets Codex CLI, the Codex app and SDK, Claude Code and other OpenAI- or Anthropic-compatible clients use any LLM: Claude, Gemini, Grok, DeepSeek, Kimi, Qwen, GLM, OpenRouter, Ollama and any OpenAI-compatible gateway, translating between the Responses, Chat Completions and Anthropic Messages APIs. This template runs OpenCodex 2.100.4 on Railway as a **hub**: provider keys, model routing and usage live on one always-on service, and every machine you code on reaches it over HTTPS with an API key.

This is a community template, not made or supported by the OpenCodex authors.

## About Hosting OpenCodex

Deploying gives you one service with a volume and a public HTTPS domain. Everything on it is locked behind the `OPENCODEX_API_AUTH_TOKEN` variable, generated at deploy time: requests without it get `401`, and OpenCodex itself refuses to start on a public address without a key.

**1. Open the dashboard.** Visit your Railway domain. The dashboard asks to pair this browser and shows an `ocx gui pair --origin …` command. Run it on the hub from your computer with the [Railway CLI](https://docs.railway.com/guides/cli):

```bash
railway ssh -- ocx gui pair --origin https://‹your-domain›
```

Paste the one-time code into the dashboard. Pairing only works over HTTPS, which Railway's domain provides.

**2. Add providers** in the dashboard (Providers → Add) with your API keys, or from the shell: `railway ssh` then `ocx provider add openrouter --api-key ‹key› --live`. Keys stay on the hub's volume and never go to your clients. Enable the models you want under Models.

**3. Point your tools at the hub.** For Codex CLI, add to `~/.codex/config.toml`:

```toml
model_provider = "opencodex"
model = "‹provider›/‹model›"

[model_providers.opencodex]
name = "OpenCodex"
base_url = "https://‹your-domain›/v1"
env_key = "OPENCODEX_API_KEY"
wire_api = "responses"
```

and `export OPENCODEX_API_KEY=‹your OPENCODEX_API_AUTH_TOKEN›`. For Claude Code, run it with `ANTHROPIC_BASE_URL=https://‹your-domain›` and `ANTHROPIC_AUTH_TOKEN=‹token›`, then pick a hub model with `--model ‹provider›/‹model›`. Any OpenAI-compatible app works with `https://‹your-domain›/v1` and the token as its API key.

**Or join a machine the OpenCodex way.** Install OpenCodex locally (`npm install -g --allow-scripts=bun @bitkyc08/opencodex`), run `railway ssh -- ocx hub invite` and run the `ocx connect` line it prints on your machine. The hub then issues that machine its own key, which you can revoke later in the dashboard's Connect → API Keys.

## Common Use Cases

- Run Codex CLI or the Codex app on Claude, Gemini, DeepSeek, Grok, Kimi or local models
- Give Claude Code non-Anthropic models, with routing and fallbacks between providers
- Keep all provider keys on one server and hand each laptop or CI job its own revocable key
- Track token usage and spend across providers and machines in one place

## Dependencies for OpenCodex Hosting

- An API key for at least one LLM provider (OpenRouter, Anthropic, Google, DeepSeek, any OpenAI-compatible endpoint), or a ChatGPT or other subscription login done on the hub.
- The [Railway CLI](https://docs.railway.com/guides/cli) for `railway ssh`, to pair the dashboard and run `ocx` commands.

### Deployment Dependencies

- [OpenCodex on GitHub](https://github.com/lidge-jun/opencodex)
- [OpenCodex documentation](https://opencodex.me)
- [Remote hub guide](https://opencodex.me/guides/remote-hub/)
- [Template source](https://github.com/two-workspaces/opencodex)

### Implementation Details

- **Tested on Railway:** the healthcheck, `401` without the key, a pairing code from `railway ssh` exchanged for a dashboard session over HTTPS, a provider added from `railway ssh`, requests on all three wire formats (Responses, Chat Completions, Anthropic Messages) to an OpenAI-compatible provider, and Codex CLI and Claude Code each answering through the hub with the settings above. A redeploy at 0.5 GB kept the providers. Subscription logins (ChatGPT, Claude) on the hub and `ocx connect` from a second machine were not tested.
- **Native Claude models in Claude Code:** with an Anthropic key on the hub, the hub's key travels in the `x-opencodex-api-key` header, not `Authorization`. Set `ANTHROPIC_CUSTOM_HEADERS="x-opencodex-api-key: ‹token›"`; see upstream's Claude Code guide.
- **Volume:** `/data` holds OpenCodex's config, provider credentials and usage (`/data/opencodex`) and Codex's model catalog (`/data/codex`). Redeploys keep everything.
- **On every boot** the template sets the listener (`0.0.0.0:10100`), the hub role and the public origin from the Railway domain (or `PUBLIC_URL`), and leaves your providers, models and keys alone. Add the domain before the first deploy, or redeploy after adding it, so the dashboard can pair.
- **Clearing `OPENCODEX_API_AUTH_TOKEN`** doesn't open the hub: a key is then generated in `/data/opencodex/service-api-token` (`railway ssh -- cat /data/opencodex/service-api-token`).
- **Memory:** about 150 MB idle, so it fits a 0.5 GB plan.
- **Image:** upstream's npm release `@bitkyc08/opencodex@2.100.4`, pinned, on upstream's Bun 1.4.4 runtime (upstream publishes no container image).

## Why Deploy OpenCodex on Railway?

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 OpenCodex 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.


## 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 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/opencodex
