Lifecycle Events

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()

nullspace lifecycle events --limit 20

curl "${NULLSPACE_API_URL}/v1/lifecycle/events?limit=20" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

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)

import { Machine } from "nullspace";

const machine = await Machine.create({ template: "base" });
await machine.commands.run("true", { shell: true });
const events = await machine.lifecycle.list({ limit: 10 });
for (const event of events.events) {
  console.log(event.operation, event.status);
}

nullspace lifecycle events --machine-id mch_123 --limit 10

curl "${NULLSPACE_API_URL}/v1/machines/mch_123/lifecycle?limit=10" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

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()

import { Machine } from "nullspace";

const machine = await Machine.connect("mch_123");
for await (const event of machine.lifecycle.subscribe({
  liveOnly: false,
  replayLimit: 100,
})) {
  console.log(event.id, event.operation, event.status);
}

nullspace lifecycle stream --machine-id mch_123 --replay-limit 100

# WebSocket upgrade; send a `subscribe` message after connecting.
# See ../reference/websocket-protocol for message shapes.
wscat -c "${NULLSPACE_API_URL}/v1/lifecycle/ws" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

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

Field	Notes
`operation`	`create`, `destroy`, `timeout_updated`, `timeout_expired`, `hibernate`, `snapshot_created`, `resume_from_snapshot`, `fork`, or `reconcile`.
`status`	`requested`, `succeeded`, or `failed`.
`audience`	Public SDK helpers expose customer-visible events.
`machine_id`, `snapshot_id`	Present when the operation is tied to that resource.
`source_machine_id`, `target_machine_id`	Present for fork and resume-style transitions.
`error_code`, `error_message`	Populated 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)

nullspace lifecycle events --snapshot-id snap_123 --limit 20

curl "${NULLSPACE_API_URL}/v1/snapshots/snap_123/lifecycle?limit=20" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

Get started

Machines

Commands

Filesystem

Code Interpreter

Desktop

Templates

Volumes

Networking

Interactive access

Observability

List recent events

Per-machine events

Stream events

Filters

Event fields

Snapshot events

​List recent events

​Per-machine events

​Stream events

​Filters

​Event fields

​Snapshot events

​Related

List recent events

Per-machine events

Stream events

Filters

Event fields

Snapshot events

Related