WebSocket Protocol

The OmniLoop WebSocket protocol provides the bidirectional control plane for telemetry, replay, and live variable mutation.

Connection

Endpoint: ws://127.0.0.1:8000/ws

Protocol Version: 1

Note

The protocol version is bumped on breaking changes only. Additive messages and fields do not require a version bump.

Handshake

The server’s first message on every connection is hello:

{
  "type": "hello",
  "protocol": 1,
  "server": "omniloop-oss",
  "auth_required": false,
  "capabilities": ["mutation", "watch", "replay", "fork", "export"],
  "principal": {"id": "local", "display_name": "Local user"}
}

• capabilities reflects what this server will actually allow — e.g. fork is omitted when timeline forking is disabled, so clients hide the control instead of hitting runtime errors.
• principal is who the server believes this connection is.
• Clients should reply with {"client_hello": {"protocol": 1, "client": "<name>/<version>"}}; clients that never do are treated as legacy and remain fully supported. The server never rejects a connection over a version mismatch.

Authentication

With no token configured (the default), every connection is the implicit local principal. When the server is started with OMNILOOP_AUTH_TOKEN, the first hello arrives with "auth_required": true and no capabilities; the client must then send {"auth": {"token": "..."}} within 5 seconds (or connect with ?token=... in the URL). On success a second, fully populated hello follows; on failure the socket closes with code 4401. HTTP endpoints accept the same token as Authorization: Bearer <token>. Websocket handshakes from browsers are additionally subject to an Origin allow-list (OMNILOOP_ALLOWED_ORIGINS); disallowed origins close with 4403.

Capabilities

The protocol supports the following capabilities:

Capability	Description
mutation	Live parameter editing
watch	Watchpoint support
replay	Journal replay
fork	Timeline forking
export	State export

Messages

Server-to-Client Messages

Messages sent from the OmniLoop server to the connected client.

Message	Description
hello	Handshake: protocol version, capabilities, principal (always first)
telemetry	State frame from the target process
schema	Parameter schema declaration
replay_info	Journal metadata + events for timeline
state_exported	Response to export_state action
info	Informational message
error	Error message
go_to_line	Source navigation request
set_execution_node	Execution node update

Client-to-Server Messages

Messages sent from the client to the OmniLoop server.

Message	Format	Description
client_hello	{"client_hello": {"protocol": 1, "client": "..."}}	Client introduction after hello
auth	{"auth": {"token": "..."}}	First-message token authentication (see Handshake)
mutation	{"mutation": {"<name>": <value>, ...}}	One or more parameter edits, keyed by variable name; the reserved key sys carries system commands (halt/resume/step)
watch	{"watch": {"name": ..., "condition": ..., "threshold": ...}} or {"watch": "clear"}	Arm/clear watchpoints
action	{"action": "...", ...params}	Trigger an action (see Actions below)

Actions

The following actions can be triggered by the client using the action message:

Action	Description
start_replay	Begin journal replay
stop_replay	Stop journal replay
get_frame	Request a specific frame by frame_index
fork_timeline	Restart worker from snapshot state
load_trace	Load a .omni file for replay
export_state	Export current state
clear_mutations	Clear pending mutations
reset_gains	Reset to initial values
trigger_exception	Deliberately trigger an exception (for testing)
go_to_line	Navigate to source line
set_execution_node	Set active execution node