# On-demand runs



A **run** is a one-off, Sandbox-backed job. The service provisions an ephemeral
Infra Sandbox, clones your repos into it, runs the agent, and tears the Sandbox
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 [#launch-a-run]

<Tabs items="['Console', 'API']">
  <Tab value="Console">
    Open an agent and choose **Run agent**. Two modes:

    * **Clone repos & run** — provisions a fresh Sandbox, clones the repos you list
      (using your linked GitHub identity), runs, and tears down on finish. Pick a
      Sandbox 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 Sandbox, bind the run to an
      [environment](/docs/agents/environments) you've already provisioned.
  </Tab>

  <Tab value="API">
    `POST /v1/runs`. Provide **exactly one** selector — `agent`, `mode`, or
    `builtin`:

    ```bash
    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 &#x2A;*`202 Accepted`** with the created session:

    ```json
    { "session_id": "ses_8b1d4e", "sandbox_id": "sbx_9a8b7c" }
    ```

    Stream `GET /v1/sessions/{session_id}/events/stream` to watch the run's progress.
  </Tab>
</Tabs>

## Selectors [#selectors]

| Selector  | Who can use it           | Driven by   | Notes                                                                                                                                                                |
| --------- | ------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent`   | Owner of the agent       | `kickoff`   | Runs a Sandbox-backed agent you own. `repos` optional — omit for a bare Sandbox.                                                                                     |
| `builtin` | Any authenticated caller | `request`   | Runs a public built-in agent by slug (e.g. `megaplan`, 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 `megareview`) against a PR.                                                                                                    |

Common fields:

| Field         | Notes                                                                                                                                                                                                                                                                  |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `repos`       | Repos to clone into the Sandbox. Each clones as your identity, so private repos pull with your GitHub credentials.                                                                                                                                                     |
| `template_id` | Override the Sandbox template — `development`, `workspace`, or `browser`. 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](/docs/agents/vaults-and-mcp) to attach to the run. MCP credentials resolve per turn; any `environment_variable` credentials are decrypted and injected as Sandbox environment variables at provision. You must own each vault (a non-owned id returns `404`). |

## Lifecycle [#lifecycle]

A run provisions the Sandbox, creates a session, fires the kickoff, watches the
session to idle, and then tears the Sandbox down — all server-side, detached
from your HTTP request. You only need the `session_id` to follow along via the [event
stream](/docs/agents/sessions-and-events).

For long-lived VMs that persist across many sessions, use
[environments](/docs/agents/environments) instead.