SSD Nodes Learn Hosting plans →
Guides Matt ConnorBy Matt Connor

Self-host HarnessRouter: one agent API

Run Codex, Claude Code and Hermes behind one self hosted API. The exact Docker deploy, the loopback bind, the initial login you must change, and TLS access.

What HarnessRouter removes

You self-host HarnessRouter Community Edition to put one API in front of several agent harnesses on a server you own. An agent harness is the command line program that drives a model in a loop: it keeps a session, edits files, runs commands, and streams progress back to whatever asked for the work. Codex, Claude Code and Hermes each do that job, and each arrives with its own install, its own credential format and its own idea of what a session is. HarnessRouter runs all of them inside one container and puts a single HTTP endpoint, a single login and a single secret store in front.

That is the whole idea, and the cost is worth saying out loud. You are adding a container, a login, a volume and an upgrade path to your server so that several moving parts become one. If you run exactly one harness today, this is a worse setup than installing that harness directly. That trade is the last section here, so read it before you deploy.

Everything below was checked against image tag 0.5.5, pulled on 19 August 2026. The project publishes new tags most days, so check the tag you actually run instead of trusting this page in a month. On 8 November 2026 this page was rechecked against the project's current documentation and source, when latest pointed at 0.38.5, and the places where current releases behave differently say so. The commands come from the project repository at github.com/HarnessRouter/harnessrouter. They were in the README at 0.5.5; the setup detail now lives in docs/self-hosting-guide.md in the same repository.

What the Unified Harness Protocol actually is

HarnessRouter implements the Unified Harness Protocol (UHP), published at unifiedharnessprotocol.org. UHP describes how a product starts a task on a harness, follows the task while it runs, manages sessions and files, and reports failure. The spec is versioned by date. The version live as of 19 August 2026 was dated 2026-08-11. As of 8 November 2026 the site lists 2026-10-19 as the current version, and it still calls it a draft standard, "stable enough to build on, versioned so it can change safely".

Read the phrase "open standard" carefully here. The same company writes the specification, the reference implementation and the conformance suite that decides who conforms, and the project's governance rules say no change lands unless all three move together. As of 9 November 2026 the protocol homepage describes that suite as 110 runnable checks, while its conformance page says 101 and the self-hosting guide's recorded reference run, dated 4 September 2026, passed 64, so the published counts do not agree. The project's changelog dates the six additional branching checks to 4 November 2026. That is ordinary for a protocol this young, and the Apache-2.0 licence means you can fork any part of it. It also means UHP is not yet a multi-vendor standard. Treat it as an emerging protocol: useful, moving, and something your own code should be able to stop using without a rewrite.

What you need before you start

Docker and roughly 4 GB of free disk. You also need an API key from a model provider you already pay for. The image pull is about 700 MB, and the rest of the disk goes to the agent CLIs and the workspaces they write in. There is no bundled model and no trial key inside the image, so tasks fail until you connect a provider. HarnessRouter itself is Apache-2.0. The agent CLIs remain subject to their own licences and terms, which the repository's licence does not replace; they are fetched on first start rather than shipped in the image.

Self-host HarnessRouter with one docker run

docker pull harnessrouter/harnessrouter
docker run -d --name harnessrouter \
  -p 127.0.0.1:3000:3000 \
  -v harnessrouter:/data \
  harnessrouter/harnessrouter

Then watch the container come up. The first start is slow, and the logs tell you why.

docker logs -f harnessrouter

You will see lines like these while it works:

