Guides

Sockets

defineSocket files under sockets/ serve WebSockets on the project host.

Default-export defineSocket from robodev/sockets/<name>.ts. sockets/chat.ts serves wss://{projectHost}/sockets/chat. Bracket segments become path params: sockets/rooms/[roomId].ts serves /sockets/rooms/:roomId and sets ctx.params.roomId. robodev dev serves the same handlers on ws://localhost:{port}/sockets/…. A successful reload closes open sockets with 1012 deployed so clients reconnect; a failed compile keeps the previous sockets. This is not the control-plane Build WebSocket and not Postgres CDC.

auth defaults to false (public). Use "required" or "optional" for Robodev Auth. Browsers cannot set Authorization on WebSocket; pass ?accessToken= or a Bearer header. Same tokens as HTTP. Messages are text JSON up to 100KB. Invalid JSON closes with 1007. Binary is out of scope.

ctx.room.join / leave / broadcast are in-process rooms scoped to that socket definition. broadcast sends to other members of the room. APIs and jobs get ctx.sockets.send({ name, room?, payload }) and ctx.sockets.broadcast({ name, payload }). Unknown socket names throw unknown_socket. A missing room is a no-op for send with room. Socket handlers also get ctx.llm, ctx.agent, and ctx.pdf — stream tokens with llm.stream; see LLM (/docs/llm). Tenant agent sessions use ctx.agent; see Agents (/docs/agents). HTML to PDF uses ctx.pdf.fromHtml; see PDF (/docs/pdf).

In the browser, createClient({ url }).socket("/sockets/chat") returns a WebSocket to the project host and attaches accessToken when a stored token exists (http(s) → ws(s)).

import { defineSocket } from "@robodev-ai/sdk";
export default defineSocket({
  auth: "optional",
  onConnect: async ({ room }) => {
    room.join("lobby");
  },
  onMessage: async ({ send, room, user }, data) => {
    room.broadcast("lobby", { from: user?.email ?? "anon", data });
    send({ ok: true });
  },
});