ADR-0003: Runners as pluggable execution backends
Context and Problem Statement
Every agent command historically ran on Homer's host via ShellExecutor (a ProcessBuilder wrapper). Operators want to run commands inside short-lived Kubernetes pods — one pod per agent run, with operator- chosen image, resources, and volume mounts — while keeping the existing local-host path working unchanged for agents that don't opt in.
We needed a place to put "where a command runs" that was not bolted onto one executor and not a per-command type: k8s hack. The choice shapes how workspaces, env vars, artifacts, and lifecycle cross the host/pod boundary for every command type Homer already supports (Cmd, Script, Claude, RunAgent).
Decision Drivers
- One pod per agent run, not per command — agents chain commands that share filesystem state; per-command pods would force copy-in / copy-out or a sidecar.
- Existing executors (
Cmd,Script,Claude,RunAgent) must work unchanged in the new backend without per-type special casing. - Artifact tailing (live stdout/stderr streaming) must keep working with no new plumbing.
- Homer remains the source of truth for workspace state; pods are ephemeral consumers of a shared view.
- Operators already run Homer in Kubernetes and want command isolation without giving up the local-host path for dev / tests.
Considered Options
- One pod per command. Spawn a pod for every
Cmd/Script/Claudeinside an agent. Reuse nothing between commands. - Kubernetes as a new command type. Add
type: k8salongsidecmd/script, leaving other commands on the host. - Runner abstraction (one pod per agent run). New pluggable backend interface with a
localbuilt-in and akubernetesimplementation; agents pick a runner by alias.
Decision Outcome
Chosen option: "Runner abstraction (one pod per agent run)", because it is the only option that satisfies all four drivers simultaneously. Per-command pods make filesystem sharing between git clone and ./build.sh prohibitive; a type: k8s command forces per-type rewrites of every executor. A Runner with one session per agent run lets every existing executor call session.shell without knowing whether it's a host or an in-pod shell.
The session's shell is threaded through ExecutionContext.shell rather than mutated onto Workspace — Workspace stays shared host state, the session-scoped shell travels with the call.
Workspaces are shared via a single RWX PVC mounted at the same absolute path inside the pod as on Homer, using subPath to scope to the per-run workspace. No copy in, no copy out; HMR_WORK_DIR and HMR_ARTIFACTS_DIR pass through unchanged. (Superseded in part by ADR-0043, 2026-10-09 note: kubernetes workspaces are now synced by tar-over-exec; the shared RWX PVC is gone.)
HMR_API_URL is contributed by the runner session and merged into the workspace env before commands run, so RunAgent resolves Homer's in-cluster Service inside the pod and the host fallback (http://localhost:<port>) applies only to the local runner. (Amended 2026-10-09: RunAgent dispatches in-process since ADR-0030 and no longer uses HMR_API_URL; the runner session still contributes it for in-run callbacks.)
Consequences
- Good: every executor is backend-agnostic —
session.shellis the only seam. - Good: live tailing keeps working because pod stdout/stderr are streamed to files on the shared PVC, which
ArtifactServicealready reads. (Superseded in part by ADR-0043, 2026-10-09 note: there is no shared PVC any more.) - Good: the local runner preserves byte-identical behavior for agents that don't set
runner:. - Good: pod lifecycle surfaces on
/api/v1/process/{id}and in the console without per-command instrumentation. - Bad: v1 is single-replica —
lockKey-based serialization is in-memory and the orphan-pod sweep assumes one Homer. Multi-replica HA needs distributed locks and per-replica ownership labels. - Bad: v1
homerApiUrlis plain HTTP; TLS / mTLS between pod and Homer is future work. - Bad: the image must ship whatever binaries a
Claude/RunAgentcommand relies on (claudeCLI,curl), documented inapp/SERVER.md.
Pros and Cons of the Options
Option A — One pod per command
- Good: strongest isolation between commands.
- Bad: breaks filesystem sharing between chained commands unless every pod mounts the same PVC and runs a setup container — more moving parts than one pod per run, for no real gain over per-run pods.
- Bad: pod-create latency is paid per command, not per agent run.
Option B — Kubernetes as a new command type
- Good: smallest surface area — one new
Commandsubclass. - Bad: every other command type (
Cmd,Script,Claude,RunAgent) stays stuck on the host; operators can't run agents in Kubernetes, only individual commands. - Bad: two execution models to maintain inside one agent.
Option C — Runner abstraction
- Good: every existing executor becomes backend-agnostic.
- Good: new backends (Fargate, Nomad, Firecracker, …) slot in behind the same interface.
- Neutral: adds a module and a config key (
AppConfig.runners) plus an agent field (runner:). - Bad: more up-front structure than Option B.
More Information
- Related: ADR-0002 — runner startup failures surface as
PodStartupExceptionmapped at the HTTP boundary the same way as otherHomerExceptionsubclasses.