installing Claude Code (Anthropic's terms apply)…
installing Codex (Apache-2.0)…
installing Hermes (check its upstream license before use)…

Wait for ready on :3000. The current guide measures roughly half a minute from docker run returning your prompt, not from that line; if http://localhost:3000 does not answer immediately after the ready line, retry after a few seconds. Installed CLIs are cached on the volume, so later starts are usually much faster, though a backend you add later, or one that failed to install before, can still trigger install work.

Two facts follow from that download, and both matter on a VPS. First, first boot needs outbound network access. The image is not self-contained, so a box behind an egress filter, or one with no route out, cannot fetch the agent CLIs. Both 0.5.5 and current releases treat failed installs as non-fatal and name them in the log, so look for which backends the backends available: line leaves out. Second, you are installing third-party software under third-party terms. Claude Code arrives under Anthropic's terms and Hermes under whatever its upstream says, so check both before you use this commercially.

-v harnessrouter:/data creates a named Docker volume. Everything durable lives in /data: the SQLite databases, the stored files, the secret store and the agent workspaces. Delete that volume and you have deleted the instance, including the provider keys and every transcript. Back it up with the container stopped, because copying a SQLite database while it is being written gives you a file that may not open. The same stop-then-copy discipline applies to every stateful container on the box, though the details vary by service, since PhotoPrism and Immich each need their own backup commands.

docker stop harnessrouter
docker run --rm -v harnessrouter:/data -v "$PWD":/backup alpine \
  tar czf /backup/harnessrouter-data.tgz -C / data
docker start harnessrouter

The compose variant, and the line you must change

The repository ships a compose file. It now publishes "127.0.0.1:3000:3000", binding the host port to loopback. The 0.5.5 file published "3000:3000"; change that line if you are using the older file on a public server.

services:
  harnessrouter:
    image: harnessrouter/harnessrouter:0.5.5
    ports:
      - "127.0.0.1:3000:3000"
    env_file:
      - .env
    volumes:
      - harnessrouter-data:/data
    restart: unless-stopped

volumes:
  harnessrouter-data:

One thing differs from current upstream: a pinned version tag instead of latest. Pinning matters because releases change quickly: Docker Hub listed both 0.38.4 and 0.38.5 as pushed within the past day when checked on 8 November 2026. An agent runtime that changes under you is hard to debug. Pin the current release rather than copying 0.5.5 from this page; on 9 November 2026 that was 0.40.0. Then copy the environment file, lock its permissions, and start.

cp .env.example .env
chmod 600 .env
docker compose up -d
docker compose logs -f

.env holds your provider key in plain text, so mode 600 is the minimum. If the docker compose subcommand is unfamiliar, the Docker Compose command cheat sheet covers the daily verbs.

Why the port is published on 127.0.0.1 and not 0.0.0.0

-p 3000:3000 publishes the port on every interface the host has by default. -p 127.0.0.1:3000:3000 publishes the host port on loopback. Docker releases older than 28.0.0 allow hosts on the same L2 segment to reach localhost-published ports, and explicitly enabled direct routing can expose the container port despite a loopback host mapping. The container listens on 3000 inside by default, configurable through PORT, so change the left-hand port number to avoid a host port conflict. Check what you got:

docker port harnessrouter
sudo ss -ltnp | grep 3000

ss printing 127.0.0.1:3000 is right. 0.0.0.0:3000 means the console is bound on every IPv4 interface; public internet access still depends on routing and filtering. That is worse here than for most self-hosted apps, because the console creates harnesses, reads every transcript, runs agents, and gives those agents a shell and a real filesystem in their workspace. It also holds the provider key you connected. Anyone who reaches an unprotected console can read your work, run commands, and spend your key.

A ufw deny rule does not save you from this. Docker diverts published container traffic through its own rules before the chains ufw manages, so sudo ufw status showing a port as denied does not establish that the published port is blocked. Test from another machine, not from the VPS, or you will test nothing. This is the same lesson as running dsh headless on port 3080: bind the service to loopback, then decide deliberately how you reach it.

Change the default login before anything else

Sign in at http://localhost:3000 with the username harnessrouter and the initial password generated by your instance. Read it with:

docker exec harnessrouter cat /data/selfhost-initial-password

The shared password harnessrouter worked in 0.5.5; current installations do not accept that published default.

Change it from the Profile page, or set it at start time for a scripted deploy. HR_AUTH_USER and HR_AUTH_PASSWORD supply the initial credentials; credentials saved from Profile take precedence.

docker run -d --name harnessrouter \
  -p 127.0.0.1:3000:3000 \
  -v harnessrouter:/data \
  -e HR_AUTH_USER='you' \
  -e HR_AUTH_PASSWORD='the-password-you-chose' \
  harnessrouter/harnessrouter

There is no reset email for the local Console login. If you lose the password, delete the auth file in the volume and restart, then sign in with your configured HR_AUTH_USER and HR_AUTH_PASSWORD, or the generated initial password if you did not supply your own.

docker stop harnessrouter
docker run --rm -v harnessrouter:/data alpine rm -f /data/selfhost-auth.json
docker start harnessrouter

HR_AUTH_DISABLED=1 removes the sign-in gate completely. The self-hosting guide calls that "only reasonable on a machine nobody else can reach". A VPS with a public IP address is not that machine, so leave the gate on unless you are running this on a laptop.

Check your version, because the old ones have no gate

This is the part to take seriously. Versions 0.1.x and 0.2.0 shipped with no authentication gate at all: anyone who could reach port 3000 was already inside the console. 0.3.0 was the first release with a login. This page last recorded those older tags as published and pullable on 12 October 2026; their current availability was not confirmed on 8 November 2026.

As of 19 August 2026 the newest published tag was 0.5.5, dated 18 August 2026. On 8 November 2026 latest pointed at 0.38.5. Check what you have, then compare it against the tag list on Docker Hub:

docker image ls harnessrouter/harnessrouter

Anything below 0.3.0 should be replaced now, not scheduled. Older releases with the shared default password still need it changed; current installations generate an initial password and ask you to choose your own. Do not treat the version numbers on this page as current. They were true on the dates given, and this project ships fast.

Connect a provider

Nothing runs until a model provider is connected. Add one from Bring your own key in the account menu, or pass it to docker run in the environment. The value is JSON, so quote it in the shell:

-e HR_SECRET_GLOBAL_HARNESS_CONN_ANTHROPIC='{"name":"anthropic","provider":"anthropic","api_key":"sk-ant-…"}'

.env.example names one connection variable per provider family: HR_SECRET_GLOBAL_HARNESS_CONN_ANTHROPIC for the claude-code backend, HR_SECRET_GLOBAL_HARNESS_CONN_OPENAI for the codex backend, HR_SECRET_GLOBAL_HARNESS_CONN_GOOGLE for the gemini backend, and HR_SECRET_GLOBAL_HARNESS_CONN_CUSTOM for any OpenAI-compatible endpoint, which is where an aggregator or your own inference server goes. The matching HR_SECRET_GLOBAL_HARNESS_POLICY_CLAUDE, HR_SECRET_GLOBAL_HARNESS_POLICY_CODEX and HR_SECRET_GLOBAL_HARNESS_POLICY_HERMES variables say which connection each backend uses by default, and there is one policy variable per backend. HR_SECRET_KEY is a separate thing. Current releases encrypt stored credentials under it, generating a key in /data/secret-key when you do not supply one. Keep the same key across restarts and upgrades; to keep it apart from the data on an existing instance, set HR_SECRET_KEY to the value in that file and delete the file.

HR_BACKENDS selects which backends install and load, as in HR_BACKENDS=claude,codex,hermes. Left unset, current releases install a much longer default list of 30 backends, from claude, codex and hermes through opencode, gemini, goose and others, so trimming it saves disk and first-start time. The current self-hosting guide says to "leave any of them out of HR_BACKENDS if you will not use it", and its own lean example is HR_BACKENDS=opencode, which leaves out Hermes entirely. A backend that fails to install is not fatal: the others still work, and a task on a backend that did not install is refused as "not installed" while the container's log names the install that failed. The 0.5.5 README carried a known issue where leaving out hermes made the container exit immediately with status 1 and no error message, but that tag's entrypoint already fixes the failure; its comments describe the previous implementation. If Hermes is the only harness you want, running the Hermes agent on its own VPS is the smaller deployment.

Call the API without the console

The console is optional. The same API serves both, and it speaks a Responses-style contract. Sign in first to get a session cookie:

curl -c hr.cookies http://localhost:3000/api/selfhost/login \
  -H 'content-type: application/json' \
  -d '{"username":"harnessrouter","password":"your-password"}'

Then send a task, naming the harness in metadata.harness_id and a model your connected provider actually serves:

curl -s -b hr.cookies http://localhost:3000/api/harness/v1/responses \
  -H 'content-type: application/json' \
  -d '{"input":"Reply with exactly this and nothing else: it works.",
       "metadata":{"harness_id":"codex"},
       "model":"gpt-5.4-mini",
       "stream":false}'

