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

# murmur pool flush

> Destroy all warm VMs in your tenant's pool so it replenishes with fresh ones built from the current base image — useful after a re-bake.

<Warning>
  Flush destroys warm VMs immediately. With `--nuke`, it also terminates every running agent workflow and deletes every VM in the tenant. The `--nuke` flag is irreversible — all in-progress work that has not been pushed or opened as a pull request is lost.
</Warning>

Destroys idle (warm) VMs in the [pool](/concepts/pools). The [pool](/concepts/pools) workflow then replenishes with fresh VMs built from the current base image. Running [agents](/concepts/agents) are not affected — only warm VMs waiting for assignment are deleted.

Use this after changing an [environment](/concepts/environments) configuration or baking a new [image](/concepts/images), so that newly spawned [agents](/concepts/agents) pick up the changes.

## Synopsis

```bash theme={null}
murmur pool flush [flags]
```

<Note>
  [Pool](/concepts/pools) commands run from your laptop only. They are not available on agent VMs.
</Note>

## Arguments

| Name          | Type   | Required | Description                                                                             |
| ------------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `--nuke`      | bool   | no       | Terminate all agent workflows and delete all VMs, not just warm ones. Default: `false`. |
| `--workspace` | string | no       | Workspace name. Overrides the value from `murmur.yaml`.                                 |

## Output

Without `--nuke`, prints the number of warm VMs flushed:

```
Flushing warm VMs...
Flushed 3 warm VMs — pool will replenish with fresh ones
```

If no warm VMs exist:

```
Flushing warm VMs...
No warm VMs to flush
```

With `--nuke`, prints the total number of workflows terminated and VMs deleted:

```
Nuking all workflows and VMs...
Nuke complete (12 terminated/deleted)
```

## Examples

### Flush warm VMs after a new image bake

```bash theme={null}
murmur pool flush
```

```
Flushing warm VMs...
Flushed 2 warm VMs — pool will replenish with fresh ones
```

The [pool](/concepts/pools) begins provisioning replacement VMs from the latest base image.

### Nuclear reset

<Warning>
  This terminates every running [agent](/concepts/agents) and deletes every VM in the tenant. Use only when you need to start completely fresh.
</Warning>

```bash theme={null}
murmur pool flush --nuke
```

```
Nuking all workflows and VMs...
Nuke complete (8 terminated/deleted)
```

## Errors

| Code                | Meaning                                                  | What to do                                                         |
| ------------------- | -------------------------------------------------------- | ------------------------------------------------------------------ |
| `UNAUTHENTICATED`   | Identity token is missing or expired.                    | Run `murmur auth` or check your `murmur.local.yaml` configuration. |
| `PERMISSION_DENIED` | Your role does not have `pool-config.delete` permission. | Ask a tenant admin to grant you the required permission.           |
| (exit error)        | `pool commands are not supported on VMs`                 | Run this command from your laptop, not from an agent VM.           |

## Related

* [Pools](/concepts/pools) — concept overview
* [`pool-config`](/catalog/pool-config) — catalog resource that controls pool capacity limits
* [`murmur pool status`](/cli/pool-status) — check the current pool state
* [`murmur pool up`](/cli/pool-up) — ensure the pool is running after a flush
* [`murmur kill`](/cli/kill) — cancel a single agent (use instead of `--nuke` for targeted cleanup)