The workspace host
@claxedo/workspace-runtime is the per-workspace host — one process per
workspace — that owns everything pinned to a project directory: harness
lifecycle, sessions, terminals, managed processes, files, diffs, and runtime
events.
Two boundary rules define it:
- The host is the execution boundary. All agent work happens here, next to the code. A browser never talks to the host directly and never imports the package — it talks to your control plane, which routes to the right host.
- The host is not the authority boundary. Auth, org policy, credential storage, and “who may reach this workspace” live in your control plane. The host executes; your server decides.
Placement: host and toolSandbox
Section titled “Placement: host and toolSandbox”Where a session’s work lands is expressed by two real fields on the session
environment (SessionEnvFactoryInput in @claxedo/agent-sdk-runtime):
host: "central" | "workspace"— where the agent loop runs: on your central server, or inside a workspace-runtime host.toolSandbox?: SandboxRef— where the agent’s tools execute, when that differs. A{ kind: "workspace-runtime", workspaceId }ref keeps the loop central while exec/file side effects run inside the selected workspace.
The split is what makes local, cloud, and hybrid placement one model instead of
three products: the loop and the tools each get a location, and the same
/api/wr/* route surface serves a loopback host and a relay-attached host —
switched with one exposure option.
The directory can live anywhere
Section titled “The directory can live anywhere”The host only needs to run next to the project directory:
| Backing | How it works |
|---|---|
| Local worktree | The host runs next to a directory on the user’s machine; the product calls it over loopback. |
| Container | The host runs inside or beside a container where the directory is mounted. |
| Cloud VM | The host runs on a VM next to the checkout; reached directly on private networking or through Relay. |
| User-hosted team workspace | A user runs the host locally, it attaches to Relay, and authorized teammates reach it through the control plane. |
None of these change the client integration — that is the point.
The harness is not fixed
Section titled “The harness is not fixed”A host does not commit to one agent at boot. Config apply can arrive later and change harness id, access, or connection; the runtime disposes the old harness adapter and creates the matching one, live, without restarting the host. See Sessions, turns & events for why the harness is data.