Factories > Infrastructure & security

Runners for Warp Factories

Runners define the OS, architecture, instance size, and sandbox image for Warp Factories work.

Runners define the compute a factory agent runs on: the operating system, CPU architecture, instance size, and sandbox image used to execute a run. Select runners in the factory definition or the factory dashboard.

A runner is a reusable compute configuration. Where an environment 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 a factory use a small Linux runner for triage and a larger runner for builds.

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.
Runner – Defines the compute: OS, architecture, instance shape (vCPUs and memory), and sandbox image.
Host – Determines where execution happens (Warp-hosted or self-hosted infrastructure).

Each environment has a default runner. Specifying a runner for a run overrides that default for that run only.

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. 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.

Managing runners with the legacy CLI

For a file-managed factory, edit runners/*.yaml in the factory definition. For a Warp-managed factory, edit runner files in the factory dashboard. The legacy Oz CLI also supports creating, listing, updating, and deleting reusable runners.

Create a runner

Create a runner with a name and the compute configuration you need.

oz runner create \
  --name <name> \
  --os linux \
  --docker-image <image> \
  --vcpus 4 \
  --memory-gb 8 \
  --setup-command "<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.

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 UID
oz runner update <UID> --vcpus 8 --memory-gb 16

# Rename a runner (UID identifies it, --name sets the new name)
oz runner update <UID> --name "new name"

# Update by name when you don't have the UID
oz runner update --name <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 <UID>

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 <ID> --prompt "<task>"

You can also select a runner when running orchestrated agents, so child agents run on the compute shape their work requires.

Environments – Define the repos, image, and setup commands an agent works with.
Managing cloud agents – Start, monitor, and manage cloud agent runs.
Oz CLI reference – Full command-line reference for runners and every other cloud agent command.