|
| 1 | +--- |
| 2 | +title: Cloud agent runners |
| 3 | +sidebar: |
| 4 | + label: "Runners" |
| 5 | +description: >- |
| 6 | + Runners define the compute a cloud agent runs on—operating system, CPU |
| 7 | + architecture, instance size, and sandbox image. Learn when to use runners and |
| 8 | + how to manage them with the Oz CLI. |
| 9 | +--- |
| 10 | + |
| 11 | +Runners define the compute a [cloud agent](/platform/) runs on: the operating system, CPU architecture, instance size, and sandbox image used to execute a run. |
| 12 | + |
| 13 | +A runner is a reusable compute configuration. Where an [environment](/platform/environments/) defines _what_ an agent works on (the repos, setup commands, and toolchain), a runner defines _where and on what hardware_ that work executes. Separating the two lets you reuse the same environment across different machine shapes—for example, a small Linux box for routine tasks and a larger instance for heavier builds. |
| 14 | + |
| 15 | +:::note |
| 16 | +Most runs don't need a custom runner. Every environment has a default runner, and Warp picks a sensible default shape when you don't specify one. Create a runner when you need a specific OS, architecture, instance size, or sandbox image. |
| 17 | +::: |
| 18 | + |
| 19 | +## Key features |
| 20 | + |
| 21 | +What runners give you: |
| 22 | + |
| 23 | +* **Reusable compute configs** – Define an OS, architecture, instance size, and sandbox image once, then reuse the runner across cloud agent runs and orchestration without repeating the configuration. |
| 24 | +* **Right-sized hardware** – Choose the number of vCPUs and amount of memory a run needs, so lightweight tasks stay cheap and heavy builds get enough resources. |
| 25 | +* **Flexible OS targets** – Run agents on Linux with a custom Docker image. macOS runners are in limited preview. |
| 26 | +* **Independent of environments** – Override an environment's default runner per run without changing the environment itself. |
| 27 | + |
| 28 | +## How runners fit into the Oz Platform |
| 29 | + |
| 30 | +A runner is the compute layer for a cloud agent run. When a run starts, Warp provisions a sandbox on the runner's shape, then prepares the workspace defined by the environment (cloning repos and executing setup commands) before the agent begins. |
| 31 | + |
| 32 | +* **Environment** – Defines the workspace: Docker image, repositories, and setup commands. See [Environments](/platform/environments/). |
| 33 | +* **Runner** – Defines the compute: OS, architecture, instance shape (vCPUs and memory), and sandbox image. |
| 34 | +* **Host** – Determines where execution happens (Warp-hosted or [self-hosted](/platform/self-hosting/) infrastructure). |
| 35 | + |
| 36 | +Each environment has a default runner. Specifying a runner for a run overrides that default for that run only. |
| 37 | + |
| 38 | +## Managing runners with the CLI |
| 39 | + |
| 40 | +Use the [Oz CLI](/reference/cli/) to create, list, update, and delete runners. Runner commands require an authenticated CLI—see the [CLI quickstart](/reference/cli/quickstart/) to get set up. |
| 41 | + |
| 42 | +### Create a runner |
| 43 | + |
| 44 | +Create a runner with a name and the compute configuration you need. |
| 45 | + |
| 46 | +```sh |
| 47 | +oz runner create \ |
| 48 | + --name <name> \ |
| 49 | + --os linux \ |
| 50 | + --docker-image <image> \ |
| 51 | + --vcpus 4 \ |
| 52 | + --memory-gb 8 \ |
| 53 | + --setup-command "<command>" \ |
| 54 | + --description "Optional description" |
| 55 | +``` |
| 56 | + |
| 57 | +Key flags: |
| 58 | + |
| 59 | +* `--name` (`-n`) — human-readable label for the runner (required). |
| 60 | +* `--description` (`-d`) — optional description (max 240 characters). |
| 61 | +* `--os` — target operating system, `linux` (default) or `macos`. |
| 62 | +* `--arch` — CPU architecture: `auto` (default), `x86-64`, or `aarch64`. `auto` uses the OS default (x86-64 on Linux, aarch64 on macOS). |
| 63 | +* `--docker-image` — Docker image reference for the sandbox. Linux only. |
| 64 | +* `--macos-version` — macOS version for the sandbox: `14`, `15`, `26`, or `27`. macOS only. |
| 65 | +* `--vcpus` — number of vCPUs for the instance shape. Must be set together with `--memory-gb`. |
| 66 | +* `--memory-gb` — memory in GB for the instance shape. Must be set together with `--vcpus`. |
| 67 | +* `--setup-command` (`-c`) — command to run when initializing the sandbox. Repeatable. |
| 68 | +* `--team` / `--personal` — create the runner at the team level or private to your account. |
| 69 | + |
| 70 | +:::caution |
| 71 | +OS-specific options must match `--os`. Use `--docker-image` only with `--os linux`, and `--macos-version` only with `--os macos`. macOS runners are in limited preview. |
| 72 | +::: |
| 73 | + |
| 74 | +### List runners |
| 75 | + |
| 76 | +```sh |
| 77 | +oz runner list |
| 78 | +``` |
| 79 | + |
| 80 | +Add `--sort-by name` or `--sort-by last-updated` to order the results. |
| 81 | + |
| 82 | +### Update a runner |
| 83 | + |
| 84 | +Change a runner's name, description, compute shape, or sandbox image without recreating it. Identify the runner by its UID, or by `--name` when you don't have the UID. |
| 85 | + |
| 86 | +```sh |
| 87 | +# Update by UID |
| 88 | +oz runner update <UID> --vcpus 8 --memory-gb 16 |
| 89 | + |
| 90 | +# Rename a runner (UID identifies it, --name sets the new name) |
| 91 | +oz runner update <UID> --name "new name" |
| 92 | + |
| 93 | +# Update by name when you don't have the UID |
| 94 | +oz runner update --name <name> --docker-image node:22 |
| 95 | +``` |
| 96 | + |
| 97 | +When updating by UID, `--vcpus` and `--memory-gb` can be set independently—the value you don't pass is preserved. |
| 98 | + |
| 99 | +### Delete a runner |
| 100 | + |
| 101 | +```sh |
| 102 | +oz runner delete <UID> |
| 103 | +``` |
| 104 | + |
| 105 | +Add `--force` to skip the confirmation prompt. |
| 106 | + |
| 107 | +## Using a runner for a run |
| 108 | + |
| 109 | +Pass a runner's ID to `oz agent run-cloud` to run a cloud agent on that runner. This overrides the environment's default runner for that run. |
| 110 | + |
| 111 | +```sh |
| 112 | +oz agent run-cloud --runner <ID> --prompt "<task>" |
| 113 | +``` |
| 114 | + |
| 115 | +You can also select a runner when [running orchestrated agents](/platform/orchestration/multi-agent-runs/), so child agents run on the compute shape their work requires. |
| 116 | + |
| 117 | +## Related pages |
| 118 | + |
| 119 | +* [Environments](/platform/environments/) – Define the repos, image, and setup commands an agent works with. |
| 120 | +* [Managing cloud agents](/platform/managing-cloud-agents/) – Start, monitor, and manage cloud agent runs. |
| 121 | +* [Oz CLI reference](/reference/cli/) – Full command-line reference for the Oz platform. |
0 commit comments