A JSON object holding an output block and a token count means the harness ran. Changing harness_id from codex to claude-code sends the same request to a different harness, and that swap is the entire reason this software exists. Note the id is claude-code, even though the backend name in HR_BACKENDS and the policy variable is claude. The custom connection above is how you point a harness at an OpenAI-compatible endpoint you already host, in the way a self-hosted DeepSeek harness on a VPS is wired up.

The session-cookie flow remains supported for local debugging. For a product backend, current documentation recommends creating a HarnessRouter API key in API Keys and sending it as a Bearer token instead of maintaining a Console session.

Reach it from your laptop without publishing a port

Two ways, and neither of them is a raw port on 0.0.0.0.

An SSH tunnel is the cheapest, and it needs nothing installed on the server. It forwards a local port on your machine to loopback on the VPS.

ssh -N -L 3000:127.0.0.1:3000 you@your-vps

Leave that running and open http://localhost:3000 in your browser. If SSH prints bind: Address already in use, something on your laptop already holds port 3000, so pick another local port with -L 3100:127.0.0.1:3000 and browse to port 3100.

A terminating reverse proxy is the answer when other people need access. The proxy holds the TLS (transport layer security) certificate and forwards to loopback. The self-hosting guide gives a Caddy config:

console.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:3000 {
        flush_interval -1      # agent turns stream for minutes; never buffer them
    }
}

