On-demand runs
Launch a one-off, VM-backed agent run — the service provisions a VM, clones your repos, runs the agent, and tears it down.
On-demand runs
A run is a one-off, VM-backed job. The service provisions an ephemeral Firecracker VM, clones your repos into it, runs the agent, and tears the VM down automatically when the agent finishes. There's no environment to manage — ideal for "review this PR" or "run my docs agent over this repo" style tasks.
Launch a run
Open an agent and choose Run agent. Two modes:
- Clone repos & run — provisions a fresh VM, clones the repos you list (using your linked GitHub identity), runs, and tears down on finish. Pick a VM template (or Agent default) and optionally describe the task; leave the task blank to use the agent's own instructions.
- Existing environment — instead of an ephemeral VM, bind the run to an environment you've already provisioned.
POST /v1/runs. Provide exactly one selector — agent, mode, or
builtin:
curl https://agents.clusterbase.dev/v1/runs \
-H "Authorization: Bearer $CLUSTER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"agent": "agt_3f9c2a",
"repos": [{ "url": "https://github.com/acme/web" }],
"kickoff": "Review the open changes on the feature branch."
}'The call returns 202 Accepted with the created session:
{ "session_id": "ses_8b1d4e", "environment_id": "env_9a8b7c" }Stream GET /v1/sessions/{session_id}/events/stream to watch the run's progress.
Selectors
| Selector | Who can use it | Driven by | Notes |
|---|---|---|---|
agent | Owner of the agent | kickoff | Runs a VM-backed agent you own. repos optional — omit for a bare VM. |
builtin | Any authenticated caller | request | Runs a public built-in agent by slug (e.g. ultraplan, or build to make a change and open a PR under your own GitHub identity). Passing kickoff here is a 400. |
mode | Operators only | pr_number | Runs a built-in reviewer (review or ultrareview) against a PR. |
Common fields:
| Field | Notes |
|---|---|
repos | Repos to clone into the VM. Each clones as your identity, so private repos pull with your GitHub credentials. |
template_id | Override the VM template. Omit to inherit the agent's configured default. |
kickoff | First message for an agent run. Omit for a sensible default. |
request | The task for a builtin run (required; replaces kickoff). |
pr_number | The PR a mode reviewer posts to (required for mode unless kickoff is set). |
vault_ids | Vaults to attach to the run. MCP credentials resolve per turn; any environment_variable credentials are decrypted and injected as VM environment variables at provision. You must own each vault (a non-owned id returns 404). |
Lifecycle
A run provisions the VM, creates a session, fires the kickoff, watches the
session to idle, and then tears the VM down — all server-side, detached from your
HTTP request. You only need the session_id to follow along via the event
stream.
For long-lived VMs that persist across many sessions, use environments instead.