> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Pools

> Pre-booted warm VMs maintained by Murmur so agents start in seconds instead of waiting minutes for a fresh boot, base image, and provisioning.

The VM pool is why agents start in seconds, not minutes. The platform maintains pre-booted VMs ready for instant assignment. When you spawn an agent, it claims a warm VM immediately instead of waiting for a cold boot.

## How the pool works

The platform continuously maintains a set of warm VMs:

1. **Backfill** — when idle VMs drop below the workspace's `min_idle` threshold, new ones are booted
2. **Assignment** — when you spawn an agent, a warm VM is claimed instantly
3. **Hard cap** — total VMs never exceed `max_vms` (set in [pool-config](/catalog/pool-config))

## Pool configuration

Each tenant has a [`pool-config`](/catalog/pool-config) resource (singleton, always named `default`) that sets the tenant-wide `max_vms` cap. Each [workspace](/concepts/workspaces) has a `min_idle` field that controls how many warm VMs to keep ready for that workspace.

Monitor pool health with [`murmur pool status`](/cli/pool-status). After changing [environment](/concepts/environments) config or [images](/concepts/images), use [`murmur pool flush`](/cli/pool-flush) to drain warm VMs so fresh ones are created from the new configuration.

## Cost management

Warm VMs consume compute even when idle. Tune these parameters to balance speed vs cost:

| Parameter         | Trade-off                                              |
| ----------------- | ------------------------------------------------------ |
| Higher `min_idle` | Faster agent startup, higher idle cost                 |
| Lower `min_idle`  | Slower startup (may need cold boot), lower idle cost   |
| Lower `max_vms`   | Hard cost cap, but may queue agent starts during peaks |

A `min_idle` of 1–3 is a good starting point for most teams.

***

| Type      | Page                                     |
| --------- | ---------------------------------------- |
| Reference | [pool-config](/catalog/pool-config)      |
| Reference | [`murmur pool status`](/cli/pool-status) |
| Reference | [`murmur pool up`](/cli/pool-up)         |
| Reference | [`murmur pool flush`](/cli/pool-flush)   |
| Concept   | [Workspaces](/concepts/workspaces)       |
| Concept   | [Environments](/concepts/environments)   |