WebSocket Events

The Runtime API broadcasts lifecycle events to all connected WebSocket clients via the existing WebSocket server. Events use the RuntimeEvent message type with a structured JSON payload.

Message format:

{
  "Type": "RuntimeEvent",
  "Content": "{\"event\":\"reload_completed\",\"state\":\"Running\",\"projectName\":\"MyProject.prj\",\"reloadDurationSeconds\":2.34,\"timestamp\":\"2026-04-18T12:15:30.000Z\"}"
}

Events:

Event	Fired when	Extra fields
`state_changed`	Any RuntimeState transition	`previousState`, `reason`
`project_started`	Project start (initial or reload) succeeds	`projectName`, `projectFileName`, `totalProjectsStarted`
`reload_completed`	Reload completes successfully	`projectName`, `reloadDurationSeconds`, `reason`
`load_failed`	Load or reload fails	`projectFileName`, `reason`
`project_stopped`	Project stopped, runtime now idle	`projectName`, `reason`
`first_frame`	First frame rendered after start/reload	`projectName`, `timeToFirstFrameSeconds`
`runtime_exit`	Runtime shutting down	`reason`, `uptimeSeconds`, `totalProjectsStarted`, `totalReloads`, `totalErrors`, `totalWarnings`
`video_worker_crash`	Video worker exited unexpectedly	`projectName`, `severity` ("critical")

All events include event, state, and timestamp fields. Events are fire-and-forget — if no WebSocket clients are connected, the WebSocket broadcast is silently skipped. This does not affect the SSE stream, which carries the same events to its own subscribers independently.

The runtime_exit reason field reports why shutdown began, so monitoring can distinguish an orchestrator/operator stop from a fault. It is one of: SigTerm, SigInt, SigQuit (POSIX signals on Linux — e.g. a container orchestrator stopping the process), CtrlC (console Ctrl+C / Break), ApiExit (/runtime/exit or the WebApi exit request), TrialExpired, UserKey (the console exit key), or InitialLoadFailed. (An unexpected video-worker exit is reported via the separate video_worker_crash event instead.)