A pool config is a catalog resource that sets tenant-level limits on agent VMs. It is a singleton — every tenant has exactly one pool config, always named default.
Changes to pool config take effect immediately. When you update max_vms, the pool recalculates capacity on the next cycle.
Fields
| Name | Type | Required | Description |
|---|
max_vms | int32 | yes | Maximum total VMs (warm + running) across all environments. Must be greater than 0. |
max_agents_per_developer | int32 | no | Maximum active agents a single developer may have. Counts every non-terminal agent — including idle and sleeping ones, not just those running on a VM. Unset or 0 means unlimited (the default); a cap takes effect only at a value of 1 or more. Must be 0 or positive. See the cap. |
description | string | no | Human-readable description shown in the dashboard. Maximum 1024 bytes. |
reap_stranded_workflows | string | no | Controls automatic cleanup of agent workflows that are stuck on a retired build. Values: dry_run, enabled, disabled. Default when absent: dry_run. |
reap_stranded_workflows values
| Value | Behavior |
|---|
dry_run | Detects stranded workflows and logs them. Does not terminate. This is the default. |
enabled | Detects and terminates stranded workflows after they have been stranded for 48 hours. |
disabled | Skips stranded workflow detection entirely. |
Unrecognized values are treated as disabled.
The max_agents_per_developer cap
max_agents_per_developer caps how many active agents one developer can have at a time. “Active” means any non-terminal agent: a developer who has agents sitting idle or sleeping is still at that count, because a sleeping agent keeps its session and can wake to consume a VM.
The cap counts a developer’s own top-level agents. Child agents that a running agent spawns do not count against it, and agents running under a service profile are not developer agents, so they are exempt. Resurrecting or restarting an existing agent never counts as an additional one.
When a developer at the cap tries to spawn another top-level agent, the spawn is rejected before any VM is provisioned, with RESOURCE_EXHAUSTED:
you have reached your organization's limit of 5 active agents (this includes
idle and sleeping agents) — contact your admin to raise the max agents per developer
0) for no limit.
Examples
Setting the pool config
echo 'max_vms: 50' | murmur set pool-config default
Updating a single field
murmur patch pool-config default --set max_vms=100
Reading the pool config
murmur get pool-config default
max_vms: 50
description: "Production pool limits"
reap_stranded_workflows: dry_run
Full resource with all fields
max_vms: 25
description: "Staging tenant pool"
reap_stranded_workflows: enabled
cat <<'EOF' | murmur set pool-config default
max_vms: 25
description: "Staging tenant pool"
reap_stranded_workflows: enabled
EOF
Errors
| Code | Meaning | What to do |
|---|
INVALID_ARGUMENT | max_vms must be positive | Set max_vms to a value greater than 0. |
INVALID_ARGUMENT | max_agents_per_developer must not be negative (0 = unlimited) | Set max_agents_per_developer to 0 (unlimited) or a positive value. |
INVALID_ARGUMENT | description exceeds 1024 byte limit (<n> bytes) | Shorten the description field to 1024 bytes or fewer. |
