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.

fix(image): a fresh install could not install Claude Code or Codex, and said nothing

richard-epsilla9f673f1ebdfc
diff --git a/Dockerfile b/Dockerfile
index b9df9a51..d5321899 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -148,9 +148,22 @@ COPY --from=ui /ui/public /app/ui/public
# The agent CLIs refuse to run as root (they gate their own permission bypass on it), so the
# runtime user is unprivileged and owns the workspace and data volume.
+#
+# The `rm -rf /home/agent/.npm` is not tidying. HOME is already /home/agent while the kit apps are
+# built above, and those builds run as root — so npm leaves ~1600 root-owned files in the cache
+# the RUNTIME user then cannot write to. First start-up installs the agent CLIs into the data
+# volume as `agent`, npm hits EACCES on its own cache, and the install fails. Its output is
+# discarded (entrypoint.sh: `|| true`), so the only symptom is one WARN line and then every turn
+# on Claude Code or Codex failing. Hermes survives because it installs through pip, into a venv.
+#
+# That made two of the three backends unusable on any fresh volume — which is EVERY new install of
+# this image. It was invisible here because a long-lived volume keeps CLIs installed before the
+# fault existed. The cache is build-time garbage with no runtime value, so it is deleted rather
+# than chowned: nothing can inherit ownership of something that is not there.
RUN useradd -m -u 10001 agent \
+ && rm -rf /home/agent/.npm /root/.npm \
&& mkdir -p /data \
- && chown -R agent:agent /data /app \
+ && chown -R agent:agent /data /app /home/agent \
&& chmod -R a+rX /opt/harnessrouter/skills /opt/harnessrouter/kits
USER agent
diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh
index f687c961..8460a486 100644
--- a/docker/entrypoint.sh
+++ b/docker/entrypoint.sh
@@ -129,6 +129,23 @@ backend_bin() {
esac
}
+# Run an install and, if it fails, SAY WHY.
+#
+# This was `>/dev/null 2>&1 || true`, and the silence cost a day of someone's life: a root-owned
+# npm cache baked into the image made every `npm install` fail with EACCES, and the only trace was
+# the "requested but not installed" line further down — which reads like a configuration choice,
+# not a broken install. An optional step may fail without stopping start-up; it may not fail
+# without leaving the reason where the person looking will find it.
+try_install() {
+ label="$1"; shift
+ log="$(mktemp)"
+ if "$@" >"$log" 2>&1; then rm -f "$log"; return 0; fi
+ echo "[harnessrouter] WARN: could not install $label — it will not be available:"
+ tail -n 12 "$log" | sed 's/^/[harnessrouter] /'
+ rm -f "$log"
+ return 1
+}
+
install_backends() {
mkdir -p "$TOOLS"
@@ -136,20 +153,19 @@ install_backends() {
# entry point, which npm reports as success.
if wanted claude && [ ! -x "$(backend_bin claude)" ]; then
echo "[harnessrouter] installing Claude Code (Anthropic's terms apply)…"
- npm install -g --prefix "$TOOLS" --no-audit --no-fund @anthropic-ai/claude-code >/dev/null 2>&1 || true
+ try_install "Claude Code" npm install -g --prefix "$TOOLS" --no-audit --no-fund @anthropic-ai/claude-code || true
fi
if wanted codex && [ ! -x "$(backend_bin codex)" ]; then
echo "[harnessrouter] installing Codex (Apache-2.0)…"
- npm install -g --prefix "$TOOLS" --no-audit --no-fund @openai/codex >/dev/null 2>&1 || true
+ try_install "Codex" npm install -g --prefix "$TOOLS" --no-audit --no-fund @openai/codex || true
fi
if wanted hermes && [ ! -x "$(backend_bin hermes)" ]; then
echo "[harnessrouter] installing Hermes (check its upstream license before use)…"
- { "$PY" -m venv "$TOOLS/venv" \
- && "$TOOLS/venv/bin/pip" install --no-cache-dir -q \
- "hermes-agent==0.19.0" anthropic "$HERMES_MCP_PIN"; } \
- >/dev/null 2>&1 || true
+ try_install "Hermes" sh -c "\"$PY\" -m venv \"$TOOLS/venv\" \
+ && \"$TOOLS/venv/bin/pip\" install --no-cache-dir -q \
+ 'hermes-agent==0.19.0' anthropic '$HERMES_MCP_PIN'" || true
fi
[ -d "$TOOLS/venv/bin" ] && export PATH="$TOOLS/venv/bin:$PATH"