> ## 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.

# pool-config

> Catalog resource that caps how many agent VMs your tenant can run at once and configures the warm-pool size that keeps spawns fast.

A [pool](/concepts/pools) 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](/concepts/pools) recalculates capacity on the next cycle.

## Fields

| Name                       | Type   | Required | Description                                                                                                                                                                                                                                                                                                                                          |
| -------------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `max_vms`                  | int32  | yes      | Maximum total VMs (warm + running) across all [environments](/concepts/environments). Must be greater than 0.                                                                                                                                                                                                                                        |
| `max_agents_per_developer` | int32  | no       | Maximum active [agents](/concepts/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](#the-max_agents_per_developer-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.                                           |

<Note>
  Unrecognized values are treated as `disabled`.
</Note>

## The `max_agents_per_developer` cap

`max_agents_per_developer` caps how many active [agents](/concepts/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](/concepts/service-profiles) 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

```bash theme={null}
echo 'max_vms: 50' | murmur set pool-config default
```

### Updating a single field

```bash theme={null}
murmur patch pool-config default --set max_vms=100
```

### Reading the pool config

```bash theme={null}
murmur get pool-config default
```

```yaml theme={null}
max_vms: 50
description: "Production pool limits"
reap_stranded_workflows: dry_run
```

### Full resource with all fields

```yaml theme={null}
max_vms: 25
description: "Staging tenant pool"
reap_stranded_workflows: enabled
```

```bash theme={null}
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.                |

## Related

* [Pools](/concepts/pools) — concept overview
* [`murmur set`](/cli/set) — CLI command for creating and updating catalog resources
* [`murmur get`](/cli/get) — CLI command for reading catalog resources
* [`murmur pool status`](/cli/pool-status) — check current pool state