Skip to main content

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.

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 min_idle, new ones are booted
  2. Assignment: When you spawn an agent, a warm VM is claimed instantly
  3. Return: When an agent finishes, the VM returns to the pool (if under max_idle)
  4. Scale down: Excess idle VMs beyond max_idle are destroyed
  5. Hard cap: Total VMs never exceed max_vms

​
Pool configuration

Each tenant has a pool-config catalog resource (singleton, always named default):
FieldTypeDescriptionExample
max_vmsintHard cap on total VMs across all developers20
reap_stranded_agentsstringAuto-cleanup mode: enabled, dry_run, or disabledenabled
Additionally, your workspace’s min_idle field controls per-workspace warm VM count. View current pool configuration: 
murmur get pool-config default
Update it: 
murmur patch pool-config default --set max_vms=30

​
Monitoring pool health

murmur pool status
This shows:
  • Running VMs (assigned to agents)
  • Idle VMs (warm, waiting for assignment)
  • Pending boots (being provisioned)
  • Current configuration

​
Pool flush

Destroy all warm (idle) VMs. Useful after changing environment config or images: 
murmur pool flush
This only affects idle VMs — running agents are not interrupted.

​
Cost management

Warm VMs consume compute even when idle. Tune these parameters to balance speed vs cost:
ParameterTrade-off
Higher min_idleFaster agent startup, higher idle cost
Lower min_idleSlower startup (may need cold boot), lower idle cost
Lower max_vmsHard cost cap, but may queue agent starts during peaks
A min_idle of 1–3 is a good starting point for most teams. Agents that finish return their VM to the pool, so active teams naturally keep the pool warm.

​
Idle timeout

When an agent completes, its VM stays warm for the idle timeout period (configurable in the environment). After that, the VM is stopped or destroyed depending on pool state. While warm, the VM can be instantly reassigned to a new agent.