Warm pools
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, where a reviewer clicks and expects the app on screen.
Warm pools aren't available on free-trial workspaces.
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 worksClick to copy link
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, the values of its Shared and On create inputs, 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 workspace's workspace script, if it has one, and then the template's On create hook 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 template's On create hook works. 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 poolClick to copy link
Every member of the workspace with RDE access sees the pool, claims from it, and manages it. A Workspace API token can reach it from CI.
The pool stores the template's Shared and On create inputs as plain values, encrypted at rest when marked secret. Whoever claims a session fills in the On claim and On restore inputs. 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 sessionClick to copy link
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 until the claim. When you claim it, Bitrise sets up your SSH key and Claude credentials, if you supplied them, signs you in to GitHub if you turned on the GitHub integration, and then runs the template's On claim hook with your On claim inputs. See Using hooks with a warm pool.
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 opens, always belong to the workspace.
Creating a poolClick to copy link
- RDE UI
- CLI
- AI agent (MCP)
- API
- 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.
- Choose the template. The form shows only what the template needs: its Shared and On create inputs, feature flags, a device section if the template boots a device, and the same Override machine configuration switch as the session form.
- Enter a Pool name.
- Set the Pool size.
- 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.
bitrise-cli rde warm-pool create ios-reviewers --template "iOS Xcode 26" --size 2
--input and --secret-input set the template's Shared and On create 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.
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.
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 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 sessionClick to copy link
- RDE UI
- CLI
- AI agent (MCP)
- API
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 name the session, choose its owner (Me by default), set its auto-terminate window, and fill in the template's On claim and On restore inputs, if it has any. A pool's page also has a Claim a session button that opens the form with the pool preselected.
bitrise-cli rde session create my-fix --warm-pool ios-reviewers
--input and --map-saved-inputs fill in the template's On claim and On restore inputs.
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.
Set warm_pool_id on the create session request and leave the configuration fields empty. Send the template's On claim and On restore inputs in session_inputs.
The pool fixes the configuration. A claim that also passes a template, Shared or On create 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 healthyClick to copy link
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 hooks 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.
- A failing On create stops the pool. After three failures in a row, the pool shows Setup failed, stops warming, and refuses claims. It keeps the last failed machine for you to inspect, and Retry starts warming again. See When On create fails in a warm pool.
- Repeated machine failures pause the pool. When machines fail to boot, the pool waits a while before it retries, so it doesn't keep starting new machines. The pool page shows the last error.
Scaling a pool on a scheduleClick to copy link
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:
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 linksClick to copy link
If the pool's template boots a virtual device, the pool keeps devices booted too. This is why a device preview link 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.
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 poolsClick to copy link
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, retry, and delete, and the API 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.