diff --git a/src/content/docs/platform/runners.mdx b/src/content/docs/platform/runners.mdx new file mode 100644 index 00000000..84282e1a --- /dev/null +++ b/src/content/docs/platform/runners.mdx @@ -0,0 +1,139 @@ +--- +title: Cloud agent runners +sidebar: + label: "Runners" +description: >- + Runners are reusable compute configurations for cloud agents. Learn how to + create runners and select the operating system, architecture, Docker image, + and instance size your agents run on. +--- + +Runners let you define the compute a [cloud agent](/platform/) runs on — the operating system, CPU architecture, Docker image, instance size, and setup commands — once, then reuse it across runs. + +A runner captures the *machine shape* for a run, separate from the [environment](/platform/environments/), which defines *what* the agent works on (repositories, image, and setup steps). Select a runner per run with `oz agent run-cloud --runner`, or choose one when launching remote child agents during [orchestration](/platform/orchestration/). + +:::note +Runners are optional. Cloud agents run on Warp's default compute unless you specify a runner, and interactive local runs (`oz agent run`) never use one. +::: + +## Key features + +What runners give you: + +* **Reusable compute presets** - Define the OS, architecture, instance size, and setup commands once, then apply the same runner across many runs. +* **Per-run compute overrides** - Point a single run at a specific runner with `--runner` without changing the agent's environment. +* **Linux and macOS targets** - Run agents on Linux (with a custom Docker image) or on macOS (with a specific macOS version). +* **Configurable instance size** - Set the number of vCPUs and amount of memory for workloads that need more compute. + +## How runners work + +A runner is a named compute configuration stored in your account. Each runner defines: + +* **Operating system** - `linux` (default) or `macos`. +* **Architecture** - `auto` (the OS default: x86-64 on Linux, aarch64 on macOS), `x86-64`, or `aarch64`. +* **Docker image** - The sandbox image for Linux runners. Not used for macOS runners. +* **macOS version** - The macOS version for macOS runners (`14`, `15`, `26`, or `27`). Not used for Linux runners. +* **Instance size** - The number of vCPUs and amount of memory (in GB) allocated to the sandbox. +* **Setup commands** - Commands that run when the sandbox is initialized, in the order you provide them. + +When you start a cloud agent with `--runner`, Warp applies that runner's compute configuration to the run, overriding the environment's default runner. This lets one environment run on different machine shapes depending on the run. + +## Managing runners with the CLI + +Use the [Oz CLI](/reference/cli/) to create and manage runners. Every `oz runner` command supports the global `--output json` flag for scripting. + +### Create a runner + +Create a Linux runner with a custom Docker image: + +```bash +oz runner create \ + --name "linux-x86" \ + --description "Standard Linux build box" \ + --os linux \ + --docker-image node:22 \ + --setup-command "npm ci" +``` + +Create a macOS runner on a larger instance: + +```bash +oz runner create \ + --name "macos-large" \ + --os macos \ + --macos-version 15 \ + --vcpus 8 \ + --memory-gb 16 +``` + +Key flags: + +* `--name` (`-n`) - Name of the runner. Required. +* `--description` (`-d`) - Optional description (max 240 characters). +* `--setup-command` (`-c`) - Command to run when initializing the sandbox. Repeatable. +* `--os` - Target operating system: `linux` (default) or `macos`. +* `--arch` - Target CPU architecture: `auto` (default), `x86-64`, or `aarch64`. +* `--docker-image` - Docker image reference for the sandbox. Linux only. +* `--macos-version` - macOS version for the sandbox: `14`, `15`, `26`, or `27`. macOS only. +* `--vcpus` - Number of vCPUs for the instance shape. Requires `--memory-gb`. +* `--memory-gb` - Memory in GB for the instance shape. Requires `--vcpus`. + +:::caution +`--docker-image` is only valid with `--os linux`, and `--macos-version` is only valid with `--os macos`. On create, `--vcpus` and `--memory-gb` must be set together. +::: + +### List runners + +```bash +oz runner list +``` + +Sort the results by name or by when they were last updated: + +```bash +oz runner list --sort-by last-updated +``` + +The `--sort-by` flag accepts `name` or `last-updated`. + +### Update a runner + +Identify the runner to update by its UID or by its `--name`. When you pass a UID, `--name` renames the runner: + +```bash +# Update by UID, and rename it +oz runner update --name "linux-x86-v2" --docker-image node:24 + +# Update by name +oz runner update --name "linux-x86" --setup-command "npm ci --production" +``` + +When updating, `--vcpus` and `--memory-gb` can be set independently — the value you don't pass is preserved. + +### Delete a runner + +```bash +oz runner delete +``` + +Add `--force` to skip the confirmation prompt. + +## Selecting a runner for a run + +Pass a runner ID to `oz agent run-cloud` to run a single cloud agent on that runner's compute: + +```bash +oz agent run-cloud \ + --prompt "Run the full test suite" \ + --runner +``` + +The `--runner` flag overrides the environment's default runner for that run only. + +When you start remote child agents through [multi-agent orchestration](/platform/orchestration/multi-agent-runs/), you can also choose a runner in the run confirmation card so the child agents run on the compute you select. + +## Related pages + +* [Environments](/platform/environments/) - Define the repositories, image, and setup steps an agent works with. +* [Oz CLI reference](/reference/cli/) - Full command reference for the Oz CLI. +* [Multi-agent orchestration](/platform/orchestration/) - Run multiple agents in parallel. diff --git a/src/sidebar.ts b/src/sidebar.ts index 0baeebbe..24f6cb4d 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -382,6 +382,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ collapsed: true, items: [ 'platform/environments', + { slug: 'platform/runners', label: 'Runners' }, { slug: 'platform/managing-cloud-agents', label: 'Managing cloud agents' }, { slug: 'platform/agents', label: 'Agents' }, { slug: 'platform/viewing-cloud-agent-runs', label: 'Viewing cloud agent runs' },