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: session workspaces are durable, and idle ones are reclaimed

richard-epsillaed8316d7bc97
diff --git a/Dockerfile b/Dockerfile
index 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=/data
RUN 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 /app
USER agent
EXPOSE 3000
diff --git a/README.md b/README.md
index 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 local
implementations; the hosted deployment overlays its own against the same interface. That seam is
why this is genuinely the same codebase rather than a fork that drifts.
diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh
index 819eb636..44381a11 100644
--- a/docker/entrypoint.sh
+++ b/docker/entrypoint.sh
@@ -9,6 +9,12 @@ set -euo pipefail
DATA_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.py
index 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 reads
from the spooled file. CRITICALLY, the spool completes BEFORE the workspace wipe — a truncated
upload (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)