> ## 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 on-idle

> Change what a running agent does when it goes idle — sleep or keep-alive — without respawning it.

Changes an [agent's](/concepts/agents) idle behavior at runtime. This is the same setting that [`murmur spawn`](/cli/spawn) fixes with its `--on-idle` flag, but applied to an agent that is already running — so you can flip an agent to `keep-alive` for an interactive debugging session, then back to `sleep` to stop paying for an idle VM, without killing and respawning it.

Only `sleep` and `keep-alive` can be set at runtime. `terminate` is a structural decision fixed when the agent spawns ([`murmur spawn --on-idle terminate`](/cli/spawn)) and cannot be changed mid-flight; to tear an agent down now, use [`murmur kill`](/cli/kill).

The change takes effect the next time the agent goes idle; it does not interrupt an in-flight turn.

## Synopsis

```bash theme={null}
murmur on-idle [flags] [slug] <mode>
```

On a VM, the slug is optional — omitting it changes the calling agent's own idle behavior.

## Arguments

| Name          | Type   | Required  | Description                                                 |
| ------------- | ------ | --------- | ----------------------------------------------------------- |
| `slug`        | string | on laptop | The agent's slug. Optional on VMs (defaults to self).       |
| `mode`        | string | yes       | The idle behavior: `sleep` or `keep-alive`.                 |
| `--json`      | bool   | no        | Print the `UpdateOnIdleResponse` as JSON (`{}` on success). |
| `--workspace` | string | no        | Workspace name. Overrides the value from `murmur.yaml`.     |

## Modes

| Mode         | Behavior                                                                                                                                                                       |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sleep`      | Stop the VM and preserve the session; the agent enters `PHASE_SLEEPING` and wakes on a follow-up or with [`murmur wake`](/cli/wake). This is the default an agent spawns with. |
| `keep-alive` | Keep the VM running and the session live indefinitely.                                                                                                                         |

`keep_alive` is accepted as an alias for `keep-alive`, matching the spelling the hosted spawn tool uses.

## Output

```
on-idle set to keep-alive for fix-auth
```

## Examples

### Keep an agent's VM alive for interactive work

```bash theme={null}
murmur on-idle fix-auth keep-alive
```

```
on-idle set to keep-alive for fix-auth
```

### Put it back to sleep when you're done

```bash theme={null}
murmur on-idle fix-auth sleep
```

```
on-idle set to sleep for fix-auth
```

### Change the calling agent's own behavior from its VM

```bash theme={null}
murmur on-idle sleep
```

```
on-idle set to sleep for self
```

## Errors

| Code                       | Meaning                                               | What to do                                                                                                                           |
| -------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `cannot be set at runtime` | You passed `terminate`, which is fixed at spawn time. | Set it at spawn with [`murmur spawn --on-idle terminate`](/cli/spawn), or use [`murmur kill`](/cli/kill) to tear the agent down now. |
| `unknown --on-idle`        | The mode is not `sleep` or `keep-alive`.              | Pass a valid mode.                                                                                                                   |
| `NOT_FOUND`                | No agent with that slug exists.                       | Check the slug spelling. Use [`murmur ls`](/cli/ls) to see running agents.                                                           |
| `UNAUTHENTICATED`          | Identity token is missing or expired.                 | Run `murmur auth` or check your `murmur.local.yaml` configuration.                                                                   |

## Related

* [Agents](/concepts/agents) — concept overview, including the idle behaviors
* [`murmur spawn`](/cli/spawn) — set the initial idle behavior with `--on-idle`
* [`murmur sleep`](/cli/sleep) — stop a running agent's VM now
* [`murmur wake`](/cli/wake) — restart a sleeping agent's VM
* [`murmur kill`](/cli/kill) — cancel an agent permanently