WebSocket Protocol

The daemon accepts WebSocket connections at /ws for real-time, bidirectional communication. Remote agents connect via WebSocket to send messages and receive streaming events.

Connecting

const ws = new WebSocket("ws://127.0.0.1:7741/ws");

ws.onopen = () => {
  // First message must be an auth message
  ws.send(JSON.stringify({
    type: "auth",
    token: process.env.NODE_AUTH_SECRET,
    name: "my-agent",  // optional display name
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg.type, msg);
};

Authentication

The first message after connecting must be an auth message. Until authenticated, only auth and ping messages are accepted.

After 3 failed auth attempts, the connection is closed with code 1008.

Inbound Messages (Client → Server)

Type	Fields	Description
`auth`	`token`, `name?`	Authenticate with Bearer token
`chat`	`message`, `sessionId?`	Send a message to the agent
`ping`	—	Keep-alive ping
`tool_result`	`toolCallId`, `content`, `isError?`	Return result of a tool call

Outbound Messages (Server → Client)

Type	Fields	Description
`auth_ok`	`agentId`	Authentication succeeded
`auth_fail`	`error`	Authentication failed
`text_delta`	`content`	Streaming text chunk from agent
`tool_call`	`id`, `name`, `arguments`	Agent wants to call a tool
`turn_complete`	`tokensIn`, `tokensOut`	Agent finished its turn
`error`	`message`	Error occurred
`pong`	—	Response to ping

Connection Lifecycle

Client opens WebSocket to ws://host:port/ws
Server assigns a unique agentId
Client sends auth message with token
Server responds with auth_ok or auth_fail
Client sends chat messages, receives streaming events
Either side can close the connection at any time

Close Codes

Code	Meaning
`1000`	Normal disconnection
`1008`	Too many failed auth attempts