Bridge protocol

Why it existed

• Security boundary: the bridge exposes a small allowlist instead of the full gateway API surface.
• Pairing + node identity: node admission is owned by the gateway and tied to a per-node token.
• Discovery UX: nodes can discover gateways via Bonjour on LAN, or connect directly over a tailnet.
• Loopback WS: the full WS control plane stays local unless tunneled via SSH.

Transport

• TCP, one JSON object per line (JSONL).
• Optional TLS (when
  text

  Copy

  bridge.tls.enabled
  is true).
• Historical default listener port was
  text

  Copy

  18790
  (current builds do not start a TCP bridge).

When TLS is enabled, discovery TXT records include

plus as a non-secret hint. Note that Bonjour/mDNS TXT records are unauthenticated; clients must not treat the advertised fingerprint as an authoritative pin without explicit user intent or other out-of-band verification.

Handshake + pairing

1. Client sends
   text

   Copy

   hello
   with node metadata + token (if already paired).
2. If not paired, gateway replies
   text

   Copy

   error
   (
   text

   Copy

   NOT_PAIRED
   /
   text

   Copy

   UNAUTHORIZED
   ).
3. Client sends
   text

   Copy

   pair-request
   .
4. Gateway waits for approval, then sends
   text

   Copy

   pair-ok
   and
   text

   Copy

   hello-ok
   .

Historically,

returned and could include .

Frames

Client → Gateway:

• text

  Copy

  req
  /
  text

  Copy

  res
  : scoped gateway RPC (chat, sessions, config, health, voicewake, skills.bins)
• text

  Copy

  event
  : node signals (voice transcript, agent request, chat subscribe, exec lifecycle)

Gateway → Client:

• text

  Copy

  invoke
  /
  text

  Copy

  invoke-res
  : node commands (
  text

  Copy

  canvas.*
  ,
  text

  Copy

  camera.*
  ,
  text

  Copy

  screen.record
  ,
  text

  Copy

  location.get
  ,
  text

  Copy

  sms.send
  )
• text

  Copy

  event
  : chat updates for subscribed sessions
• text

  Copy

  ping
  /
  text

  Copy

  pong
  : keepalive

Legacy allowlist enforcement lived in

(removed).

Exec lifecycle events

Nodes can emit

or events to surface system.run activity. These are mapped to system events in the gateway. (Legacy nodes may still emit .)

Payload fields (all optional unless noted):

• text

  Copy

  sessionKey
  (required): agent session to receive the system event.
• text

  Copy

  runId
  : unique exec id for grouping.
• text

  Copy

  command
  : raw or formatted command string.
• text

  Copy

  exitCode
  ,
  text

  Copy

  timedOut
  ,
  text

  Copy

  success
  ,
  text

  Copy

  output
  : completion details (finished only).
• text

  Copy

  reason
  : denial reason (denied only).

Historical tailnet usage

• Bind the bridge to a tailnet IP:
  text

  Copy

  bridge.bind: "tailnet"
  in
  text

  Copy

  ~/.openclaw/openclaw.json
  (historical only;
  text

  Copy

  bridge.*
  is no longer valid).
• Clients connect via MagicDNS name or tailnet IP.
• Bonjour does not cross networks; use manual host/port or wide-area DNS‑SD when needed.

Versioning

The bridge was implicit v1 (no min/max negotiation). This section is historical reference only; current node/operator clients use the WebSocket Gateway Protocol.

Related

• Gateway protocol
• Nodes