> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beam.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Lifecycle

> Stop, start, pause, resume, and automatically sleep persistent VMs

A VM's name, ID, durable root, and published URLs belong to the persistent resource. Starting it again may create a new runtime, while retaining those identities.

## Inspect state

```bash theme={null}
beam vm list
beam vm get devbox
beam vm list --status stopped --json
```

`list` displays CPU, memory, configured root disk size, and uptime for the current running boot. `get --json` includes the specification, state, current container ID, and URLs. States include `starting`, `running`, `stopping`, `stopped`, `paused`, and `error`.

| Operation | Persistent filesystem | RAM and processes | Compute after completion |
| - | - | - | - |
| Stop | Saved | Discarded | Released |
| Start a stopped VM | Restored | New boot; enabled systemd services start | Running |
| Pause | Saved with the memory checkpoint | Saved | Released |
| Resume a paused VM | Restored with its saved RAM | Restored | Running |
| Start with `--cold` | Retained | Saved RAM discarded; new boot | Running |
| Snapshot | Captured as a restore point | Not included | Current VM keeps its state |
| Fork | Copied to an independent root | New boot | A new VM runs |
| Remove | VM root deleted | Discarded | Released |

## Stop and start

```bash theme={null}
beam vm stop devbox
beam vm start devbox
```

Stop saves the latest root contents before releasing compute and creates a filesystem snapshot artifact by default. Start cold-boots the saved filesystem. A command you launched manually does not rerun on a cold boot; install a [systemd service](/v2/vm/processes#systemd-services) if it should start automatically.

`--no-snapshot` skips the named snapshot artifact, while still saving the durable root:

```bash theme={null}
beam vm stop devbox --no-snapshot
beam vm start devbox
```

## Pause and resume

```bash theme={null}
beam vm pause devbox
beam vm resume devbox
```

Pause checkpoints memory and its paired disks, then shuts down the microVM. Resume restores those processes and memory. `beam vm start` also resumes a paused VM; `resume` is an alias for `start`.

External network peers can close connections while the VM is paused. Applications should reconnect their database, API, and other external sessions after resuming.

To keep the disk but explicitly discard paused RAM:

```bash theme={null}
beam vm start devbox --cold
```

The Python equivalents are `vm.stop()`, `vm.start()`, `vm.pause()`, `vm.resume()`, and `vm.start(cold=True)`.

## Idle TTL and automatic resume

Unlike a sandbox lifetime, a VM TTL measures **idle time**. It does not delete the VM.

```bash theme={null}
beam vm new devbox --ttl 300 --auto-resume --protected-port 7681
```

After 300 idle seconds, the default action saves the root and stops the VM. Set `--idle-action pause` to preserve RAM instead:

```bash theme={null}
beam vm update devbox --ttl 300 --idle-action pause --auto-resume
```

```python theme={null}
from beam import VM

vm = VM.get("devbox")
vm.update(ttl=300, idle_action="pause", auto_resume=True)
vm.close()
```

Automatic resume wakes a stopped or paused VM on an SDK operation that needs its runtime, authenticated tunnel access, or a permitted request to a published URL. Merely listing or inspecting the VM does not wake it. Without automatic resume, start it explicitly before executing commands or using a URL.

Disable idle sleep or automatic resume separately:

```bash theme={null}
beam vm update devbox --ttl 0
beam vm update devbox --no-auto-resume
```

### What counts as activity?

Foreground CLI execution, SSH/tunnels, and active desktop or terminal WebSockets keep an activity lease. SDK access to processes or files updates activity. A command running inside the guest by itself is not a continuous activity signal.

For a long Python operation on an idle-limited VM, hold a lease:

```python theme={null}
from beam import VM

with VM.get("devbox") as vm:
    with vm.keep_alive():
        process = vm.process.exec("bash", "-lc", "./long-build.sh")
        for line in process.logs:
            print(line, end="")
        print(process.wait())
```

<Note>
  Detached commands and background coding agents do not keep the VM awake for their entire lifetime. Disable the TTL for unattended jobs, or keep an SDK activity lease open until the job finishes.
</Note>

## Python client lifetime and readiness

`VM.get(name)` resolves state without starting the machine. `VM.connect(name)` also starts or resumes it. `create()` and `start()` wait for exec readiness by default. Use `wait(services=True)` when you also need SSH, the terminal, and an enabled desktop to be ready.

```python theme={null}
from beam import VM

with VM.connect("devbox") as vm:
    vm.wait(services=True)
    print(vm.info["status"])
```

`close()` and exiting a `with VM...` block release local client connections. They leave the VM running. Use `stop()`, `pause()`, or `remove()` to release compute.

## Remove a VM

```bash theme={null}
beam vm rm devbox
```

Removal deletes the VM and its root disk. Saved snapshot and template artifacts, additional named disks, and shared volumes are managed separately. Use `beam vm snapshot rm` and `beam vm template rm` to remove artifacts you no longer need.

## Troubleshooting

| Symptom | Next step |
| - | - |
| `VM is not running` | Run `beam vm start NAME`, or enable automatic resume. |
| VM is starting or in an error state | Inspect `beam vm get NAME --json` for the error and configuration. Verify that your selected pool supports CPU microVMs and has capacity. |
| Service is unavailable after a cold boot | Inspect `beam vm logs NAME --unit SERVICE` and make sure the unit is enabled. |
| Browser access fails after sleeping | Start the VM, then reopen it with `beam vm desktop NAME` or `beam vm terminal NAME` to obtain a fresh protected session. |
| VM slept while a background job was working | Set `--ttl 0` or hold `vm.keep_alive()` during the job. |
| Wrong workspace or gateway | Check `beam whoami` and `beam config list`; use `beam --context CONTEXT vm get NAME`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.