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.
Python agent-apiagent-frameworkagent-harnessai-agentsai-infrastructurecoding-agentconformance-testingdeepseek-harnessharness-engineeringhermesllmopen-protocolopen-sourceopen-standardpi-coding-agentself-hosteduhpunified-apiunified-harness-protocolunified-interface
fix: session workspaces are durable, and idle ones are reclaimed
richard-epsillaed8316d7bc97
diff --git a/Dockerfile b/Dockerfileindex 721a964a..b0361e3b 100644--- a/Dockerfile+++ b/Dockerfile@@ -53,7 +53,7 @@ ENV DEBIAN_FRONTEND=noninteractive \PIP_NO_CACHE_DIR=1 \NEXT_TELEMETRY_DISABLED=1 \HOME=/home/agent \- HARNESS_WORKSPACE=/workspace \+ HARNESS_WORKSPACE=/data/workspaces \HR_DATA_DIR=/dataRUN apt-get update -y && apt-get install -y --no-install-recommends \@@ -108,8 +108,8 @@ 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.RUN useradd -m -u 10001 agent \- && mkdir -p /workspace /data \- && chown -R agent:agent /workspace /data /app+ && mkdir -p /data \+ && chown -R agent:agent /data /appUSER agentEXPOSE 3000diff --git a/README.md b/README.mdindex a282f14c..33a871a0 100644--- a/README.md+++ b/README.md@@ -94,6 +94,8 @@ docker build -t harnessrouter --build-arg WITH_BROWSER=1 .| `POOL_MGMT_ENDPOINT` | `http://127.0.0.1:8081` | The runner is in this container. || `HR_POOL_AUTH` | `none` | No cloud identity to present to a loopback runner. || `HR_SANDBOX_TRUST` | `owner` | You own the box, the agent and the key, so the key is handed over directly rather than brokered. |+| `HARNESS_WORKSPACE` | `/data/workspaces` | One directory per session, on the volume — so a restart doesn't discard work in flight. |+| `HR_WORKSPACE_TTL_HOURS` | `72` | Idle session workspaces are removed after this. They rehydrate from their checkpoint, so this costs time, not work. `0` keeps them forever. || `HARNESS_INTERNAL_KEY` | generated | Per-container; never leaves the process tree. |</details>@@ -127,16 +129,22 @@ each claiming to be current. Your hosted key is used for that one request and is## Architecture```-┌─ container ────────────────────────────────────────────┐-│ UI (Next.js) :3000 ← the only published port │-│ │ same-origin proxy │-│ Gateway :8080 Responses API, harness CRUD │-│ │ loopback │-│ Runner :8081 spawns the agent CLI on /workspace│-└────────────────────────┬───────────────────────────────┘- /data (volume): SQLite, blobs, secrets+┌─ container ─────────────────────────────────────────────┐+│ UI (Next.js) :3000 ← the only published port │+│ │ same-origin proxy │+│ Gateway :8080 Responses API, harness CRUD │+│ │ loopback │+│ Runner :8081 one agent CLI per session │+└─────────────────────────┬───────────────────────────────┘+ /data (volume): SQLite, blobs, secrets, workspaces```+Sessions run concurrently and are isolated: each gets its own workspace directory, its own+conversation state, and its own checkpoint. Turn concurrency defaults to the machine's core+count — this box cannot scale sandboxes on demand the way the hosted deployment does, so the+limit is what it can actually run. Publish the port to loopback (`-p 127.0.0.1:3000:3000`) if+the host is reachable from anywhere you don't control: there is no login to stop a visitor.+Storage sits behind a small adapter interface (graph / blob / secret). This repo ships the localimplementations; the hosted deployment overlays its own against the same interface. That seam iswhy this is genuinely the same codebase rather than a fork that drifts.diff --git a/docker/entrypoint.sh b/docker/entrypoint.shindex 819eb636..44381a11 100644--- a/docker/entrypoint.sh+++ b/docker/entrypoint.sh@@ -9,6 +9,12 @@ set -euo pipefailDATA_DIR="${HR_DATA_DIR:-/data}"mkdir -p "$DATA_DIR"+# Session workspaces live on the volume so a restart doesn't discard work in flight. Created HERE+# rather than in the image: /data is a volume mount, and Docker only seeds a volume from the image+# when the volume is empty — so an image-time mkdir is invisible on every existing install.+export HARNESS_WORKSPACE="${HARNESS_WORKSPACE:-$DATA_DIR/workspaces}"+mkdir -p "$HARNESS_WORKSPACE"+# Our own processes must run on the image's interpreter, never on whatever a backend puts on# PATH. Hermes installs into its own venv and that venv's bin joins PATH below so the runner can# spawn `hermes` — but that venv has none of the gateway's dependencies, so resolving `python3`diff --git a/runner/server.py b/runner/server.pyindex 6d7f6062..3eb077e5 100644--- a/runner/server.py+++ b/runner/server.py@@ -61,6 +61,43 @@ WORKSPACE_ROOT = os.environ.get("HARNESS_WORKSPACE", "/workspace")_SID_SAFE = re.compile(r"[^A-Za-z0-9._-]")+# How long an untouched session workspace is kept. Sessions are resumable from their checkpoint,+# so a reaped directory costs a rehydrate, not the work — but keeping every one forever fills the+# disk of a box nobody is watching. 0 disables.+WS_TTL_HOURS = float(os.environ.get("HR_WORKSPACE_TTL_HOURS", "72") or 0)+++def _reap_workspaces(keep: str = "") -> int:+ """Delete session workspaces untouched for longer than the TTL. Cheap, and only ever called+ at hydrate — the moment we already know a session is starting fresh."""+ if WS_TTL_HOURS <= 0:+ return 0+ cutoff = time.time() - WS_TTL_HOURS * 3600+ removed = 0+ try:+ entries = list(os.scandir(WORKSPACE_ROOT))+ except OSError:+ return 0+ for e in entries:+ if not e.is_dir() or e.name == keep:+ continue+ try:+ # mtime of the directory tracks the last write into it; a running turn keeps it fresh.+ if e.stat().st_mtime >= cutoff:+ continue+ shutil.rmtree(e.path, ignore_errors=True)+ try:+ _ws_marker_path(e.name).unlink()+ except OSError:+ pass+ removed += 1+ except OSError:+ continue+ if removed:+ print(f"[reap] removed {removed} workspace(s) idle > {WS_TTL_HOURS}h", flush=True)+ return removed++def _ws(identifier: str = "") -> str:"""This session's workspace directory.@@ -1613,6 +1650,7 @@ async def hydrate(request: Request, identifier: str = "") -> dict:materializes in the sandbox's ~2 GiB RAM. sha256 folds over the incoming stream; untar readsfrom the spooled file. CRITICALLY, the spool completes BEFORE the workspace wipe — a truncatedupload (client disconnect) raises during spooling and leaves the current workspace untouched."""+ _reap_workspaces(keep=_SID_SAFE.sub("_", (identifier or "").strip())[:120] or "_default")ws = _ws(identifier)ws_path = pathlib.Path(ws)ws_path.mkdir(parents=True, exist_ok=True)