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 platform maintains warm VM pools for fast agent startup. When you spawn an agent, it claims a pre-booted VM from the pool instead of waiting for a fresh boot. These commands let you monitor pool health, adjust scaling parameters, and flush VMs when needed.
murmur pool status
Show the current state of your tenant’s VM pool, including running VMs, idle count, pending boots, and active configuration.
murmur pool status [flags]
Flags
| Flag | Type | Description |
|---|
--workspace | string | Override workspace |
Example output
Pool: default
Status: healthy
VMs:
Total: 12
Active: 8 (running agents)
Idle: 3 (warm, ready to claim)
Booting: 1 (starting up)
Configuration:
max_vms: 30
min_idle: 2
max_idle: 5
idle_timeout: 15m
boot_timeout: 5m
murmur pool up
Trigger the pool to scale up, ensuring warm VMs are available. This is a manual nudge to the pool scaler — it ensures at least min_idle VMs are ready.
Flags
| Flag | Type | Description |
|---|
--workspace | string | Override workspace |
min_idle target.
murmur pool flush
Destroy warm (idle) VMs in the pool. Active VMs running agents are not affected.
murmur pool flush [flags]
Flags
| Flag | Type | Description |
|---|
--nuke | bool | Also terminate active VMs (kills running agents). Use with extreme caution. |
--workspace | string | Override workspace |
# Flush idle VMs only
murmur pool flush
# Nuclear option: terminate everything (idle + active)
murmur pool flush --nuke
murmur pool flush --nuke terminates all VMs including those running agents. All running agents will be killed. Use only when you need a complete pool reset.
When to flush
- After image updates: Flush warm VMs so new spawns pick up the updated image.
- After config changes: Flush to ensure warm VMs match the new configuration.
- Cost management: Flush idle VMs when you know no new agents will be spawned for a while.
- Debugging: Start fresh when VMs are in a bad state.
Pool configuration
Pool behavior is controlled by a pool-config catalog resource. Every tenant has a default pool config.
Viewing pool config
murmur get pool-config default
Example pool config
max_vms: 30
min_idle: 2
max_idle: 5
idle_timeout: 15m
boot_timeout: 5m
Configuration fields
| Field | Type | Default | Description |
|---|
max_vms | int | 30 | Maximum total VMs (active + idle) in the pool |
min_idle | int | 2 | Minimum number of warm idle VMs to maintain |
max_idle | int | 5 | Maximum number of idle VMs before excess are terminated |
idle_timeout | duration | 15m | How long a completed agent’s VM stays warm before termination |
boot_timeout | duration | 5m | Maximum time to wait for a VM to boot before considering it failed |
Modifying pool config
Use murmur patch to update individual fields:
# Increase max VMs
murmur patch pool-config default --set max_vms=50
# Increase minimum warm VMs for faster spawns
murmur patch pool-config default --set min_idle=5
# Reduce idle timeout to save costs
murmur patch pool-config default --set idle_timeout=5m
# Multiple changes at once
murmur patch pool-config default \
--set max_vms=20 \
--set min_idle=3 \
--set max_idle=8
cat <<EOF | murmur set pool-config default
max_vms: 20
min_idle: 3
max_idle: 8
idle_timeout: 10m
boot_timeout: 5m
EOF
Understanding pool scaling
The pool scaler runs continuously and maintains these invariants:
- Scale up: If idle VMs <
min_idle and total VMs < max_vms, boot new VMs
- Scale down: If idle VMs >
max_idle, terminate excess idle VMs
- Timeout: If an idle VM has been idle longer than
idle_timeout, terminate it
- Claiming: When
murmur spawn runs, the oldest idle VM is claimed. If none are available, a new VM is booted on demand (subject to max_vms).
┌──────────┐
spawn ────claim───▶│ Idle VM │──────▶ Active (running agent)
└──────────┘ │
▲ │
boot │ agent completes
│ │
┌────┴─────┐ ▼
│ Scaler │◀──── Return to idle pool
└──────────┘ (or terminate if
idle_timeout or
max_idle exceeded)
Cost considerations
Warm VMs incur compute costs even when idle. Tune these parameters to balance cost against spawn latency:
| Goal | Action |
|---|
| Faster spawns | Increase min_idle (more warm VMs ready) |
| Lower costs | Decrease min_idle, decrease idle_timeout |
| Burst capacity | Increase max_vms (allows more concurrent agents) |
| Tight budget | Set min_idle=0 (all spawns boot on demand, ~60s delay) |
murmur patch pool-config default \
--set max_vms=20 \
--set min_idle=2 \
--set max_idle=5 \
--set idle_timeout=10m
