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

# Managing Capsule Lifecycle: Pause, Resume, Destroy

> Control capsule state with pause, resume, and destroy operations. Understand how Wrenn preserves running capsules via snapshot-based persistence.

Every capsule moves through a defined set of states from creation to destruction. Understanding those states lets you build reliable workflows: pausing idle capsules to save resources, resuming them instantly when needed, and cleaning up with confidence.

## Lifecycle states

| State      | Description                                                        |
| ---------- | ------------------------------------------------------------------ |
| `pending`  | Capsule is queued and waiting to be scheduled on a host.           |
| `starting` | Capsule is booting — the microVM kernel is starting up.            |
| `running`  | Capsule is fully booted and ready to accept commands.              |
| `paused`   | Capsule state has been snapshotted to disk and the VM has stopped. |
| `stopped`  | Capsule has exited and cannot be resumed.                          |
| `error`    | Capsule entered an unrecoverable error state.                      |

<Note>
  When you pause a capsule, Wrenn writes the full VM state — memory, processes, open files — to disk as a snapshot. Resuming restores that snapshot, so the capsule comes back exactly as you left it.
</Note>

## Waiting for a capsule to be ready

After creating a capsule without `wait=True`, call `wait_ready()` to block until it reaches `running` status:

```python theme={null}
capsule = Capsule(template="minimal")
capsule.wait_ready(timeout=30, interval=0.5)
```

`wait_ready` raises `TimeoutError` if the capsule does not reach `running` within `timeout` seconds. It raises `RuntimeError` if the capsule enters `error`, `stopped`, or `paused` state while waiting.

## Checking status

```python theme={null}
# Live check — makes an API call
if capsule.is_running():
    print("capsule is ready")

# Fetch full metadata
info = capsule.get_info()
print(info.status)        # "running"
print(info.vcpus)         # 1
print(info.memory_mb)     # 512
```

## Pausing a capsule

Pausing snapshots the running VM to disk and frees the host CPU and memory. The capsule's filesystem and process state are preserved exactly.

```python theme={null}
# Instance method
capsule.pause()

# Static method — no instance required
Capsule.pause("cl-abc123")
```

## Resuming a capsule

Resume restores the snapshot and brings the capsule back to `running`. Memory, processes, and open file descriptors are all restored.

```python theme={null}
# Instance method
capsule.resume()

# Static method
Capsule.resume("cl-abc123")
```

`Capsule.connect()` also resumes a paused capsule automatically:

```python theme={null}
capsule = Capsule.connect("cl-abc123")  # resumes if paused
```

## Destroying a capsule

Destroying a capsule permanently deletes the VM and all data on its filesystem.

```python theme={null}
# Instance method
capsule.destroy()

# Static method
Capsule.destroy("cl-abc123")
```

<Warning>
  Destruction is irreversible. Create a snapshot first if you need to preserve the capsule's state as a reusable template.
</Warning>

## Inactivity timeout and ping

When you create a capsule with a `timeout` value, the capsule is automatically paused after that many seconds of inactivity. An activity is any `exec` or `ping` call.

Call `ping()` to reset the inactivity timer without executing a command:

```python theme={null}
import time

capsule = Capsule(template="minimal", timeout=60, wait=True)

# Keep the capsule alive during a long-running local operation
for _ in range(10):
    time.sleep(30)
    capsule.ping()
```

<Tip>
  Set `timeout=0` to disable auto-pause entirely. Use this for capsules that must stay running regardless of activity.
</Tip>

## Full lifecycle example

```python theme={null}
from wrenn import Capsule

# Create and wait for ready
capsule = Capsule(template="minimal", timeout=120, wait=True)
print(capsule.capsule_id)      # "cl-abc123"
print(capsule.is_running())    # True

# Do some work
capsule.commands.run("python train.py")

# Pause to save resources
capsule.pause()
info = capsule.get_info()
print(info.status)  # "paused"

# Resume later and continue
capsule.resume()
capsule.wait_ready()
capsule.commands.run("python eval.py")

# Clean up
capsule.destroy()
```