---
title: "Deploy HarnessRouter Codex API"
description: "Call the Codex agent from your app through one Responses API"
category: "AI/ML"
url: https://railway.com/deploy/deploy-harnessrouter-codex-cli-as-api
---

# Deploy HarnessRouter Codex API

Call the Codex agent from your app through one Responses API

**[Deploy HarnessRouter Codex API on Railway](https://railway.com/template/deploy-harnessrouter-codex-cli-as-api)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/deploy-harnessrouter-codex-cli-as-api/manifest.json

- **Creator:** onepush
- **Category:** AI/ML

## Template content

### HarnessRouter https://github.com/HarnessRouter.png

- **Image:** ghcr.io/onepush-dev/harnessrouter:0.37.13
- **Health check:** /login
- **Public domain:** Yes

## Documentation

# Deploy and Host self hosted HarnessRouter Codex API (Codex CLI as an API Backend) on Railway

This template runs HarnessRouter with the Codex CLI wired in as an API backend, so your app can call a Codex agent through one Responses-style endpoint.

## About Hosting HarnessRouter Codex API open-source software on Railway (self hosted Codex CLI exposed as a Responses-style API backend template)

You own the whole stack with this template: the Console, the Responses-compatible Gateway and the Runner that executes Codex in per-session workspaces all live in one container, and your OpenAI key, sessions and files sit on its /data volume.

Railway builds the pinned image, exposes the Console on a public domain, runs the /login health check and keeps the volume attached across restarts.

## Why Deploy HarnessRouter Codex API, the HarnessRouter Cloud alternative on Railway (Railway Free Trial)

Self-hosting HarnessRouter on Railway keeps your OpenAI key and Codex workspaces on a volume you control, unlike HarnessRouter Cloud, which runs them on managed sandboxes.

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 HarnessRouter Codex API 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 HarnessRouter Codex API self hosting

| Provider | What You Get with Railway | What You Get with the Other Provider |
| --- | --- | --- |
| DigitalOcean | A one-click template with generated secrets, a /data volume, and a public domain. | A droplet where you install Docker, set the firewall, and configure HTTPS yourself. |
| AWS | A template deploy with no VPC or load balancer work before your first Codex request. | Full networking control, but you set up EC2 or ECS, EBS, security groups, and certificates first. |
| Hetzner | Managed deploys with a /login healthcheck and no host patching during harness installs. | Low-cost capacity where you run the container runtime, back up /data, and handle restarts. |

## Common Use Cases for hosted HarnessRouter Codex API

- **Routing coding tasks from an internal app:** Send a job to a Codex harness with one POST to /api/harness/v1/responses on your own domain. The app does not need to know how the Codex CLI is installed.
- **Streaming Codex output to a web UI:** Set "stream": true to receive server-sent events, so a browser can show progress live.
- **Retrying failed agent calls safely:** Send an Idempotency-Key header and a retry with the same key returns the first result instead of running the task again.
- **Attaching repository files to a task:** Upload with POST /v1/files, then reference the file in an input_file block.
- **Switching harnesses without rewriting code:** Change metadata.harness_id to move the same integration between codex and another installed harness.

## Dependencies for HarnessRouter Codex API Docker hosted on Railway

This template runs as a single public service, so nothing else needs provisioning before you send a Codex task.

### Deployment Dependencies for Managed HarnessRouter Codex API Service (Console + Gateway + Runner on a /data volume)

The service listens on Railway's PORT, mounts a volume at /data, and uses /login as its healthcheck.

- **HR_AUTH_PASSWORD:** generated, 32 characters, the Console password for user harnessrouter.
- **HR_SECRET_KEY:** generated, 48 characters; keep it stable or stored keys become unreadable.
- **HR_BACKENDS:** ten bases by default, including codex. All 30 overflow a 5 GB volume.

### Implementation Details for HarnessRouter Codex API (Using HarnessRouter official docker image)

On first boot the container installs the enabled harness CLIs into /data, so the first start is slow.

## How does HarnessRouter Codex API compare against other ways to run Codex CLI behind an API

### HarnessRouter Codex API vs Calling the codex CLI directly (Codex CLI Alternative)

- **Process model:** Calling codex directly means spawning a terminal agent per request and parsing its output yourself. HarnessRouter wraps Codex behind one POST /v1/responses endpoint.
- **Retries:** A bare CLI call has no deduplication, so a retry can run the task twice. The Idempotency-Key header returns the first result instead.
- **Where the CLI wins:** For interactive use on your own machine, the CLI is simpler with no server to run.

### HarnessRouter Codex API vs OpenAI Responses API (OpenAI Responses Alternative)

- **Request shape:** HarnessRouter accepts a Responses-style request, so client code written for OpenAI's endpoint needs little change.
- **What runs behind it:** OpenAI returns model output for your tool definitions. HarnessRouter runs a full Codex agent with workspaces and file handling.
- **Where OpenAI wins:** For plain model calls with your own tool loop, the hosted API has fewer moving parts.

### HarnessRouter Codex API vs OpenRouter (OpenRouter Alternative)

- **Routing target:** OpenRouter routes one key across many model providers. HarnessRouter routes across agent harnesses, so the unit of work is a task.
- **Your keys:** HarnessRouter uses your own OpenAI key through Bring your own key, with no bundled credits.
- **Where OpenRouter wins:** For cheap access to many models for chat, OpenRouter is more direct and needs no self-hosting.

### HarnessRouter Codex API vs LiteLLM (LiteLLM Alternative)

- **Layer:** LiteLLM unifies many LLM providers under an OpenAI-style interface. HarnessRouter sits one layer up, exposing whole coding agents as backends.
- **State:** HarnessRouter keeps sessions, files and artifacts on its /data volume. LiteLLM is largely stateless per request.
- **Where LiteLLM wins:** For standardizing model access across many providers with spend tracking, LiteLLM is more mature.

## How to use HarnessRouter Codex API (the OSS agent harness router)?

1. Deploy and wait for first boot; the harness CLIs install before the Console starts.
2. Sign in at https://YOUR-DOMAIN/login as harnessrouter with the HR_AUTH_PASSWORD value.
3. In the account menu choose Bring your own key, Add key, and paste your OpenAI key.
4. On Start, set up an agent harness with Codex and the model on Auto.
5. Create a key on the API Keys page and store it as HARNESSROUTER_API_KEY on your server.
6. Call the Responses endpoint with metadata.harness_id set to codex:

```bash
curl -X POST https://YOUR-DOMAIN/api/harness/v1/responses \
  -H "Authorization: Bearer $HARNESSROUTER_API_KEY" \
  -H "Idempotency-Key: task-0001" \
  -H "Content-Type: application/json" \
  -d '{"input":"Summarize the README","metadata":{"harness_id":"codex"},"model":"gpt-5.4-mini","stream":false}'
```

7. For server-sent events, repeat with "stream":true:

```bash
curl -N -X POST https://YOUR-DOMAIN/api/harness/v1/responses \
  -H "Authorization: Bearer $HARNESSROUTER_API_KEY" \
  -H "Idempotency-Key: task-0002" \
  -H "Content-Type: application/json" \
  -d '{"input":"Summarize the README","metadata":{"harness_id":"codex"},"model":"gpt-5.4-mini","stream":true}'
```

8. Browse the spec at /v1/openapi.json or /v1/docs.

## How to self host HarnessRouter Codex API on other VPS Services (HarnessRouter self hosting guide)

Running this on your own VPS works if you have Docker, about 4 GB of free disk and an OpenAI key.

### Clone the Repository

```
git clone https://github.com/onepush-dev/harnessrouter.git
cd harnessrouter
```

### Install Dependencies

Confirm Docker is running and pull the pinned image.

```
docker --version
docker pull ghcr.io/onepush-dev/harnessrouter:0.37.13
```

### Configure Environment Variables

Keep HR_SECRET_KEY unchanged across restarts, since it decrypts your stored OpenAI credential.

```
export HR_AUTH_PASSWORD=your-32-char-password
export HR_SECRET_KEY=your-48-char-secret-key
export HR_BACKENDS=claude,codex,opencode,gemini,qwen,pi,kilo,cline,goose,hermes
```

### Start the HarnessRouter Codex API Application

Start the container with a data volume, then wait for the ready line before logging in.

```
docker run -d --name harnessrouter -p 127.0.0.1:3000:3000 \
  -v harnessrouter:/data -e PORT=3000 \
  -e HR_AUTH_PASSWORD -e HR_SECRET_KEY -e HR_BACKENDS \
  ghcr.io/onepush-dev/harnessrouter:0.37.13
docker logs -f harnessrouter
```

## Official Pricing of HarnessRouter Codex API (HarnessRouter pricing)

HarnessRouter Codex API is free and open source under Apache-2.0, so there is no license fee for the software.

## HarnessRouter Codex API cloud vs self hosted comparison (Pricing, features, costs, and more)

It comes down to who runs the sandboxes and who holds the provider keys.

### Monthly cost of self hosting HarnessRouter Codex API on Railway

The template has no license fee, so your cost is the Railway service plus your OpenAI usage.

### System Requirements for Hosting HarnessRouter Codex API on a VPS

Upstream asks for Docker, about 4 GB of disk and a provider API key.

## Frequently Asked Questions (FAQs)

### Do I still need an OpenAI key to use Codex through HarnessRouter?

Yes, add it in the Console under Bring your own key.

### Why does a retry return the first result instead of running again?

Sending the same Idempotency-Key header tells HarnessRouter the call is a repeat, so it returns the saved result rather than starting a new run.

### What does a 409 on Idempotency-Key mean?

A 409 means you reused a key with a different request body.

### How do I pass a repository file to a Codex task?

Upload the file with POST /v1/files, then reference it in the input array using an input_file block.

### Is streaming supported?

Yes, set "stream": true to get server-sent events.

### Are W3C trace headers propagated?

Valid W3C traceparent and tracestate headers are propagated to the task's model calls.


## 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-harnessrouter-codex-cli-as-api