Handbook
Forge runner
A Forge runner is any executable (CLI, script, container entrypoint, or library main) that implements a workcell: it accepts a WorkcellRequest-shaped input and produces a WorkcellResult-shaped output linked to an…
A runner is not:
- A Forge Agent (that is the session pattern)
- An AgentRun record (
arun_*) - A ForgeRun container (
frun_*) - Fleet itself (Fleet schedules containers; the runner is inside or beside the job)
Runner vs workcell id
| Layer | Example |
|---|---|
| Workcell id | local_llm_worker |
| Runner host repo | forge-workcells |
| Entrypoint | forge-workcells run --workcell local_llm_worker |
See the full matrix in Workcell catalog.
Host-repo matrix (summary)
| Workcell id | Runner host | Entrypoint |
|---|---|---|
local_runner |
forge-platform | scripts/selfhost_runner.py |
local_llm_worker |
forge-workcells | forge-workcells run |
campaign_orchestrator |
operator host / CI | orchestrator CLI (planned) |
fleet_ux_worker |
Fleet container | image CMD + workspace bridge |
hermes |
Hermes product | Hermes runtime |
factory |
Factory Droid | Factory runtime |
cursor_cli |
operator / container | agent -p (governed) |
openclaw |
OpenClaw | channel gateway |
Where new runners land
Default: implement shared bounded runners in forge-workcells (private) and document the workcell id here.
Exceptions (documented in handbook):
- Self-Host Alpha —
local_runnerstays in forge-platform until migration (see Self-Host local runner). - Product-specific operators (Hermes, Factory, OpenClaw) — runners live in their product repos; platform owns contracts only.