flush_interval -1 explicitly disables Caddy's response buffering; Caddy already flushes text/event-stream responses immediately without it. Agent turns stream tokens for minutes, and a proxy that buffers the response holds those tokens until the turn ends, so the console looks frozen and then prints everything at once. The equivalent in Nginx is proxy_buffering off; inside the location block. Whichever you pick, keep the DNS name pointed at the proxy and the container on loopback. Comparing Nginx, Caddy and Traefik as a reverse proxy covers which one fits your box.

Run it as its own user, not as root

The Docker daemon runs as root, and membership of the docker group is equivalent to root, because a member can start a container that mounts the host filesystem. So "add the team to the docker group" hands out root on the box that holds your provider key.

The simple version: create a service account that owns the compose file and .env, and keep those files out of any shared home directory.

sudo adduser --disabled-password --gecos "" harness
sudo install -d -o harness -g harness -m 750 /srv/harnessrouter

Do not try to get there by adding --user to docker run or user: to the compose file. The current guide says the container must start as root, and from 0.8.2 it refuses to start any other way, with one line in the log saying so.

The stronger version is rootless Docker, where the daemon itself runs as that unprivileged user. It needs the uidmap package for newuidmap and newgidmap, and at least 65536 subordinate UIDs in /etc/subuid and /etc/subgid for the user. uidmap is in the Ubuntu archive, but docker-ce-rootless-extras is not: it ships from Docker's own apt repository at download.docker.com, which the Docker engine install adds. If you have not installed the engine from that repository, grep -rl download.docker.com /etc/apt/sources.list.d/ prints nothing and the install below will not find the package.

sudo apt install -y uidmap docker-ce-rootless-extras
sudo loginctl enable-linger harness
sudo -iu harness
dockerd-rootless-setuptool.sh install
export DOCKER_HOST=unix:///run/user/$(id -u)/docker.sock
systemctl --user enable --now docker

loginctl enable-linger keeps the user's systemd instance running after logout and starts it at boot. Confirm the result with docker info, which lists rootless under Security Options. Rootless mode cannot bind ports below 1024 without extra configuration, which does not matter here because port 3000 is above that line. Setting up the account itself is covered in creating least-privilege users on a VPS.

What breaks, and what you will see

The container exits a second after starting and the logs are empty. docker ps -a shows Exited (1). An earlier entrypoint failed when HR_BACKENDS left out hermes, but 0.5.5 already contains the fix, despite its README still listing the issue. Do not diagnose that failure from the exit status alone. On a recent tag read the last line of docker logs: from 0.8.2 a container started with --user exits with one line saying it must start as root.

