> For the complete documentation index, see [llms.txt](/llms.txt). > Markdown versions of each page are available by appending .md to any URL. # Cloud agent runners Runners define the OS, architecture, instance size, and sandbox image cloud agents run on, managed with the Oz CLI. 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. 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. Note 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. ## Key features What runners give you: - **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. - **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. - **Flexible OS targets** – Run agents on Linux or macOS. - **Independent of environments** – Override an environment’s default runner per run without changing the environment itself. ## How runners fit into cloud agent runs 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. - **Environment** – Defines the workspace: Docker image, repositories, and setup commands. See [Environments](/platform/environments/). - **Runner** – Defines the compute: OS, architecture, instance shape (vCPUs and memory), and sandbox image. - **Host** – Determines where execution happens (Warp-hosted or [self-hosted](/platform/self-hosting/) infrastructure). Each environment has a default runner. Specifying a runner for a run overrides that default for that run only. ## Operating systems - [Linux](#tab-panel-706) - [macOS](#tab-panel-707) Linux runners execute the agent in a fresh Docker container. Warp uses the Docker image you select to provide the agent’s base filesystem and toolchains. Warp-hosted Linux runners support any public x86-64 or aarch64 image. By default, runners use [`warpdotdev/dev-base:latest`](https://hub.docker.com/r/warpdotdev/dev-base). Linux supports any combination of CPU and memory as long as both are a power of two and within your plan’s maximum resource limit. macOS runners execute the agent in a fresh VM on Apple Silicon. You can choose from macOS 14, 15, 26, or 27. If not specified, Warp uses the current macOS release. The VM has Xcode and standard system tools installed. Use setup commands to install additional dependencies. Downloads from Homebrew and popular language package managers are cached automatically. The following resource configurations are supported: - 4 vCPUs, 7 GB memory - 6 vCPUs, 14 GB memory - 8 vCPUs, 14 GB memory - 12 vCPUs, 28 GB memory - 12 vCPUs, 56 GB memory ## Managing runners with the CLI 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. ### Create a runner Create a runner with a name and the compute configuration you need. ``` oz runner create \ --name \ --os linux \ --docker-image \ --vcpus 4 \ --memory-gb 8 \ --setup-command "" \ --description "Optional description" ``` Key flags: - `--name` (`-n`) — human-readable label for the runner (required). - `--description` (`-d`) — optional description (max 240 characters). - `--os` — target operating system, `linux` (default) or `macos`. - `--arch` — CPU architecture: `auto` (default), `x86-64`, or `aarch64`. `auto` uses the OS default (x86-64 on Linux, aarch64 on macOS). - `--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. Must be set together with `--memory-gb`. - `--memory-gb` — memory in GB for the instance shape. Must be set together with `--vcpus`. - `--setup-command` (`-c`) — command to run when initializing the sandbox. Repeatable. - `--team` / `--personal` — create the runner at the team level or private to your account. Caution OS-specific options must match `--os`. Use `--docker-image` only with `--os linux`, and `--macos-version` only with `--os macos`. ### List runners ``` oz runner list ``` Add `--sort-by name` or `--sort-by last-updated` to order the results. ### Update a runner 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. ``` # Update by UIDoz runner update --vcpus 8 --memory-gb 16 # Rename a runner (UID identifies it, --name sets the new name)oz runner update --name "new name" # Update by name when you don't have the UIDoz runner update --name --docker-image node:22 ``` When updating by UID, `--vcpus` and `--memory-gb` can be set independently—the value you don’t pass is preserved. ### Delete a runner ``` oz runner delete ``` Add `--force` to skip the confirmation prompt. ## Using a runner for a run 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. ``` oz agent run-cloud --runner --prompt "" ``` 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. ## Related pages - [Environments](/platform/environments/) – Define the repos, image, and setup commands an agent works with. - [Managing cloud agents](/platform/managing-cloud-agents/) – Start, monitor, and manage cloud agent runs. - [Oz CLI reference](/reference/cli/) – Full command-line reference for runners and every other cloud agent command.