Skip to content

Warm pools belong to the workspace #359

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ilanazholobovsky merged 4 commits into from
Oct 9, 2026
Merged

Warm pools belong to the workspace #359

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ab93cde
Warm pools belong to the workspace
gaborszakacs Oct 8, 2026
04736d1
Mark warm pools as an alpha feature
gaborszakacs Oct 8, 2026
a19a495
Remove the last personal-pool references
ilanazholobovsky Oct 9, 2026
1043073
Tighten the warm pools prose
ilanazholobovsky Oct 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 46 additions & 36 deletions docs/bitrise-rde/configuration/warm-pools.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,61 +9,72 @@ import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import GlossTerm from '@site/src/components/GlossTerm';

A <GlossTerm baseform="warm pool">warm pool</GlossTerm> keeps a number of <GlossTerm baseform="rde session">RDE sessions</GlossTerm> booted and idle, so that creating a session takes seconds instead of the minutes a fresh machine needs to boot and run its setup. You describe the session once, the way you would when creating one, and set a pool size. Bitrise keeps that many sessions warm, and hands one out when someone asks for it.
A <GlossTerm baseform="warm pool">warm pool</GlossTerm> keeps a set number of <GlossTerm baseform="rde session">RDE sessions</GlossTerm> 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.

Warm pools are useful when a pool is needed immediately: an AI agent that needs a machine now, a team that starts many similar sessions a day, and [device preview links](/bitrise-rde/devices/device-preview-links) where a reviewer clicks and expects the app on screen.
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 is a stored session configuration plus an owner and a pool size:
A warm pool has two parts: a stored session configuration and a pool size. The workspace owns the pool.

- The configuration is what a session create request carries: a <GlossTerm baseform="rde template">template</GlossTerm>, its session input values, the enabled feature flags, and optional stack, machine type, cluster, and virtual device overrides.
- The pool size is how many sessions the pool keeps booted. Bitrise creates them, runs the template's warmup and startup scripts on them, and keeps them ready. When one is claimed, a replacement boots to take its place.
- A pool with a size of 0 keeps no sessions but stays around as a configuration preset: claiming from it creates a session from the stored configuration.
- The configuration holds the same fields as a session create request: a <GlossTerm baseform="rde template">template</GlossTerm>, 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.

Claiming a session from a pool gives you one of its warm sessions, renamed and stamped with your name, labels, and auto-terminate window. If none is ready yet, you get one that's still warming up, and it finishes starting under your name. If no warm session is available at that moment, a session is created from the pool's configuration instead. Every session records where it came from: a claimed session's warm state is `claimed`, a session created on demand from the pool is `cold`. In the RDE UI, the session list shows these as **Claimed** and **Built cold** badges.
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.

Warm sessions are ordinary sessions underneath, and they cost machine time while they wait. They don't appear in anyone's session list, and until someone claims one it can't be connected to, changed, or terminated; you can read its logs from the pool page to check that the setup scripts do what you expect. A warm session has no auto-terminate timer of its own: it either gets claimed or is retired when the pool shrinks or its configuration changes.
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.

## Personal and workspace pools
## Who can use a pool

A pool belongs either to you or to the <GlossTerm baseform="workspace">workspace</GlossTerm>:
Every member of the <GlossTerm baseform="workspace">workspace</GlossTerm> 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.

- A **personal pool** is private to you. Only you see it, claim from it, and manage it. Its inputs can reference your [saved inputs](/bitrise-rde/configuration/saved-inputs), so a rotated credential flows into the next warm sessions without editing the pool.
- A **workspace pool** is shared with every member of the workspace. Anyone with RDE access can claim from it and manage it, and a [Workspace API token](/bitrise-platform/workspaces/workspace-api-token) can reach it from CI. Its inputs are stored as plain values, encrypted at rest when marked secret, because there is no single person whose saved inputs it could use. Only workspace pools can serve device preview links.
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.

A session claimed from a personal pool is owned by you, like a session you create yourself.
## Who owns a claimed session

A session claimed from a workspace pool is owned by the workspace: every member sees and manages it under **Workspace sessions**, and you're recorded as its creator.
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.

