Skip to content

HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.

feat(release): build for both architectures, and stop killing the container people configure

richard-epsilla40565b4a2017
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 29dfc944..3750564b 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,11 +1,24 @@
-# Publish the all-in-one image to Docker Hub.
+# Publish the all-in-one image to Docker Hub, for both architectures people actually use.
#
# This exists because the alternative was a person minting a Docker Hub token by hand for every
# release, pasting it into a shell on a build VM, and then having to remember to revoke it. That
# is three chances to leak a credential and one chance to forget, per release.
#
# Here the token is a repository secret: it is written once, never read back, and never travels
-# through anyone's terminal or transcript. Publishing becomes `git tag v0.4.2 && git push --tags`.
+# through anyone's terminal or transcript. Publishing becomes `git tag v0.4.3 && git push --tags`.
+#
+# WHY THE BUILD FANS OUT AND THE TAG DOES NOT
+#
+# Each architecture builds on a runner of its own kind — no QEMU, so arm64 is not the slow long
+# pole it becomes under emulation — and each smoke-tests ITSELF on that runner. That second part
+# is the point: the gate that catches "the agent CLIs cannot install on a fresh volume" had only
+# ever run on amd64, so the guarantee was unproven on the architecture most developers have.
+#
+# The version tag is created ONCE, at the end, from both digests, and only if both smoke tests
+# passed. Publishing amd64 under the real tag and adding arm64 later would mean the tag names two
+# different things at two different times: whoever pulled during the window got a different
+# artifact and had no way to know. An arm64 user in that window would silently get the emulated
+# image and never learn a native one existed.
#
# ONE-TIME SETUP
# 1. hub.docker.com → account settings → Personal access tokens → Generate, "Read & Write".
@@ -21,7 +34,7 @@ on:
workflow_dispatch:
inputs:
version:
- description: 'Version to publish, without the v (e.g. 0.4.2)'
+ description: 'Version to publish, without the v (e.g. 0.4.3)'
required: true
latest:
description: 'Also move the :latest tag'
@@ -32,22 +45,20 @@ env:
IMAGE: harnessrouter/harnessrouter
jobs:
- publish:
+ # ── what we are about to ship ──────────────────────────────────────────────────────────────
+ # Resolved once, so both architectures bake the SAME skills and kits. Resolving per-arch would
+ # let a commit land between the two builds and produce a manifest whose halves disagree.
+ plan:
runs-on: ubuntu-latest
+ outputs:
+ version: ${{ steps.v.outputs.version }}
+ skills: ${{ steps.refs.outputs.skills }}
+ kits: ${{ steps.refs.outputs.kits }}
steps:
- - uses: actions/checkout@v4
-
- # The image is ~2 GB unpacked and the runner ships with several GB of Android SDK and .NET
- # nobody here needs. Without this the build dies on "no space left on device" somewhere in
- # the middle, which reads like a broken Dockerfile.
- - name: Reclaim runner disk
- run: |
- sudo rm -rf /usr/local/lib/android /usr/share/dotnet /opt/ghc /usr/local/share/boost
- df -h / | tail -1
-
- name: Work out the version
id: v
run: |
+ set -euo pipefail
if [ "${{ github.event_name }}" = workflow_dispatch ]; then
V='${{ inputs.version }}'
else
@@ -60,13 +71,6 @@ jobs:
echo "version=$V" >> "$GITHUB_OUTPUT"
echo "Publishing $V"
- - uses: docker/setup-buildx-action@v3
-
- - uses: docker/login-action@v3
- with:
- username: ${{ secrets.DOCKERHUB_USERNAME }}
- password: ${{ secrets.DOCKERHUB_TOKEN }}
-
# The skills and the kits are pulled from their own repositories at build time, and a release
# must never ship the catalogue some earlier build happened to fetch. Resolving both heads to
# a sha HERE is what guarantees that: the sha is a build arg, so the layer rebuilds exactly
@@ -94,46 +98,139 @@ jobs:
resolve skills skills
resolve starter-kit kits
- - name: Build and push
+ # ── one runner per architecture ────────────────────────────────────────────────────────────
+ build:
+ needs: plan
+ strategy:
+ fail-fast: false # a failure on one arch should still show the other's result
+ matrix:
+ include:
+ - platform: linux/amd64
+ arch: amd64
+ runner: ubuntu-latest
+ - platform: linux/arm64
+ arch: arm64
+ runner: ubuntu-24.04-arm # native; QEMU here would take the best part of an hour
+ runs-on: ${{ matrix.runner }}
+ steps:
+ - uses: actions/checkout@v4
+
+ # The image is ~2 GB unpacked and the runner ships with several GB of Android SDK and .NET
+ # nobody here needs. Without this the build dies on "no space left on device" somewhere in
+ # the middle, which reads like a broken Dockerfile.
+ - name: Reclaim runner disk
+ run: |
+ sudo rm -rf /usr/local/lib/android /usr/share/dotnet /opt/ghc /usr/local/share/boost || true
+ df -h / | tail -1
+
+ - uses: docker/setup-buildx-action@v3
+
+ - uses: docker/login-action@v3
+ with:
+ username: ${{ secrets.DOCKERHUB_USERNAME }}
+ password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+ # Pushed BY DIGEST, with no tag. Nothing a user can pull exists until the merge job says so.
+ - name: Build and push by digest
+ id: build
uses: docker/build-push-action@v6
with:
context: .
- platforms: linux/amd64
- push: true
+ platforms: ${{ matrix.platform }}
build-args: |
- HR_SKILLS_REF=${{ steps.refs.outputs.skills }}
- HR_KITS_REF=${{ steps.refs.outputs.kits }}
- tags: |
- ${{ env.IMAGE }}:${{ steps.v.outputs.version }}
- ${{ (github.event_name != 'workflow_dispatch' || inputs.latest) && format('{0}:latest', env.IMAGE) || '' }}
- cache-from: type=gha
- cache-to: type=gha,mode=max
+ HR_SKILLS_REF=${{ needs.plan.outputs.skills }}
+ HR_KITS_REF=${{ needs.plan.outputs.kits }}
+ outputs: type=image,name=${{ env.IMAGE }},push-by-digest=true,name-canonical=true,push=true
+ cache-from: type=gha,scope=${{ matrix.arch }}
+ cache-to: type=gha,mode=max,scope=${{ matrix.arch }}
# A published image that cannot install its agent CLIs is the failure this project has
# already shipped once (a root-owned npm cache in /home/agent). It was invisible because
# every instance that was checked had a data volume from before the fault. So the release
- # gate runs the image the way a NEW user does: empty volume, and read what it says.
- - name: Smoke-test the published image on a fresh volume
+ # gate runs the image the way a NEW user does: empty volume, and read what it says — and now
+ # it does that on EACH architecture, on hardware of that architecture.
+ - name: Smoke-test this architecture on a fresh volume
run: |
+ set -euo pipefail
+ REF="${{ env.IMAGE }}@${{ steps.build.outputs.digest }}"
docker rm -f smoke 2>/dev/null || true
docker volume rm smoke-data 2>/dev/null || true
- docker run -d --name smoke -v smoke-data:/data \
- -e HR_SECRET_KEY=ci-smoke ${{ env.IMAGE }}:${{ steps.v.outputs.version }}
+ docker run -d --name smoke -v smoke-data:/data -e HR_SECRET_KEY=ci-smoke "$REF"
for i in $(seq 1 60); do
docker logs smoke 2>&1 | grep -q "backends available" && break
sleep 5
done
docker logs smoke 2>&1 | tail -30
- LINE=$(docker logs smoke 2>&1 | grep "backends available" | tail -1)
+ LINE=$(docker logs smoke 2>&1 | grep "backends available" | tail -1 || true)
echo "$LINE"
for b in claude codex hermes; do
- echo "$LINE" | grep -q "$b" || { echo "::error::$b did not install on a fresh volume"; exit 1; }
+ echo "$LINE" | grep -q "$b" || { echo "::error::$b did not install on ${{ matrix.arch }}"; exit 1; }
done
docker exec smoke ls /opt/harnessrouter/kits
+ # The architecture is asserted, not assumed: a QEMU fallback would otherwise pass here
+ # silently and ship an emulated image under the native manifest.
+ GOT=$(docker image inspect "$REF" --format '{{.Architecture}}')
+ [ "$GOT" = "${{ matrix.arch }}" ] || { echo "::error::built $GOT, expected ${{ matrix.arch }}"; exit 1; }
+ echo "${{ matrix.arch }} ok"
+
+ - name: Hand the digest to the merge
+ run: |
+ mkdir -p /tmp/digests
+ echo "${{ steps.build.outputs.digest }}" > "/tmp/digests/${{ matrix.arch }}"
+ - uses: actions/upload-artifact@v4
+ with:
+ name: digest-${{ matrix.arch }}
+ path: /tmp/digests/*
+ retention-days: 1
+
+ # ── the tag, created once, from both ───────────────────────────────────────────────────────
+ merge:
+ needs: [plan, build]
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/download-artifact@v4
+ with:
+ path: /tmp/digests
+ pattern: digest-*
+ merge-multiple: true
+
+ - uses: docker/setup-buildx-action@v3
+ - uses: docker/login-action@v3
+ with:
+ username: ${{ secrets.DOCKERHUB_USERNAME }}
+ password: ${{ secrets.DOCKERHUB_TOKEN }}
- - name: Say what shipped
+ - name: Create the manifest
run: |
- echo "### harnessrouter ${{ steps.v.outputs.version }}" >> "$GITHUB_STEP_SUMMARY"
- echo '```' >> "$GITHUB_STEP_SUMMARY"
- echo "docker pull ${{ env.IMAGE }}:${{ steps.v.outputs.version }}" >> "$GITHUB_STEP_SUMMARY"
- echo '```' >> "$GITHUB_STEP_SUMMARY"
+ set -euo pipefail
+ V='${{ needs.plan.outputs.version }}'
+ REFS=""
+ for f in /tmp/digests/*; do
+ REFS="$REFS ${{ env.IMAGE }}@$(cat "$f")"
+ echo "$(basename "$f") $(cat "$f")"
+ done
+ [ -n "$REFS" ] || { echo "::error::no digests to merge"; exit 1; }
+ TAGS="-t ${{ env.IMAGE }}:$V"
+ if [ "${{ github.event_name }}" != workflow_dispatch ] || [ "${{ inputs.latest }}" = true ]; then
+ TAGS="$TAGS -t ${{ env.IMAGE }}:latest"
+ fi
+ docker buildx imagetools create $TAGS $REFS
+
+ # Read the published manifest back: the promise of this workflow is that the tag serves both
+ # architectures, and only the registry can confirm it.
+ - name: Prove the tag serves both architectures
+ run: |
+ set -euo pipefail
+ V='${{ needs.plan.outputs.version }}'
+ PLAT=$(docker buildx imagetools inspect "${{ env.IMAGE }}:$V" --raw \
+ | jq -r '.manifests[]?.platform | select(.os=="linux") | "\(.os)/\(.architecture)"' | sort -u)
+ echo "$PLAT"
+ echo "$PLAT" | grep -qx 'linux/amd64' || { echo "::error::amd64 missing from $V"; exit 1; }
+ echo "$PLAT" | grep -qx 'linux/arm64' || { echo "::error::arm64 missing from $V"; exit 1; }
+ {
+ echo "### harnessrouter $V"
+ echo '```'
+ echo "docker pull ${{ env.IMAGE }}:$V"
+ echo '```'
+ echo "$PLAT" | sed 's/^/- /'
+ } >> "$GITHUB_STEP_SUMMARY"
diff --git a/README.md b/README.md
index 071e7543..98c8db94 100644
--- a/README.md
+++ b/README.md
@@ -37,11 +37,10 @@ own data. Configure a harness, give it work, watch it run, with no account, no c
## Install
Six steps, and at the end of them you have a running instance, a signed-in console, and an agent
-that has answered you. Everything here was run against the published 0.4.2 release on a brand-new
-volume, and every block of output is what it actually printed.
+that has answered you.
-You need Docker, about 4 GB of disk (2.7 GB of image and around a gigabyte in the data volume once
-the agent CLIs install), and an API key from a model provider. There is no account to create and
+You need Docker, about 4 GB of disk, and an API key from a model provider. There is no account to
+create and
nothing to sign up for. The provider key is the only credential in the story, and it never leaves
the box except to call the provider it belongs to.
@@ -51,11 +50,11 @@ the box except to call the provider it belongs to.
docker pull harnessrouter/harnessrouter
```
-716 MB over the wire, in 25 layers.
+About 700 MB to download.
`latest` is the current release, and pulling it again is how you upgrade. Pin a version only
-when you need two machines to run the same bytes, for instance `harnessrouter/harnessrouter:0.4.2`
-in a compose file you share with a team. `docker image inspect` will tell you which one you have.
+when you need two machines to run the same bytes, by naming a version in a compose file you share
+with a team. Releases are listed on [Docker Hub](https://hub.docker.com/r/harnessrouter/harnessrouter/tags).
**The published image is `linux/amd64` only.** On an Apple Silicon Mac, `docker pull` gets an
emulated image: a platform warning, and a first start that is already slow made slower.
@@ -105,7 +104,7 @@ an afternoon:
A pairing that is not on that list does not fail loudly: the turn comes back empty after a long
wait. So if a turn returns nothing at all, check the pair before you check the key. In particular
`"provider":"openai-api"`, which `.env.example` still shows for a custom endpoint, is not one a
-backend accepts in 0.4.2; use `"openai"` with a `base_url`, as above.
+backend accepts; use `"openai"` with a `base_url`, as above.
A backend with no policy at all is more forthcoming, and this is what you get if you skip this step
entirely:
@@ -169,13 +168,12 @@ Installing them on first run means you install them yourself, from upstream, und
which is also why you should read them before you use those two backends. Codex is Apache-2.0 and
arrives the same way, so all three land in one place.
-On the machine this was measured on the whole sequence took **35 seconds**: Claude Code 4s, Codex
-5s, Hermes 24s, then two more for the services behind the console. A slow connection makes it
-longer. `backends available:` is the line worth reading: it lists what actually installed, so a
-backend that failed is named rather than silently missing, and the others still work.
+Expect about half a minute, longer on a slow connection. `backends available:` is the line worth
+reading: it lists what actually installed, so a backend that failed is named rather than silently
+missing, and the others still work.
-The install is once per volume, not once per start. Starting a fresh container against that same
-volume took **3 seconds** and printed no install lines at all.
+This happens once per volume, not once per start. Every start after it takes a few seconds and
+prints no install lines at all.
If you skipped `HR_AUTH_PASSWORD` in step 3, one more line comes first, and comes back on every
start until you fix it:
@@ -230,7 +228,7 @@ the instance is gone; copy it and you have moved the instance, harnesses, transc
## Starter kits
A kit is a working product in one click. It provisions the harness it needs, installs the skill
-that teaches that agent the product's format, and opens its own app. 0.4.2 ships four.
+that teaches that agent the product's format, and opens its own app. There are four.
![The four starter kits, before any of them has been launched](docs/images/dashboard-1-starter-kits.png)
@@ -432,7 +430,7 @@ want is a run-time setting:
docker run -e HR_BACKENDS=claude,codex,hermes ... # the default
```
-**Known issue in 0.4.2: any value that leaves out `hermes` makes the container exit immediately**
+**Known issue: any value that leaves out `hermes` makes the container exit immediately**
with status 1 and no error message. `claude`, `codex` and `claude,codex` all do it, and the last
line in the log is the install line for the backend it was working on, so it reads as if the
install killed it, which it did not. Until that is fixed, leave `HR_BACKENDS` unset.
@@ -479,7 +477,7 @@ Then run a turn. The gateway speaks the Responses API:
```bash
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: HarnessRouter 0.4.2 verified.",
+ -d '{"input":"Reply with exactly this and nothing else: it works.",
"metadata":{"harness_id":"codex"},
"model":"gpt-5.4-mini",
"stream":false}'
@@ -491,7 +489,7 @@ curl -s -b hr.cookies http://localhost:3000/api/harness/v1/responses \
"model":"gpt-5.4-mini",
"output":[{"id":"msg_3d71e018c6584abbb063ee16d9a36e75","type":"message","status":"completed",
"role":"assistant",
- "content":[{"type":"output_text","text":"HarnessRouter 0.4.2 verified.","annotations":[]}]}],
+ "content":[{"type":"output_text","text":"it works.","annotations":[]}]}],
"store":true,
"usage":{"input_tokens":10878,"output_tokens":34,"total_tokens":10912},
"metadata":{"session_id":"hsessa79756fab07a4bf58fa072be24d5ce59"}}
diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh
index 8460a486..76a3d572 100644
--- a/docker/entrypoint.sh
+++ b/docker/entrypoint.sh
@@ -171,7 +171,12 @@ install_backends() {
[ -d "$TOOLS/venv/bin" ] && export PATH="$TOOLS/venv/bin:$PATH"
# Hermes otherwise tries to install its own dependencies mid-turn.
export HERMES_DISABLE_LAZY_INSTALLS=1
- wanted hermes && verify_hermes_mcp
+ # `wanted hermes && verify_hermes_mcp` looks equivalent and is not: as the LAST command in the
+ # function it becomes the function's exit status, so under `set -e` an instance that did not ask
+ # for hermes aborted the whole entrypoint — exit 1, no message, the log ending on an install line
+ # so it read as if the install had killed it. HR_BACKENDS=claude, =codex and =claude,codex were
+ # all unusable, which is exactly the choice the licence note above asks people to make.
+ if wanted hermes; then verify_hermes_mcp; fi
}
# hermes 0.19.0 gates HTTP MCP on importing `streamablehttp_client`, the name the mcp SDK