0001 — Three runtimes behind one interface

• Date: 2026-04-30
• Status: Accepted

Context

An agent platform's biggest distinguishing axis is where execution happens. Three constituencies want three things: hobbyists want their laptop, most teams want a hosted VM, enterprises want to run it themselves. Picking one is leaving the other two on the table.

Decision

Clip exposes a single RuntimeProvider interface with three implementations: cloud (Cursor SDK against Cursor-hosted VMs), local (piggyback on the user's already-running Cursor via a bridge), pool (any URL implementing the contract).

We do not ship a Docker image for the pool. The HTTP/WS contract is the artifact; users stand up whatever fits.

We do not build our own desktop tray app for local. We talk to the existing Cursor instance.

Alternatives considered

• Cloud only. Faster to ship, but cedes local-first and enterprise to competitors.
• Build our own tray. More polish, but doubles the surface area we maintain and asks users to install another binary.
• Ship a Dockerfile. Tempting, but commits us to operating an infrastructure product on top of an orchestration product.

Consequences

• The UI must show runtime health prominently and explain why a runtime is unavailable. Silent failures will burn us.
• RuntimeProvider must be small enough that a Claude Agent SDK or other adapter is one file later.
• Local mode is unavailable when the user isn't running Cursor; the picker must say so without shaming the user into running it.