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

# Sandbox lifecycle events

> Follow sandbox lifecycle events and distinguish subscribed notifications from durable runner and membership events.

Track sandbox lifecycle events through webhooks for subscribed account, billing, and lifecycle notifications, and use runner events for a coding turn. These event streams have different cursors and delivery rules.

## Runner events

```bash theme={null}
bead events ID --follow
bead events ID --after 42
```

Runner events are durable within the runner's retained state and replay through `GET /sandboxes/{id}/events?after=N`. Keep the last processed sequence to resume reading. They describe turn progress and approvals; they are not webhook delivery records.

See [events, steering, and approvals](https://docs.bead.run/agents/control.md).

## Lifecycle and account notifications

Register [webhooks](https://docs.bead.run/platform/webhooks.md) for the events you need:

| Category | Event names |
| - | - |
| Machines | `sandbox.created`, `sandbox.ready`, `sandbox.paused`, `sandbox.resumed`, `sandbox.deleted`, `sandbox.failed` |
| Parallel jobs | `fleet.completed`, `swarm.completed` |
| Templates | `template.build.finished`, `template.build.failed` |
| Account membership | `account.claimed`, `account.membership.revoked` |
| Credit and payments | `credit.low`, `credit.exhausted`, `billing.autorefill.failed`, `purchase.completed` |
| Retention | `volume.expiring`, `snapshot.expiring` |
| Human desktop help | `desktop.takeover.requested`, `desktop.control.returned` |

## Interpret lifecycle boundaries

`sandbox.created` means admission committed. `sandbox.ready` means successful guest readiness. `sandbox.deleted` means the lifecycle lease fence expired and quota was released. Fleet completion means all admitted operations finished; inspect individual results to determine success.

Membership events describe account authority changes. They do not grant the receiver authority to access machines or profiles.

## Process deliveries

Subscriptions are prospective. Events without an enabled selected recipient are skipped. Authenticate every webhook delivery, deduplicate its stable event UUID, and read current resource state when your workflow requires it.

Webhook delivery is at least once. Runner replay cursors cannot resume webhook delivery, and webhook event UUIDs cannot continue runner events. Use [delivery logs and signatures](https://docs.bead.run/platform/webhooks.md) for notification recovery.


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