> For the complete documentation index, see [llms.txt](https://docs.warp.dev/llms.txt). > Markdown versions of each page are available by appending .md to any URL. # Runners for Warp Factories Runners define the OS, architecture, instance size, and sandbox image for cloud agent runs, including work from Warp Factories. Runners define the compute a [cloud agent](https://docs.warp.dev/platform/) runs on: the operating system, CPU architecture, instance size, and sandbox image used to execute a run. Factory agents select runners through the [factory definition](https://docs.warp.dev/factories/factory-as-code/) or the [factory dashboard](https://docs.warp.dev/factories/factory-dashboard/). A runner is a reusable compute configuration. Where an [environment](https://docs.warp.dev/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. This lets any cloud-agent workflow use different machine shapes for different workloads. ## Configure runners for a factory Set a factory’s default runner in `agentDefaults.runner`, then override it per agent or automation when the work needs different compute. For file-managed factories, edit `runners/*.yaml` in the factory definition. For Warp-managed factories, edit runner files in the factory dashboard. 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. - **Operating systems** – Run agents on Linux, macOS, or Windows. - **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, clones the repositories, runs the runner’s `setupCommands` in order, and then runs the environment’s setup commands before the agent begins. A setup command that exits with a nonzero status or runs longer than 30 minutes fails the run during environment setup. - **Environment** – Defines the workspace: Docker image, repositories, and setup commands. See [Environments](https://docs.warp.dev/platform/environments/). - **Runner** – Defines the OS, architecture, instance shape (vCPUs and memory), and sandbox image. - **Host** – Determines where execution happens (Warp-hosted or [self-hosted](https://docs.warp.dev/factories/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-691) - [macOS](#tab-panel-692) - [Windows](#tab-panel-693) 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, and private images with a team credential. By default, runners use [`warpdotdev/dev-base:latest`](https://hub.docker.com/r/warpdotdev/dev-base). To pull a private image, choose a team-owned credential for the image’s registry in the “Private image credential” dropdown when you create or edit the runner. See [AWS ECR credentials](https://docs.warp.dev/platform/secrets/#aws-ecr-credentials) for Amazon ECR. 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. Warp-hosted Linux runners can also run Docker containers and KVM-based virtual machines, such as the Android emulator. 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, along with simulators for iOS, watchOS, and tvOS. 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 Windows runners are available for Warp-hosted execution and run each agent in a fresh Windows VM. They support x86-64 architecture only and don’t use Docker images or expose a custom Windows image setting. Use PowerShell-compatible setup commands to install dependencies and prepare the workspace: ```yaml title="runners/windows-ci.yaml" description: Windows runner for builds and tests setupCommands: - pwsh -File setup.ps1 instanceShape: vcpus: 4 memoryGb: 8 platform: os: windows arch: x86_64 ``` Both `vcpus` and `memoryGb` must be positive powers of two within your plan’s resource limit. Omit `instanceShape` to use the workspace default shape. A factory’s default runner (`agentDefaults.runner`) must be Linux because it supplies the factory-managed environment. Select a Windows runner on an individual agent or automation with `runner`. Managed self-hosted workers currently run on Linux. Use [Warp-hosted execution](https://docs.warp.dev/factories/warp-hosting/) for Windows runners. ## Managing runners with the legacy CLI The legacy [Oz CLI](https://docs.warp.dev/agents/cli/oz-cli/) also supports creating, listing, updating, and deleting reusable runners for standalone cloud-agent workflows. ### Create a runner Create a runner with a name and the compute configuration you need. ```sh 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), `macos`, or `windows`. - `--arch` — CPU architecture: `auto` (default), `x86-64`, or `aarch64`. `auto` uses the OS default (x86-64 on Linux and Windows, 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`. Windows doesn’t have an OS-specific option. ### List runners ```sh 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. ```sh # Update by UID oz 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 UID oz 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 ```sh 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. ```sh oz agent run-cloud --runner --prompt "" ``` You can also select a runner when [running orchestrated agents](https://docs.warp.dev/platform/orchestration/multi-agent-runs/), so child agents run on the compute shape their work requires. ## Related pages - [Environments](https://docs.warp.dev/platform/environments/) – Define the repos, image, and setup commands an agent works with. - [Warp-hosted execution](https://docs.warp.dev/factories/warp-hosting/) – Run factory work on Warp-managed infrastructure. - [Managed self-hosting](https://docs.warp.dev/factories/self-hosting/) – Run factory work on Linux infrastructure you manage. - [Managing cloud agents](https://docs.warp.dev/platform/managing-cloud-agents/) – Start, monitor, and manage cloud agent runs. - [Oz CLI reference](https://docs.warp.dev/agents/cli/oz-cli/) – Full command-line reference for runners and every other cloud agent command.