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

# Python SDK Lifecycle

> Read lifecycle events, stream live updates, and inspect webhook deliveries.

Lifecycle APIs expose customer-visible machine and snapshot transitions.

> Lifecycle history and webhooks require hosted or local Supabase-backed state.

## List events

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
from nullspace import Lifecycle

lifecycle = Lifecycle()
events = lifecycle.list_events(limit=20)
for event in events.events:
    print(event.operation, event.status)
```

## Per-machine events

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
from nullspace import Machine

with Machine.create() as machine:
    machine.commands.run("true", shell=True)
    events = machine.list_lifecycle(limit=10)
    print([event.operation for event in events.events])
```

## Stream events

Use `stream_events()` when code needs to react to lifecycle events without
polling. The iterator reconnects automatically after transport drops. On every
yield it records the event ID, then reconnects with `after_event_id` so the API
can replay missed committed events before returning to live delivery.

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
from nullspace import Lifecycle, LifecycleOperation

lifecycle = Lifecycle()
try:
    for event in lifecycle.stream_events(
        operation=LifecycleOperation.CREATE,
        replay_limit=100,
    ):
        print(event.id, event.machine_id, event.operation, event.status)
finally:
    lifecycle.close()
```

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
from nullspace import AsyncLifecycle

lifecycle = AsyncLifecycle()
try:
    async for event in lifecycle.stream_events(live_only=True):
        print(event.id, event.operation)
finally:
    await lifecycle.close()
```

Supported filters include `machine_id`, `snapshot_id`, `operation`, `status`,
`live_only`, `after_event_id`, `replay_limit`, and exact-match `metadata`.
`live_only=True` skips the initial replay. After the first yielded event, the
SDK still reconnects with `after_event_id` so reconnects do not lose events.

## Webhooks

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace lifecycle webhooks create \
  --url https://example.com/nullspace/lifecycle \
  --operation create \
  --operation destroy \
  --signing-secret "$NULLSPACE_LIFECYCLE_WEBHOOK_SIGNING_SECRET"
nullspace lifecycle webhooks deliveries wh_123
nullspace lifecycle webhooks delivery wh_123 del_123
```

Concepts: [Create](../../concepts/create), [Destroy](../../concepts/destroy).
API reference: [listLifecycleEvents](../../api-reference),
[listMachineLifecycleEvents](../../api-reference), and
[createLifecycleWebhook](../../api-reference).