Protocol

Cyborg7 uses one transport: WebSocket, plus HTTP for REST endpoints. There is no SSE and no separate agent broker. Messaging, agent control, history and presence all use the same sockets. Requests use a request/response pattern with a requestId. Broadcasts are pushed.

Participants

• Clients (web, desktop, mobile) connect to the relay as guests and exchange cyborg:* messages with it.
• Machines connect to the relay with a daemon handshake, and the relay forwards agent work to them.

The relay is the gateway for both.

Handshakes

sequenceDiagram
participant C as Browser or app
participant R as Relay
participant M as Machine
C->>R: guest_hello (user JWT)
M->>R: daemon_hello (daemon token, workspaceIds, providers, ...)
R->>M: relay_subscribed

A client authenticates with a user token (guest_hello). A machine authenticates with a daemon token (daemon_hello), lists the workspaces it belongs to, and reports the providers it has ready, so the relay can route an agent’s work to a machine that can run it.

Machine ↔ relay messages

Message	Direction	Purpose
daemon_hello	Machine → Relay	Authenticate, subscribe to workspaces, report ready providers
relay_subscribed	Relay → Machine	Confirm the subscription
relay_forward	Machine → Relay	Send a message to a workspace
relay_message	Relay → Machine	Deliver a message from a workspace
relay_sync_request	Machine → Relay	Ask for what was missed since a sequence number
relay_sync_response	Relay → Machine	The batch of missed changes
relay_heartbeat	Machine → Relay	Liveness ping (every 30 seconds), also refreshes the ready-provider list
relay_heartbeat_ack	Relay → Machine	Reply that lets the machine tell a live socket from a dead one
relay_token_renewed	Relay → Machine	A fresh daemon token, sent when the current one is past half its life
relay_error	Relay → Machine	An error for the machine
relay_shutdown	Relay → Machine	The relay is going down on purpose. It says roughly how long its drain lasts, and the machine reconnects after that

Sequence numbers

Each workspace has a monotonically increasing seq assigned by the relay, the single point of ordering. This gives:

• Total ordering of messages within a workspace.
• Efficient catch-up: a reconnecting machine asks for what happened after the last seq it saw and replays only the difference.
• No conflicts between machines creating messages at the same time.

Presence

The relay tracks which machines are connected and broadcasts machine status to clients, so the app can show a machine and its agents as online or offline.