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.