Warm pools aren't available on free-trial workspaces.
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

<Tabs>
<TabItem value="ui" label="RDE UI" default>

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 then shows only what the template calls for: session inputs, feature flags, a device section when the template boots one, and the same **Override machine configuration** switch the session form has.
1. Enter a **Pool name** and choose the owner: **Me** for a personal pool or **Workspace** for a shared one.
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, the warm sessions by name, and lifetime counts of claimed and cold sessions.
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.

</TabItem>
<TabItem value="cli" label="CLI">

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

`--input`, `--secret-input`, and `--saved-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.
`--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.

</TabItem>
<TabItem value="mcp" label="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, the owner, and the pool size.
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.

</TabItem>
<TabItem value="api" label="API">
Expand All @@ -75,7 +86,6 @@ curl -X POST "https://api.bitrise.io/rde/v1/workspaces/WORKSPACE_ID/warm-pools"
-d '{
"name": "ios-reviewers",
"template_id": "TEMPLATE_ID",
"owner_type": "workspace",
"pool_size": 2
}'
```
Expand All @@ -85,14 +95,14 @@ The configuration fields are the same as the create session request's. See [Crea
</TabItem>
</Tabs>

The configuration is validated the same way a session create is: 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 and count toward your workspace's session limit, the same as sessions people create. If a pool can't reach its size because the workspace is at its limit, its page shows the error and the pool keeps trying.
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

<Tabs>
<TabItem value="ui" label="RDE UI" default>

On the **New session** form, once a template and an owner are chosen, **Start from warm pool** lists the matching pools; when exactly one matches, it's preselected. With a pool selected the configuration sections are fixed by the pool, and you only name the session 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.
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.

</TabItem>
<TabItem value="cli" label="CLI">
Expand All @@ -104,7 +114,7 @@ bitrise-cli rde session create my-fix --warm-pool ios-reviewers
</TabItem>
<TabItem value="mcp" label="AI agent (MCP)">

The agent passes `warm_pool_id` to `bitrise_devenv_create`; `bitrise_devenv_list_warm_pools` shows it which pools it can claim from.
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`.

</TabItem>
<TabItem value="api" label="API">
Expand All @@ -114,36 +124,36 @@ Set `warm_pool_id` on the create session request and leave the configuration fie
</TabItem>
</Tabs>

The pool fixes the configuration, so a claim can't also pass a template, inputs, feature flags, a stack, machine type, cluster, or device: those are rejected, not ignored. What you still choose per session: the name, description, labels, the auto-terminate window, and for a pool that boots a device, an app build to install.
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.** Changing the inputs, the flags, or the machine or device settings retires the sessions that were warmed with the old configuration and boots new ones. The UI warns you before saving such a change. Renaming the pool or changing its size doesn't touch 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. Rotating a saved input a personal pool references has the same effect.
- **A configuration that stops working pauses the pool.** If a template edit adds a required input the pool doesn't have, or removes a feature flag it enables, the pool shows a configuration error and stops creating sessions until you fix it. The warm sessions it already has stay claimable.
- **Repeated failures pause the pool** for a while before it retries, so a broken setup script doesn't burn machines in a loop. The pool page shows the last error.
- **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 size at what demand needs. The size is one call, which makes a schedule easy: warm the pool up for business hours and drain it in the evening. For a workspace pool, a Workspace API token in a cron job does it:
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
```

A size of 0 retires every warm session but keeps the pool, its configuration, and any preview links minted with it. Deleting the pool also retires its warm sessions, and additionally invalidates its preview links. Sessions already claimed from the pool are regular sessions and aren't affected by either.
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

A pool of a template that boots a virtual device keeps devices booted too, which is what makes a [device preview link](/bitrise-rde/devices/device-preview-links) open in the time it takes to download the app. Mint the link against a workspace 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).
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, and it installs the moment the session is handed out, because the device is already running.
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 your pools under **My pools** and the shared ones under **Workspace 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.
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 see every pool in the workspace, including other members' personal pools, on the **Usage** page and with `bitrise-cli rde warm-pool list --all`. That view is read-only: only a pool's owner manages it.
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.
Loading
Loading