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.
Environments
A project's files and its installed dependencies, built once and read by every task session that
names it. This is the design of record for the self-hosted server (shipped in 0.26) and for the
hosted service (to be built to the same contract); the wire contract is the
Environments chapter of UHP 2026-09-28.
The problem it solves
A session's working directory is made for one conversation. It starts empty, is checkpointed after every turn as a tarball with dependency directories excluded, and is restored before the next turn. Everything a task needs is uploaded into it, and everything it installs is reinstalled the next time. For a task that is a project, a content pipeline with scripts, assets, templates and a hundred packages, opened by several people many times a day, that is the wrong shape (Spiral, SPI-001 to SPI-004): every session paid the upload and the install again, and two sessions could not share one copy.
The contract a session sees
/env/content-studio the environment: complete, READ-ONLY, shared by every session
scripts/ assets/ data/ … the project's files, as the owner put them in
.venv/ node_modules/ installed once, when the environment was built
/data/workspaces/<sid> the session's working directory: writable, private, checkpointed,
the only place artifacts come from (unchanged)
PROJECT_ROOT=/env/content-studio
PATH=/env/content-studio/.venv/bin:/env/content-studio/node_modules/.bin:…
PYTHONPATH=/env/content-studio NODE_PATH=/env/content-studio/node_modules:…
The agent's instruction file carries a "Project environment" section (runner/environments.py,
doc_section): where the project is, that it is read-only and shared, that its dependencies are
installed, to write outputs to the working directory, to run scripts by absolute path, and the
owner's entry line when there is one. Richard's decision (2026-09-28): a fixed read-only path
with a private cwd, not a copy-on-write working directory inside the project; the reasons are in
the chapter's first note.
Objects and operations
An environment (henv_…) belongs to an org and a workspace, like a harness. It has a source
(the files the owner edits: upload one by one, import an archive or a git repository, edit in the
console), versions (builds: the source copied, then .venv / node_modules installed from
requirements.txt / pyproject.toml / package.json, then setup.sh, then the tree made
read-only), and one active version, the one sessions read. A build that succeeds becomes
active; a failed one changes nothing; rollback is a pointer to an earlier build. A harness names
the environment its tasks read; a task can name another. A task on an environment with nothing
built is refused before it starts (environment_not_ready).
Routes: /v1/environments, …/{id}, …/{id}/files[/{path}], …/{id}/import, …/{id}/build,
…/{id}/builds/{n}, …/{id}/versions[/{n}/activate], …/{id}/harnesses; environment on the
harness object and on POST /v1/responses; environment on the session object.
Self-hosted implementation (this repository)
- Record: the gateway (
gateway/app.py, "Environments" section): anEnvironmentvertex with org, workspace, name, slug, description, entry, status, active/latest version, the versions list and the active build's packages, refreshed from the runner on reads. - Bytes: the runner (
runner/environments.py) owns/data/environments/<id>/:source/(editable,0700),versions/<n>/(a build,root:<env group>0750/0640, with.hr-build.json: status, log, packages, size),active→versions/<n>. The mount/env/<slug>is a link toactive, on the container's rootfs, remade lazily after a restart. Builds run in a thread of the runner with the image's ownpython3andnpm, caches in a scratch directory, a wall clock ofHR_ENV_BUILD_TIMEOUT(1800 s). Dependency directories in the source are never copied. - Read-only, and read by its own sessions only: the write-wall (
HR_SESSION_UIDS): an agent runs as its session's uid, the layer is root's, so a write fails with EACCES. Each environment has a group of its own (GID_BASE60000 + a hash of the id; the environment directory's group IS the record, as the workspace's owner is the session uid's). The source is0700, the runner's alone; a built version is0750/0640, the group's to read; the agent process joins that group (extra_groups) only for a turn whose harness names the environment, so a session reads the one environment it was given and no other./data/environmentsand/envare0751: traversable, not listable, so a session cannot enumerate the rest. pip, npm andsetup.shrun the packages' own code, so a build runs them as the environment's identity (uid = gid = the environment's number) that owns the layer under construction and nothing else; apt-get anddpkg -xrun no package code and stay the runner's. A store from before groups is migrated once at start (secure_store). Without the wall (a development box) the modes still hold for any non-root agent; root is the operator's own choice. Measured on hr-test 2026-09-28: before the groups, any session could list and read every environment's source and layers; after, a session reads its own and gets EACCES on the others. - While it builds: the runner writes
.hr-build.jsonas each step ends, withstage(copying files, python packages, node packages, system packages, setup.sh, finishing) and the log so far; the page polls it every 3 s and shows a strip with the stage, the elapsed seconds and the log tail. Add asksGET /v1/environments/packages/check(runnercheck_package: PyPI JSON, the npm registry, the box's apt lists) and refuses a name that is not there or a pin that was never published; a row reads the installed version, or "installing", or "installs on save" with the version the registry reported. - The turn: the gateway resolves the environment (
metadata.environmenton the request, else the harness's) before anything is allocated, passes{id, slug, entry}to the runner, stamps the session vertex withenvironmentand the turn record with the version. The runner resolves the mount before writing the agent doc (a 409 there fails the turn before any process starts), then sets the variables. - Checkpoints are unchanged: the environment is outside the workspace, so it is never in one.
How the hosted service implements it
Reviewed with the hosted session on 2026-09-28; the corrections are theirs. The hosted service runs
one session per Azure Container Apps dynamic session out of the custom-container pool
(harness-sessions-e2: 1 vCPU, 2 GiB, about 4 GiB of ephemeral disk, a 1800 s cooldown after
which the container is recycled). There is no pool host to keep a cache on, no volume and no bind
mount a session can be given, and nothing in a sandbox may hold a blob credential. The same
contract is built like this:
- Record. The same
Environmentvertex on the HR tenant, registered with the seed script (label and edges) before the gateway that writes it rolls, as the billing labels were: a write before the seed 400s. Same routes, same object,mountstays/env/<slug>. - Source. One blob per file (
environments/<id>/source/<path>) plus a small index blob with the tree, so the console's editor reads and writes one file at a time. A build materialisesenvironments/<id>/versions/<n>/source.tgzfrom them first, so the build's input is one immutable object: reproducible, one download. - Build = a sandbox job, never a gateway thread. A gateway replica has no toolchain, no disk
and may restart. The build takes a sandbox from the pool under the identifier
env-<id>-<n>(no colons; the charset is the pool's), the policy gate runs BEFORE the sandbox is allocated (deficit and plan refusals; a build counts as a task for the Free plan's concurrency), and the "one build at a time per environment" lock and the build's status live in the control store as a lease with a TTL, swept by the straggler sweep, exactly as turns are, so a replica restart orphans nothing. Inside the sandbox the samerunner/environments.py::_buildruns (the one function both sides call), withsource.tgzas its input and a 1800 s wall clock. The build is metered as agent work under the org, with its own receipt line ("Environment build",agent.active_second, the per-task cost cap applied), not a new ledger unit. - Blob access is the gateway's, in one shape. The sandbox never sees the account key. For the
layer, the gateway mints a per-blob, minutes-lived SAS (write-only for the build's output,
read-only for a turn's input) and hands it in the build or turn body, so a layer of a few
hundred MB does not pass through a gateway replica that has no disk. The build writes
layer.tgz(zstd) and.hr-build.json(status, log, packages, sizes) with its write SAS; a turn's hydrate downloadslayer.tgzwith its read SAS. The source files and index are written only by the API (the gateway streams them itself, as it streams checkpoints). - The mount = extract at hydrate. This IS the hosted design, not a first slice: when a turn
names an environment,
/hydratedownloads the active version'slayer.tgzand extracts it to/env/<slug>once per session lifetime (the container lives until the cooldown recycles it, so later turns of the session find it in place), root-owned with 755/644 as extracted, nochmod -Rpass; the agent runs as the image's agent uid (10001), which is the same wall the self-hosted server uses. The turn record carriesenv_hydrate_msso the cost is visible. If sharing a layer across sessions is ever needed, the ACA-native shape is a session pool whose image bakes the layer, a different product decision; a bind mount is not promised. - Isolation. The container is the boundary: one session cannot see another's container at all, and a container holds only the environment its turn named (the hydrate downloads that layer and no other), which is the group model's outcome without the groups; the layer is root's and the agent is not; the source and the layers are written only by the API and the build's write SAS. The build runs in its own job container, never in a session's.
- Versions, rollback, retention.
active_versionon the vertex is the pointer; the gateway passesversionin the turn body so a hydrate is deterministic, and stamps the session with the version it started on, which later turns of that session keep. The active version plus the last three are kept; an environment's blobs are deleted with it; layers are counted in/internal/storage-usage. - Sizes. The ephemeral disk also holds the workspace, so the layer cap is a fraction of it, per
plan, enforced at build time from the recorded size: a layer over the cap fails the build with
the size in the log. Import 512 MiB and file 64 MiB stay the env-tunable caps; measure the disk
with
dfin a session before writing the number into a plan.
What is not in this slice
- Environment-level system packages (apt): the image provides
ffmpeg, LibreOffice, Playwright; a project that needs more says so insetup.sh, which runs with the build's privileges. - Cross-workspace sharing beyond the org's workspaces; a marketplace of environments.
- Controlled updates from inside a session (SPI-006): a session cannot write the environment; a "promote these files to the next version" flow is a later design with review and versioning.