# Warm pools

> Keep pre-booted Remote Dev Environment sessions ready to claim, so a new session or a device preview open is handed out in seconds instead of waiting for a machine to boot.

A warm pool keeps a set number of RDE sessions booted and idle. Creating a session from the pool takes seconds, instead of the minutes a fresh machine needs to boot and run its setup. You describe the session once, as you would when creating one, and set a pool size. Bitrise keeps that many sessions warm and hands one out on request.

Use a warm pool when you need sessions right away, for example:

- An AI agent that needs a machine now.
- A team that starts many similar sessions a day.
- A [device preview link](/bitrise-rde/devices/device-preview-links), where a reviewer clicks and expects the app on screen.

Warm pools aren't available on free-trial workspaces.

:::warning[Alpha feature]

Warm pools are in alpha, as the **Alpha** badge in the RDE UI shows. Pool configuration, the way a claimed session is personalized, and the related CLI commands, MCP tools, and API endpoints can change in backwards-incompatible ways without notice. Expect to adjust your templates, scripts, and automation.

:::

## How a warm pool works

A warm pool has two parts: a stored session configuration and a pool size. The workspace owns the pool.

- The configuration holds the same fields as a session create request: a template, its session input values, the enabled feature flags, and optional overrides for stack, machine type, cluster, and virtual device.
- The pool size is how many sessions the pool keeps booted. Bitrise creates the sessions, runs the template's warmup and startup scripts on them, and keeps them ready. When someone claims one, a replacement boots.
- A pool with size 0 keeps no sessions but still works as a configuration preset. Claiming from it creates a session from the stored configuration.

When you claim a session, you get one of the pool's warm sessions. Bitrise renames it and applies your name, labels, and auto-terminate window. If no session is ready yet, you get one that is still warming up, and it finishes starting as your session. If the pool has no warm session at all, Bitrise creates a session from the pool's configuration instead. Every session records where it came from: a claimed session has the warm state `claimed`, and a session created on demand has the warm state `cold`. The session list in the RDE UI shows these as **Claimed** and **Built cold** badges.

A warm session is a regular session that waits to be claimed, and it costs machine time while it waits. Until someone claims it, it doesn't appear in any session list, and nobody can connect to it, change it, or terminate it. You can read its logs on the pool page to check that the setup scripts work. A warm session has no auto-terminate timer. It waits until someone claims it, or until Bitrise retires it because the pool shrank or its configuration changed.

## Who can use a pool

Every member of the workspace with RDE access sees the pool, claims from it, and manages it. A [Workspace API token](/bitrise-platform/workspaces/workspace-api-token) can reach it from CI.

The pool's inputs are stored as plain values, encrypted at rest when marked secret. [Saved inputs](/bitrise-rde/configuration/saved-inputs) are personal, so a pool can't reference them: there is no single person whose saved inputs it could use.

## Who owns a claimed session

A session claimed from a pool is yours, like a session you create yourself: only you see and manage it. A warm session is booted before anyone claims it, so it has nothing personal on it: no saved inputs, no GitHub credential. Add those after claiming, for example over SSH.

To share a claimed session instead, choose **Workspace** as the owner when you claim it. Every member then sees and manages it under **Workspace sessions**, with you recorded as its creator. Sessions claimed with a Workspace API token, and the device sessions a [preview link](/bitrise-rde/devices/device-preview-links) opens, always belong to the workspace.

## Creating a pool

**RDE UI**

1. In the Remote Dev Environments section, open **Warm pools** and click **New warm pool**. From a template's page, **Create warm pool** opens the same form with the template already selected.
1. Choose the template. The form shows only what the template needs: session inputs, feature flags, a device section if the template boots a device, and the same **Override machine configuration** switch as the session form.
1. Enter a **Pool name**.
1. Set the **Pool size**.
1. Click **Create warm pool**.

The pool page shows how many sessions are ready and how many are still warming up. It also lists the warm sessions by name, and lifetime counts of claimed and cold sessions.

**CLI**

```bash
bitrise-cli rde warm-pool create ios-reviewers --template "iOS Xcode 26" --size 2
```

`--input` and `--secret-input` set the template's session inputs, `--feature-flag` enables a template feature flag, and the `--stack`, `--machine-type`, and `--device-*` flags override what the template declares. Every command that takes a pool ID also accepts the pool's name.

**AI agent (MCP)**

Ask for it in plain language, for example: *"Keep two sessions of the iOS Xcode 26 template warm for the team."* The agent calls `bitrise_devenv_create_warm_pool` with the template, the inputs, and the pool size.

