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(selfhost): a login, so the image is safe to put on a public URL

richard-epsilladbfce9eb239c
diff --git a/.env.example b/.env.example
index 8f7e6f2e..1a45176e 100644
--- a/.env.example
+++ b/.env.example
@@ -26,3 +26,11 @@ HR_SECRET_GLOBAL_HARNESS_POLICY_CLAUDE={"chain":["anthropic"]}
# Everything else is configured for self-hosting by the entrypoint: local SQLite storage,
# no auth, no metering, a loopback runner, and direct key hand-off to the agent. You should
# not need to set them, and they are documented in the README if you want to.
+
+# ── console login ─────────────────────────────────────────────────────────────
+# The console creates harnesses, reads every transcript, and runs agents with your provider key.
+# These defaults are published in the README, so CHANGE THEM before the instance is reachable by
+# anyone but you.
+HR_AUTH_USER=harnessrouter
+HR_AUTH_PASSWORD=harnessrouter
+# HR_AUTH_DISABLED=1 # no gate at all — only for a box nobody else can reach
diff --git a/README.md b/README.md
index 33a871a0..4b0f5882 100644
--- a/README.md
+++ b/README.md
@@ -117,6 +117,41 @@ Harness CRUD (`/v1/harnesses`), the model catalog (`/v1/models`), sessions
(`/v1/sessions/{id}/turns`, `/cancel`) and task listing (`/v1/traces`) are all available on the
same surface.
+## Putting it on a public URL
+
+The console can create harnesses, read every task transcript, and run an agent with your
+provider key. So it ships with a login, on by default, covering the pages and the API alike:
+
+| | |
+|---|---|
+| `HR_AUTH_USER` | `harnessrouter` |
+| `HR_AUTH_PASSWORD` | `harnessrouter` |
+
+**Change the password before anyone else can reach the instance.** The defaults are printed
+right here, which makes them a placeholder, not a secret — the container warns on every start
+while the default is still in place. `HR_AUTH_DISABLED=1` removes the gate entirely, which is
+only reasonable on a machine nobody else can reach.
+
+For TLS, keep the console on loopback and put a terminating proxy in front. With Caddy that is
+one file and a real certificate, automatically:
+
+```caddyfile
+console.example.com {
+ encode zstd gzip
+ reverse_proxy 127.0.0.1:3000 {
+ flush_interval -1 # agent turns stream for minutes; never buffer them
+ }
+}
+```
+
+```bash
+docker run -d -p 127.0.0.1:3000:3000 -v harnessrouter:/data \
+ -e HR_AUTH_PASSWORD='something only you know' harnessrouter/harnessrouter
+```
+
+The `flush_interval -1` matters: without it a proxy buffers the event stream and the console
+looks frozen until the turn ends.
+
## Moving to the hosted service
When a harness is working the way you want, **Harnesses → Push to cloud** copies it into a
diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh
index 44381a11..194fc95e 100644
--- a/docker/entrypoint.sh
+++ b/docker/entrypoint.sh
@@ -51,6 +51,18 @@ fi
# the console's port is published.
export HARNESS_GATEWAY_URL="${HARNESS_GATEWAY_URL:-http://127.0.0.1:8080}"
export NEXT_PUBLIC_HR_EDITION=selfhost
+
+# ── console login ─────────────────────────────────────────────────────────────
+# The console can create harnesses, read every transcript, and run an agent with your provider
+# key, so an instance anyone can reach needs a gate. Defaults exist so the first run works; they
+# are also published in the README, which makes them a placeholder rather than a secret.
+export HR_AUTH_USER="${HR_AUTH_USER:-harnessrouter}"
+export HR_AUTH_PASSWORD="${HR_AUTH_PASSWORD:-harnessrouter}"
+if [ "${HR_AUTH_DISABLED:-}" = "1" ]; then
+ echo "[harnessrouter] WARNING: login is DISABLED (HR_AUTH_DISABLED=1) — anyone who can reach this port has full control"
+elif [ "$HR_AUTH_PASSWORD" = "harnessrouter" ]; then
+ echo "[harnessrouter] WARNING: using the DEFAULT password. Set HR_AUTH_PASSWORD before exposing this instance."
+fi
export PORT="${PORT:-3000}"
# ── agent CLIs: installed here, not shipped in the image ──────────────────────
diff --git a/ui/src/middleware.ts b/ui/src/middleware.ts
new file mode 100644
index 00000000..a32323f6
--- /dev/null
+++ b/ui/src/middleware.ts
@@ -0,0 +1,77 @@
+// The gate for a self-hosted instance that is reachable by anyone.
+//
+// Self-hosted has no accounts service, and on a machine only you can reach that is the right
+// answer — a login would be ceremony with nothing behind it. The moment the box has a public
+// URL that stops being true: the console can create harnesses, read every task transcript, and
+// run an agent with your provider key. So exposure needs a gate, and the gate ships INSIDE the
+// image rather than in whatever proxy happens to sit in front, because `docker run -p 3000:3000`
+// on a cloud host must be safe by default and not by configuration.
+//
+// Middleware is the chokepoint deliberately: pages, the /api/harness proxy, static assets and any
+// route added later all pass through here, so no individual handler can forget to check. HTTP
+// Basic is the mechanism because it needs no session store, no cookie signing and no login route
+// to keep in sync with the hosted edition's — fewer moving parts is the security argument.
+//
+// HR_AUTH_USER / HR_AUTH_PASSWORD set them. Defaults are published in the README, so an
+// instance still running them is open to anyone who read it.
+// HR_AUTH_DISABLED=1 no gate at all. Only for a box nobody else can reach.
+import { NextResponse, type NextRequest } from 'next/server';
+
+const SELF_HOSTED = process.env.NEXT_PUBLIC_HR_EDITION === 'selfhost';
+const DISABLED = process.env.HR_AUTH_DISABLED === '1';
+const USER = process.env.HR_AUTH_USER || 'harnessrouter';
+const PASSWORD = process.env.HR_AUTH_PASSWORD || 'harnessrouter';
+
+/** Length-independent comparison: a plain === leaks how much of the password was right through
+ * timing. Cheap to do properly, so do it properly. */
+function sameSecret(a: string, b: string): boolean {
+ const enc = new TextEncoder();
+ const x = enc.encode(a);
+ const y = enc.encode(b);
+ // Compare a fixed number of bytes so length alone doesn't change the timing.
+ let diff = x.length ^ y.length;
+ const n = Math.max(x.length, y.length);
+ for (let i = 0; i < n; i++) diff |= (x[i] ?? 0) ^ (y[i] ?? 0);
+ return diff === 0;
+}
+
+function unauthorized(): NextResponse {
+ return new NextResponse('Authentication required.', {
+ status: 401,
+ headers: {
+ // The realm is what the browser shows in its prompt.
+ 'WWW-Authenticate': 'Basic realm="HarnessRouter", charset="UTF-8"',
+ 'Cache-Control': 'no-store',
+ },
+ });
+}
+
+export function middleware(req: NextRequest) {
+ // Hosted has its own login; this gate exists only for the self-hosted image.
+ if (!SELF_HOSTED || DISABLED) return NextResponse.next();
+
+ const header = req.headers.get('authorization') || '';
+ if (header.toLowerCase().startsWith('basic ')) {
+ let decoded = '';
+ try {
+ decoded = atob(header.slice(6).trim());
+ } catch {
+ return unauthorized(); // malformed base64 is a failed attempt, not a server error
+ }
+ // Only the FIRST colon separates them — a password may legitimately contain one.
+ const i = decoded.indexOf(':');
+ const user = i < 0 ? decoded : decoded.slice(0, i);
+ const pass = i < 0 ? '' : decoded.slice(i + 1);
+ // Both are checked every time, so a wrong username costs the same as a wrong password.
+ const okUser = sameSecret(user, USER);
+ const okPass = sameSecret(pass, PASSWORD);
+ if (okUser && okPass) return NextResponse.next();
+ }
+ return unauthorized();
+}
+
+export const config = {
+ // Everything. The one exception is the favicon, so a browser tab doesn't provoke a second
+ // credential prompt before the page itself has asked for one.
+ matcher: ['/((?!favicon.ico).*)'],
+};