ADR-0095: The built-in local runner can be turned off
Context and Problem Statement
The built-in local runner always existed: server.localRunner only set its tags and concurrency, and an agent with neither runner: nor runnerTags: runs on it. A server meant only to orchestrate, with its agents on external pull runners (ADR-0066), Kubernetes or SSH, therefore still ran any agent that missed its routing inside its own container. There the run either fails for lack of tools (the slim image has no agent CLIs) or executes agent code next to the server's config, secrets and SQLite database. The operator had no way to make the server refuse such a run.
Decision Drivers
- An operator can keep agent runs out of the server container entirely (root CLAUDE.md §12: name the trust boundary, fail closed).
- A misrouted run fails with a reason that names the fix, without waiting.
- One agent directory can serve servers with and without a local runner.
- Existing configurations behave exactly as before.
Considered Options
server.localRunner.enabled(defaulttrue): withfalseno local consumer is registered and a claim forlocalfails before it is queued- The same switch, but let a claim for
localwait in the queue until its TTL - Reject at agent load every agent that routes to
localwhile it is off server.localRunner.concurrency: 0as "off"
Decision Outcome
Chosen option: server.localRunner.enabled, failing a claim for local before it is queued.
- With
enabled: false,RunnerWiringregisters noLocalRunnerconsumer and tellsRunnerRegistrythatlocalis off.RunnerRegistry.forAlias("local")then throws aConfigurationExceptionnaming the setting. This covers an agent with no routing, one withrunner: local, and arunnerCmdstep targetinglocal. The message names no other runner alias (ADR-0077). - This amends ADR-0066's invariant that every run reaches a runner through the claim queue. A run for a disabled
localnever reaches the queue. Nothing could ever claim it, so queueing it would only turn a configuration error into a stall ofrunnerClaimTimeoutSec. tagsandconcurrencyare refused whileenabledisfalse, in the model and in the JSON schema, because they would never apply.GET /api/v1/runnersdoes not list a disabledlocal.
Consequences
- Good: a server can guarantee that no agent run executes in its container.
- Good: a misrouted run fails at once, with the setting to change in its failure reason.
- Neutral: a run routed by
runnerTagsthat only the local runner used to serve behaves like any unservable tag set under ADR-0066. Agent load warns that no configured runner serves the tags, and the run waits out its claim TTL. Failing every unservable tag set at once is a broader change to the claim queue, not part of this switch. - Bad: the boundary covers runs only. For the console's LangGraph views the server still runs
homer_langgraph inspect(ADR-0027) andstate(ADR-0044) itself, and both import the agent's graph module on the server host. Moving them to the runner is separate work. Until then, an operator who must keep all agent code off the server host avoids!<langgraph>agents on it.
Pros and Cons of the Options
Let the claim wait until its TTL
- Good: no exception to the ADR-0066 queue invariant.
- Bad: every misrouted run stalls for
runnerClaimTimeoutSec(300 s by default) before failing with a generic claim-timeout reason.
Reject routed-to-local agents at load
- Good: the mistake surfaces before any run.
- Bad: one agent directory can no longer serve both a server with a local runner and one without. It also misses
runnerCmdsteps, whose target is resolved per step.
concurrency: 0
- Bad: overloads a capacity setting with an on/off meaning, and a claim would still wait out its TTL.
More Information
- Issue #33. The slim server image (ADR-0094) is the deployment this switch is for.