Build a Custom Client

Custom FlowLayer clients use the same protocol surface as the official TUI:

• WebSocket endpoint: /ws
• Authentication: Authorization: Bearer <token> on upgrade
• Envelope model: command, ack, result, event, error

See Protocol Overview and Message Envelopes.

Minimal client flow

1. Connect to /ws with Bearer token.
2. Read initial hello event.
3. Read initial snapshot event.
4. Keep reading live events (service_status, log).
5. Send runtime commands as needed.

There is no explicit subscribe message for live events in V1. Events are pushed on the active session.

Envelope examples

Command:

{
  "type": "command",
  "id": "cmd-1",
  "name": "get_snapshot"
}

Ack:

{
  "type": "ack",
  "id": "cmd-1",
  "payload": {
    "accepted": true
  }
}

Result:

{
  "type": "result",
  "id": "cmd-1",
  "payload": {
    "ok": true,
    "data": {
      "services": [
        { "name": "api", "status": "running" }
      ]
    }
  }
}

Live event:

{
  "type": "event",
  "name": "service_status",
  "payload": {
    "service": "api",
    "status": "ready",
    "timestamp": "2026-04-25T10:05:00Z"
  }
}

Practical guidance

• Correlate command lifecycle strictly by id.
• Treat reconnect as a new independent session (no automatic replay).
• Use get_logs with after_seq to recover continuity after reconnect or event loss.
• Keep JSON decoding tolerant to additional fields to stay forward-compatible.

Common runtime commands:

• get_snapshot
• get_logs
• start_service
• stop_service
• restart_service
• start_all
• stop_all

See Events, Logs, and Actions for payload details.