Skip to main content
Lifecycle history and webhooks require hosted or local Supabase-backed state.

​
List recent events

Account-wide listing is available from the Python SDK, CLI, and HTTP API. The TypeScript SDK exposes lifecycle history per machine (machine.lifecycle.list), shown under Per-machine events. 
from nullspace import Lifecycle

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

​
Per-machine events

from nullspace import Machine

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

​
Stream events

The lifecycle stream is a WebSocket channel (/v1/lifecycle/ws). The SDKs and CLI handle the upgrade and replay for you; raw HTTP clients perform the upgrade described in the WebSocket protocol. 
from nullspace import Lifecycle

lifecycle = Lifecycle()
for event in lifecycle.stream_events(
    machine_id="mch_123",
    live_only=False,
    replay_limit=100,
    metadata={"run": "docs"},
):
    print(event.id, event.operation, event.status)
lifecycle.close()
Use subscribe() when you want callbacks in a background reader: 
subscription = lifecycle.subscribe(
    machine_id="mch_...",
    on_event=lambda event: print(event.operation, event.status),
    on_error=lambda error: print(error.message),
)
subscription.stop()

​
Filters

list_events supports operation, status, audience, machine ID, snapshot ID, source machine ID, target machine ID, time range, ordering, offset, and limit filters. stream_events supports machine ID, snapshot ID, operation, status, audience, metadata matching, after_event_id, live_only, and replay_limit. It does not support source/target machine filters, time range, ordering, offset, or limit. Use after_event_id to resume from a known event ID after reconnecting.

​
Event fields

FieldNotes
operationcreate, destroy, timeout_updated, timeout_expired, hibernate, snapshot_created, resume_from_snapshot, fork, or reconcile.
statusrequested, succeeded, or failed.
audiencePublic SDK helpers expose customer-visible events.
machine_id, snapshot_idPresent when the operation is tied to that resource.
source_machine_id, target_machine_idPresent for fork and resume-style transitions.
error_code, error_messagePopulated for failed transitions.

​
Snapshot events

events = lifecycle.list_snapshot_events("snap_123", limit=20)
for event in events.events:
    print(event.operation, event.status, event.machine_id)