---
title: "Deploy HarnessRouter"
description: "Run Claude Code, Codex and more agents behind one API"
category: "AI/ML"
url: https://railway.com/deploy/deploy-harnessrouter
---

# Deploy HarnessRouter

Run Claude Code, Codex and more agents behind one API

**[Deploy HarnessRouter on Railway](https://railway.com/template/deploy-harnessrouter)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/deploy-harnessrouter/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 (Unified API for Agent Harnesses) on Railway

HarnessRouter Community Edition 0.37.13 runs as one container on Railway, with a Console, Gateway and Runner sharing a /data volume.

## About Hosting HarnessRouter open-source software on Railway (self hosted HarnessRouter template)

This template runs HarnessRouter Community Edition 0.37.13 as a single container, with the Console, Gateway and Runner all inside one service and state kept on a /data volume.

## Why Deploy HarnessRouter, the open-source agent harness router on Railway (Railway Free Trial)

Wiring Claude Code, Codex and OpenCode into a product one CLI at a time means rebuilding sessions, streaming and failure handling for each. HarnessRouter puts them behind one API, and Railway keeps it running for you.

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

Railway gives you HarnessRouter CE as one managed service.

| Provider | What You Get with Railway | What You Get with the Other Provider |
| --- | --- | --- |
| DigitalOcean | One-click template with the console, gateway and runner in one container, a /data volume and generated secrets. | A Droplet you size and maintain yourself, with Docker and the volume configured by hand. |
| AWS | A single public service and volume without IAM, VPC or load balancer config. | Full networking control, but you assemble EC2, storage and security groups before first boot. |
| Hetzner | Managed deploys and restarts from the dashboard, with no SSH or firewall setup to reach the Console. | Low-cost servers with generous bandwidth, paired with manual Docker installs and upkeep. |

## Common Use Cases for hosted HarnessRouter

- **Adding an agent feature to your product:** Put a coding agent behind one OpenAI Responses-compatible endpoint and pick the harness per request with `metadata.harness_id`.
- **Switching harnesses per task:** Send quick edits to a cheaper, faster harness like OpenCode and harder refactors to Claude Code or Codex, trading cost and latency without changing client code.
- **Giving a team a shared console:** One operator account (harnessrouter) holds the provider keys under Bring your own key, and teammates' backends call it with API keys created in the Console.
- **Running long agent tasks:** Persistent sessions, files and streaming progress let multi-step jobs run for minutes and resume without losing context.
- **Prototyping before moving to Cloud:** Shape a harness setup on your own Railway service first, then move the configuration to HarnessRouter Cloud once the workflow is settled.

## Dependencies for HarnessRouter Docker hosted on Railway

HarnessRouter runs as one container with no separate database, so the deployment is a single Railway service with one persistent volume.

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

The Console is the only public port and listens on Railway's PORT, with the gateway and runner kept on loopback inside the container.

| Variable | Purpose |
|---|---|
| HR_AUTH_PASSWORD | Console password for username harnessrouter; change it later in Profile |
| HR_SECRET_KEY | Signs session cookies and encrypts stored provider credentials; keep it stable |

### Implementation Details for HarnessRouter (Using the HarnessRouter CE docker image)

The wrapper refuses to boot if HR_AUTH_PASSWORD is empty or still the default "harnessrouter," unless you have already changed credentials in Profile.

## How does HarnessRouter compare against other ways to run AI coding agents behind an API

### HarnessRouter vs Calling Each Agent CLI Directly (Direct CLI Alternative)

- **Single contract:** You call one Responses-compatible endpoint and pick the harness per request with metadata.harness_id, instead of writing a separate integration for each CLI.
- **Shared plumbing:** Sessions, streaming progress, files, cancellation and structured failures come built in, which you would otherwise rebuild for every agent.
- **Where direct CLIs win:** For one agent on one machine, calling its CLI directly has fewer moving parts.

### HarnessRouter vs OpenRouter (OpenRouter Alternative)

- **Different layer:** OpenRouter routes model calls to providers, while HarnessRouter runs full agent harnesses like Claude Code or Codex that plan, edit files and execute tasks.
- **Self hosted control:** HarnessRouter CE runs in your own Railway project with your own provider keys, so state stays on your volume.
- **Where OpenRouter wins:** If you only need a single model call with broad model choice and no agent loop, OpenRouter is simpler and needs nothing to host.

### HarnessRouter vs LiteLLM (LiteLLM Alternative)

- **Different layer:** LiteLLM normalizes model API calls across providers, while HarnessRouter wraps coding and agent CLIs as runnable backends with sessions and workspaces.
- **Agent workspaces:** Each session gets its own workspace and runs tasks there, which a model proxy does not provide.
- **Where LiteLLM wins:** For plain chat completions across many model vendors behind one proxy, LiteLLM is the more focused tool.

### HarnessRouter vs HarnessRouter Cloud (HarnessRouter Cloud Alternative)

- **Same API contract:** Cloud uses the same API, so an app built on CE can move to Cloud without rewriting client code.
- **Managed isolation:** Cloud runs serverless isolated sandboxes, while CE runs sessions as separate workspaces and OS users inside one container.
- **Where CE wins:** If you want to keep everything in your own infrastructure and avoid a managed dependency, the self hosted Community Edition is the right fit.

## How to use HarnessRouter (the OSS Unified API for Agent Harnesses)?

1. Wait for first boot (about 2 minutes in our test) until the deploy logs show the Console is ready and the /login healthcheck passes.
2. Open the public domain Railway generated for the service.
3. Sign in as harnessrouter with HR_AUTH_PASSWORD, then change it in Profile.
4. Choose Bring your own key and add your provider API key.
5. Start and set up an agent harness, picking a harness and model.
6. Try one example job to confirm the stack works.
7. Create an API key on the API Keys page, shown once, and store it as HARNESSROUTER_API_KEY.
8. Call the Responses endpoint with metadata.harness_id:

```bash
curl https://your-domain/api/harness/v1/responses \
  -H "Authorization: Bearer $HARNESSROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Reply with exactly: it works.", "metadata": {"harness_id": "codex"}, "model": "gpt-5.4-mini", "stream": false}'
```

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

### Clone the Repository

Clone the template repo for the Dockerfile and start wrapper.

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

### Install Dependencies

You need Docker, about 4 GB of free disk, and a model provider API key such as OpenAI or Anthropic.

### Configure Environment Variables

Set a console password and a stable secret key before the first start.

```bash
export HR_AUTH_PASSWORD="your-strong-password"
export HR_SECRET_KEY="your-48-char-random-secret"
export HR_BACKENDS="claude,codex,opencode,gemini,qwen,pi,kilo,cline,goose,hermes"
```

### Start the HarnessRouter Application

Run the container with a named volume at /data so state survives restarts.

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

## Official Pricing of HarnessRouter (HarnessRouter pricing)

HarnessRouter Community Edition is free and open source under Apache-2.0, so there is no license fee to pay.

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

HarnessRouter Community Edition is free to run yourself, and the Railway template gives you the same single-container setup as the upstream image.

### Monthly cost of self hosting HarnessRouter on Railway

The template runs as one public service with a /data volume and no database service, so your recurring cost is the service compute plus the volume.

### System Requirements for Hosting HarnessRouter on a VPS

Running the upstream image on a VPS needs Docker, roughly 4 GB of disk for the harness CLIs and workspaces, and a provider API key.

## Frequently Asked Questions (FAQs)

### Why does first boot take a few minutes?

On first start the container installs the harness CLIs you enabled into the /data volume before the Console comes up, so the service stays unhealthy for a short while.

### How do I add more harnesses with HR_BACKENDS?

Set the HR_BACKENDS service variable to a comma-separated list of the bases you want, such as claude,codex,opencode,gemini.

### Why not install all 30?

Upstream installs all 30 harness bases on first boot, which is over 5 GB and overflows a 5 GB Railway volume with a "database or disk is full" error.

### Where do I change the password?

Sign in as harnessrouter with the HR_AUTH_PASSWORD value, then change it under Profile in the Console.

### What happens if HR_SECRET_KEY changes?

HR_SECRET_KEY encrypts your stored provider credentials and signs session cookies, so changing it makes saved provider connections unreadable and logs users out.

### Do I need a HarnessRouter account?

No. Community Edition needs no HarnessRouter account and ships no bundled model or trial key; you bring your own provider 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-harnessrouter