Signaling

Signaling is the real-time side of the engine API. The engine exposes the same stream over Server-Sent Events and over WebSocket, and the CLI and SDKs provide higher-level helpers on top of those raw transports.

Signaling serves a different purpose from the list APIs. The list APIs answer the point-in-time inventory question. Signaling carries that same inventory as an initial snapshot and then continues with incremental updates. This makes it suitable for fleet management, dashboards, automation controllers, and applications that need to react to resource changes without polling.

Engine endpoints and transports

The engine exposes an SSE endpoint at /api/sse and a WebSocket endpoint at /api/websocket. Both accept an authentication token through the rstream.token query parameter. The Go SDK and the CLI expose both sse and websocket transport values, and the JavaScript SDK watch helper uses the same transport model.

Both transports send a state.initial event first, containing snapshot arrays of clients and tunnels, and then continue with incremental updates.

Filtering the stream

The signaling endpoints accept a params query parameter that applies server-side filters to both the initial snapshot and subsequent client.* and tunnel.* events. Client filters and tunnel filters are configured independently, which makes it possible to observe a subset of agents and a subset of tunnels in the same connection.

As with the list APIs, these filters are intended for the properties that vary inside a project. Labels are usually the most useful tunnel selectors, while client filters are typically built around agent metadata such as agent, channel, version, os, arch, or user_id. In practice, labels are often the most stable selectors because they follow service identity or environment segmentation rather than generated hostnames.

CLI usage

The CLI subscribes to the stream with rstream events. --client-filter and --tunnel-filter apply server-side filters. --events narrows the local output to selected event types after the filtered stream has been received. The command can emit newline-delimited JSON to stdout or forward selected events as HTTP POST requests to an external endpoint.

rstream events \
  --transport websocket \
  --client-filter 'agent=rstream,channel=dev' \
  --tunnel-filter 'labels.service=ssh,labels.env=prod'

rstream events \
  --transport sse \
  --events tunnel.created,tunnel.updated \
  --tunnel-filter 'labels.service=api' \
  --forward-to https://example.internal/hooks/rstream

The same filtering model is available in the Go and JavaScript SDKs through watch parameters. This keeps the selection model consistent across raw API calls, CLI inspection, and embedded application integrations. For the surrounding API model, see APIs; for label-driven selection, see Labels; and for SDK-specific helpers, see JS SDK and Go SDK.