**API**

```bash
curl -X POST "https://api.bitrise.io/rde/v1/workspaces/WORKSPACE_ID/warm-pools" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ios-reviewers",
    "template_id": "TEMPLATE_ID",
    "pool_size": 2
  }'
```

The configuration fields are the same as the create session request's. See [Create warm pool](/bitrise-rde-api/api-reference/codespaces-service-create-warm-pool) in the API reference.

Bitrise validates the configuration the same way as a session create request. An unknown input, a missing required input, or a device the machine type can't run is rejected when you save. Warm sessions are running sessions, so they count toward the workspace's session limit like any other session. If the workspace is at its limit and the pool can't reach its size, the pool page shows the error and the pool keeps trying.

## Claiming a session

**RDE UI**

On the **New session** form, once you choose a template, **Start from warm pool** lists its pools and preselects the pool when there is only one. With a pool selected, the pool fixes the configuration sections. You only name the session, choose its owner (**Me** by default), and set its auto-terminate window. A pool's page also has a **Claim a session** button that opens the form with the pool preselected.

**CLI**

```bash
bitrise-cli rde session create my-fix --warm-pool ios-reviewers
```

**AI agent (MCP)**

The agent passes `warm_pool_id` to `bitrise_devenv_create`. To see which pools it can claim from, it calls `bitrise_devenv_list_warm_pools`.

**API**

Set `warm_pool_id` on the create session request and leave the configuration fields empty.

The pool fixes the configuration. A claim that also passes a template, inputs, feature flags, a stack, a machine type, a cluster, or a device is rejected, not ignored. Per session, you still choose the name, description, labels, and auto-terminate window. For a pool that boots a device, you can also choose an app build to install.

## Keeping the pool healthy

Bitrise checks every pool regularly and keeps it at its size. A few things to know:

- **Editing the configuration replaces the warm sessions.** When you change the inputs, the feature flags, or the machine or device settings, Bitrise retires the sessions warmed with the old configuration and boots new ones. The UI warns you before you save such a change. Renaming the pool or changing its size doesn't affect the warm sessions.
- **A template edit does the same.** The pool follows its template, so editing the template's scripts or variables replaces the pool's warm sessions too.
- **A broken configuration pauses the pool.** A template edit can add a required input the pool doesn't set, or remove a feature flag the pool enables. The pool then shows a configuration error and stops creating sessions until you fix it. The pool's existing warm sessions stay claimable.
- **Repeated failures pause the pool.** The pool waits a while before it retries, so a broken setup script doesn't keep starting new machines. The pool page shows the last error.

## Scaling a pool on a schedule

Warm sessions cost machine time while idle, so keep the pool size at what demand needs. Changing the size is a single call, which makes a schedule easy: warm the pool up for business hours and drain it in the evening. A cron job with a Workspace API token does it:

```bash
0 8  * * 1-5  BITRISE_TOKEN=bitwat_… bitrise-cli rde warm-pool set-size ios-reviewers 3 --workspace WORKSPACE_ID -q
0 19 * * 1-5  BITRISE_TOKEN=bitwat_… bitrise-cli rde warm-pool set-size ios-reviewers 0 --workspace WORKSPACE_ID -q
```

Size 0 retires every warm session but keeps the pool, its configuration, and any preview links minted with it. Deleting the pool retires its warm sessions and also invalidates its preview links. Sessions already claimed from the pool are regular sessions, and neither change affects them.

## Device pools and preview links

If the pool's template boots a virtual device, the pool keeps devices booted too. This is why a [device preview link](/bitrise-rde/devices/device-preview-links) opens in the time it takes to download the app. Mint the link against the pool, and every open claims one of its warm devices. See [Serving links from a warm pool](/bitrise-rde/devices/device-preview-links#serving-links-from-a-warm-pool).

A claim from a device pool can install an app build right away. Pass the build's URL as the session's artifact. Because the device is already running, the app installs the moment the session is handed out.

## Managing pools

The **Warm pools** page lists the workspace's pools. From a pool's page you can change its size, edit its configuration, claim a session, and delete it. The CLI mirrors this with `bitrise-cli rde warm-pool list`, `view`, `update`, `set-size`, and `delete`, and the [API](/bitrise-rde/configuration/rde-api#warm-pools) with the warm pool endpoints.

Workspace owners and members who manage billing also see every pool and its size. The pools appear on the **Usage** page and in `bitrise-cli rde warm-pool list --all`, alongside the rest of the workspace's RDE spend.