pool-config

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

Leave the field unset (or 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.

Pools — concept overview
murmur set — CLI command for creating and updating catalog resources
murmur get — CLI command for reading catalog resources
murmur pool status — check current pool state

Getting Started

Core Concepts

Guides

Fields

`reap_stranded_workflows` values

The `max_agents_per_developer` cap

Examples

Setting the pool config

Updating a single field

Reading the pool config

Full resource with all fields

Errors

​Fields

​reap_stranded_workflows values

​The max_agents_per_developer cap

​Examples

​Setting the pool config

​Updating a single field

​Reading the pool config

​Full resource with all fields

​Errors

​Related

Fields

`reap_stranded_workflows` values

The `max_agents_per_developer` cap

Examples

Setting the pool config

Updating a single field

Reading the pool config

Full resource with all fields

Errors

Related