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

​
List recent events

from nullspace import Lifecycle

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

​
Per-sandbox events

from nullspace import Sandbox

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

​
Stream events

from nullspace import Lifecycle

lifecycle = Lifecycle()
for event in lifecycle.stream_events(
    sandbox_id="sb_...",
    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(
    sandbox_id="sb_...",
    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, sandbox ID, snapshot ID, source sandbox ID, target sandbox ID, time range, ordering, offset, and limit filters. stream_events supports sandbox ID, snapshot ID, operation, status, audience, metadata matching, after_event_id, live_only, and replay_limit. It does not support source/target sandbox 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.
sandbox_id, snapshot_idPresent when the operation is tied to that resource.
source_sandbox_id, target_sandbox_idPresent for fork and resume-style transitions.
error_code, error_messagePopulated for failed transitions.

​
Snapshot events

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