Warm pools keep pre-initialized EC2 instances running and ready to claim. When a user creates an environment, Ona assigns a warm instance instead of launching a new one, reducing startup time from minutes to seconds.
When to use warm pools
Warm pools are most effective for:
- Large or monorepo projects where EBS snapshot restoration adds noticeable startup latency. EC2 instances lazy-load data from the prebuild snapshot on first boot, and larger volumes take longer to fully hydrate. For these projects, warm pools can cut startup time from minutes to around 10 seconds.
- Smaller projects with many users where prebuilds already bring startup to 30-50 seconds. Warm pools can reduce this further to around 10 seconds. Whether the cost is justified depends on how many engineers use the project and how often they create new environments versus reusing existing ones.
- Latency-sensitive workflows where every second of startup time matters (e.g. PR review environments, demo environments).
Without warm pools, each environment launch provisions a new EC2 instance and restores the prebuild snapshot. With warm pools, the instance is already running and the snapshot is already loaded, skipping the most time-consuming parts of startup.
Actual startup time depends on your devcontainer configuration. Dotfiles installation and post-prebuild lifecycle hooks (postCreateCommand, postStartCommand, postAttachCommand) still run when the environment starts. Optimize these commands for the fastest experience.
How it works
- You enable a warm pool for a project and environment class, specifying a pool size (1-20 instances).
- The runner launches that many EC2 instances from the latest prebuild snapshot and keeps them running.
- When a user creates an environment, Ona claims a warm instance from the pool instead of launching a new one.
- The pool automatically replenishes. A new instance starts launching as soon as one is claimed.
- When a new prebuild completes, the pool rotates instances to use the new snapshot.
Instances can be claimed even while still initializing. A partially warmed instance is still faster than a cold start because the EC2 instance is already running and the snapshot is partially loaded.
Pool size does not need to be large. Because instances replenish quickly (they start from a prebuild, so initialization takes minutes, not tens of minutes), a small pool handles bursts well. Start with 1-2 instances and increase only if you observe frequent cold starts.
Prerequisites
- Enterprise plan
- Prebuilds enabled for the project
- AWS runner with warm pool capability (requires runner version that supports warm pools)
- At least one successful prebuild for the environment class
Enable warm pools
Via the dashboard
- Navigate to your project settings
- In the Prebuilds section, find the environment class list
- Expand an environment class row. A Warm Pool toggle appears below each class that has prebuilds enabled
- Toggle Warm Pool on
- Set the Size (number of instances to keep ready, default: 1, range: 1-20)
The warm pool toggle only appears for environment classes on runners that support warm pools and have prebuilds enabled.
Via the CLI
# Create a warm pool for a project and environment class
gitpod prebuild warm-pool create <project-id> \
--environment-class-id <class-id> \
--desired-size 2
# List warm pools for a project
gitpod prebuild warm-pool list --project-id <project-id>
# Check warm pool status
gitpod prebuild warm-pool get <warm-pool-id>
# Update pool size
gitpod prebuild warm-pool update <warm-pool-id> --desired-size 3
# Delete a warm pool
gitpod prebuild warm-pool delete <warm-pool-id>
--format json, --format yaml, and --format table output.
Pool lifecycle
Warm pools go through these phases:
| Phase | Description |
|---|
| Pending | Pool created, waiting for a prebuild snapshot to be assigned |
| Ready | Instances are running and available for claiming |
| Degraded | The runner reported a problem (e.g. failed to launch instances). Check the failure message for details |
| Deleting | Pool is being deleted, instances are draining |
| Deleted | All instances terminated, cleanup complete |
Cost
Warm pool instances are regular EC2 instances running in your AWS account. You pay standard EC2 on-demand pricing for each instance in the pool, 24/7, regardless of whether it is claimed.
No Ona credits are consumed. You pay only for the AWS infrastructure.
Cost estimates
Costs depend on the environment class (instance type) and AWS region. Estimates below use us-east-1 on-demand pricing:
| Environment Class | Instance Type | Approx. cost per instance/month |
|---|
| Small | m6i.large (2 vCPU, 8 GB) | ~$70 |
| Regular | m6i.xlarge (4 vCPU, 16 GB) | ~$140 |
| Large | m6i.2xlarge (8 vCPU, 32 GB) | ~$280 |
m6i.xlarge (Regular) instances costs approximately $280/month in us-east-1. For a team of 20 engineers, that is $14/engineer/month to eliminate startup latency.
EBS volume costs are additional but typically small relative to compute, roughly $0.08/GB/month for gp3 volumes.
Start with a pool size of 1. Increase only if your team frequently hits cold starts during peak hours. A pool of 1-2 instances handles most teams well because instances replenish quickly.
Viewing warm pool costs in AWS
Filter AWS Cost Explorer by the tag gitpod.dev/warm-pool to isolate warm pool instance costs from regular environment costs. See Costs & budgeting for general cost tracking.
Sizing guidance
| Team size | Recommended pool size | Rationale |
|---|
| 1-10 engineers | 1 | Replenishment is fast enough for low concurrency |
| 10-30 engineers | 1-2 | Covers typical burst patterns |
| 30+ engineers | 2-3 | Handles higher concurrency during peak hours |
Limitations
- AWS only. GCP support is coming soon.
- No schedule-based scaling. Pool size is fixed. Dynamic scaling based on time of day or demand is planned.
- No stopped instances. All pool instances run continuously. Support for stopped instances to reduce costs is planned.
