Runtimes

The core idea

Every agent run picks one of three places to execute: the cloud (Cursor-hosted VMs), your local machine (via your running Cursor), or a self-hosted pool (any URL you run that speaks our protocol). They're three implementations of one interface, RuntimeProvider. The UI shows live health for each so you don't pick something that's down.

The three modes

Cloud. @cursor/sdk Agent.create() returns a bc-<uuid> agent in a Cursor-hosted VM. The VM clones your repo, agents stream SDKMessage events, costs are billed against your Cursor account. Best default. Use when: your repo is on GitHub, you don't care about latency to disk, you want runs to keep going if you close your laptop.

Local. Piggybacks on the user's already-running Cursor instance through a small bridge that exposes the same provider HTTP shape on localhost. No tray app to install — if Cursor isn't running, local mode is unavailable and the picker says so. Best when: you're editing a private repo on your laptop, you don't want code leaving the machine, you want files-from-disk semantics.

Pool. A URL that the workspace has registered. Anything that implements the provider HTTP contract counts: a Fly machine you spun up, an EC2 box, a k8s deployment behind an ingress. We don't ship a Docker image — the contract is the artifact. Best when: a customer needs the runtime in their VPC, or you're running many concurrent agents and want your own pool of capacity.

Why this works

The expensive part of any agent product is the runtime — VMs, repo clones, MCP server processes. Pretending we're a runtime is a trap; pretending the runtime can never change is also a trap. So Clip is neither. It's an orchestrator that treats the runtime as plug-replaceable. That makes Cursor cloud the path of least resistance today, lets sophisticated users keep code local, and gives enterprises a story for "run it in our VPC."

How to use it

You set a default in the agent (agents.runtime_pref). Anyone with summon_agent permission can override the default at summon time using the RuntimePicker. The chosen runtime is recorded on the runs row, so when you open a run later you see exactly where it ran and can replay its event stream.

The picker shows three tiles:

• Cloud — green if your CURSOR_API_KEY is valid and quota remains. Subtitle shows estimated cost per minute.
• Local — green if the bridge on localhost responds. Subtitle shows machine name + free RAM/CPU. Red with reason if Cursor isn't running.
• Pool — green if the configured URL responds. Subtitle shows queue depth and time-to-pickup.

Tips and tricks

• If you're prototyping a skill, pick local: the iteration loop is faster than spinning up a cloud VM.
• For overnight heartbeats, prefer cloud — runs survive your machine sleeping.
• For demoing to a customer, pre-warm a pool node and pin agents to it; they'll feel snappy.
• When debugging "why is my agent slow?", check the run page first — the SDKMessage stream tells you whether time is in tool calls, model thinking, or VM startup.

What's optional

Pool. Most users will never set one up. Cloud + local covers the long tail. Pool exists so the product isn't a dead end for teams that need it.