Skip to content

ADR 001: Runtime Backend Interface

Status

Accepted

Context

Kohakku needs to spawn agent containers on multiple infrastructure backends (local Docker, Kubernetes, AWS ECS). Each has different APIs and lifecycle management.

Decision

Define a Go Backend interface with 5 methods: Spawn, Status, Cancel, Logs, ListRunning. All backends implement this interface. The Dispatcher selects backend via RUNTIME_BACKEND env var.

Consequences

  • Adding a new backend requires only implementing the interface — no changes to consumer, monitor, or API code
  • Testing uses mock implementations (dockerClient interface for local, fake clientset for K8s, ecsClient interface for ECS)
  • Port exposure, resource limits, and CMD override are part of SpawnRequest — backends handle them differently but the consumer doesn't know which backend it's using
  • WorkerBackend (subprocess) doesn't support all features (ports, logs) — it stubs them gracefully