First start never finishes. The log stops after an installing line and ready on :3000 never appears. Check whether the box can reach the network to fetch the agent CLIs, because they are not in the image. Both 0.5.5 and current releases tolerate completed install failures, naming failed installs in the log and leaving them out of the backends available: line. Fix the outbound route or the proxy settings, then restart.

The console loads and every task fails. No provider is connected. There is no bundled model and no free tier inside the image, so a fresh instance can sign you in and still run nothing.

The console freezes mid-answer behind a proxy. The output appears in one block when the turn ends. That is response buffering. Set flush_interval -1 in Caddy, or proxy_buffering off; in Nginx.

You cannot reach it from your laptop and the tunnel is up. Run docker port harnessrouter on the server. If it prints nothing, the container publishes nothing, so check its port mapping and network mode.

Is this worth running?

It is worth running if you genuinely use more than one harness and you want one endpoint and one credential store instead of three of each. It is also worth running if you are building a product on top and want the harness to be a configuration value rather than a rewrite. That is what UHP buys you, with the caveat above about how young the protocol is.

It is not worth running if you use one harness. Installing that CLI on the server is fewer moving parts, and no login sits between you and it. It is also the wrong shape if what you want is several agents cooperating on one task rather than one API in front of several harnesses, which is a different tool: see a multi-agent harness such as Omnigent for that pattern. Either way the deployment rules do not change. Loopback bind, changed password, a pinned current release, and its own user.

FAQ

Is it safe to publish HarnessRouter on port 3000?

No. The console creates harnesses, reads every transcript, runs agents with shell and filesystem access, and holds the provider key you connected, so an unprotected console exposes all of it. Publish on loopback with -p 127.0.0.1:3000:3000 and reach it through an SSH tunnel or a TLS-terminating reverse proxy. A ufw deny rule is not enough on its own: Docker diverts published container traffic before the chains ufw manages. Verify with sudo ss -ltnp | grep 3000, which should print 127.0.0.1:3000, and test access from another machine. Use Docker 28.0.0 or later to avoid the older same-L2 localhost exposure, and check that direct routing has not been enabled.

Which HarnessRouter version added the login gate?

0.3.0. Versions 0.1.x and 0.2.0 shipped with no authentication at all, so anyone running them is relying on nobody finding the port. This page last recorded those tags as published and pullable on 12 October 2026; their current availability was not confirmed on 8 November 2026. As of 19 August 2026 the newest tag was 0.5.5, dated 18 August 2026; on 8 November 2026 latest pointed at 0.38.5. Run docker image ls harnessrouter/harnessrouter to see what you have, compare that against the tag list on Docker Hub rather than against this page, and choose your own password. Current installations generate an initial password instead of accepting the old shared default.

Why does the container exit straight after I set HR_BACKENDS?

On a current release it should not. The self-hosting guide says to leave out any backend you will not use, and a backend that fails to install is not fatal. An earlier implementation exited with status 1 and no error message when hermes was omitted, but the 0.5.5 source already fixes that failure, despite its README still listing it. On a recent tag, read docker logs: from 0.8.2 a container started with --user exits with one line saying it must start as root.

Does HarnessRouter need internet access on first start?

Yes. The agent CLIs are fetched on first start instead of being shipped in the image, and each one remains subject to its own licence and terms. Both 0.5.5 and current releases name failed installs in the log and let the other backends start. Installed CLIs are cached on the volume, so later starts are usually faster, though backend tools and the tasks you run can still need network access, and a new or previously failed backend can trigger another install.

I lost the console password. How do I get back in?

There is no reset email for the local Console login. Stop the container, delete /data/selfhost-auth.json from the volume, start it again, then sign in with your configured HR_AUTH_USER and HR_AUTH_PASSWORD, or the generated initial password if you did not supply your own, and set a new password from the Profile page. With the container and volume both named harnessrouter, that is docker stop harnessrouter, then docker run --rm -v harnessrouter:/data alpine rm -f /data/selfhost-auth.json, then docker start harnessrouter. Read the generated password with docker exec harnessrouter cat /data/selfhost-initial-password.

Was this article useful?