WebSockets and SSE
One Node process streams Server-Sent Events, runs a WebSocket echo chat and serves an admin JSON view, each on its own port behind its own hostname. It shows WebSockets and SSE working through the devlanes proxy with nothing to configure, and how to give a service’s extra ports their own hostnames. The server uses Hono; the page’s browser code is TypeScript bundled by Vite.
Requirements
Section titled “Requirements”- devlanes, with
devlanes setuprun once - Node 22 or later
Run it
Section titled “Run it”cd web-realtime-wsdevlanes startdevlanes start --no-ui prints the start as text:
example-realtime-ws@0 (main): 1/1 readyready realtime http://127.0.0.1:20421 https://example-realtime-ws.localhostOpen https://example-realtime-ws.localhost. The page says This is lane 0 of example-realtime-ws., shows a tick from /events every second, and has a chat that echoes each message tagged with the lane and the hostname it came through.
During a start
Section titled “During a start”- The first start of a lane runs the
installtask (npm install), because a new worktree has nonode_modules. - The
realtimeservice’senvmentionsself.ports.wsandself.ports.admin, so devlanes gives it two more ports next toPORT, with the same offsets in every lane. - It runs
npm run dev, which builds the page’s browser code fromsrc/client/intodist/clientwith Vite, then runstsx watch src/index.ts. Server edits restart the server; after a client edit,devlanes restart realtimerebuilds it. - The server opens the
wsandadminports first and the main port last, so thehttpready check on/healthzpasses once all three listen.
Ports and hostnames
Section titled “Ports and hostnames”| Hostname | Port | Serves |
|---|---|---|
example-realtime-ws. | main (PORT) | the page, SSE on /events, a WebSocket on /ws, /lane, /healthz |
ws. | ws (WS_PORT) | the chat’s WebSocket, on any path |
admin. | admin (ADMIN_PORT) | connections, ticks and recent messages as JSON |
Every port answers /healthz and /lane, so each hostname can be checked on its own. WebSockets and SSE need no key in devlanes.yaml: the proxy bridges upgrades on any hostname and path and streams /events without buffering. The page opens both wss://ws.example-realtime-ws.localhost and wss://example-realtime-ws.localhost/ws to show that the main port takes upgrades too. The page and the ws hostname are different origins, so the server accepts a browser’s socket only when its Origin is in DEVLANES_ORIGINS, and answers others with 403.
devlanes status lists the service’s three ports, and devlanes url ls the hostname that answers on each:
$ devlanes statusexample-realtime-ws LANE BRANCH STATE SERVICES CPU MEM URL 0 main running 1/1 0.0% 29.2 MiB https://example-realtime-ws.localhost
UNIT STATE PORT CPU MEM URL realtime ready 20420,20421,20422 0.0% 29.2 MiB https://example-realtime-ws.localhost install exited – – –
$ devlanes url ls | grep example-realtime-wsexample-realtime-ws.localhost -> example-realtime-ws@0:realtime 20421 readyws.example-realtime-ws.localhost -> example-realtime-ws@0:realtime 20422 readyadmin.example-realtime-ws.localhost -> example-realtime-ws@0:realtime 20420 readyurl ls lists the hostnames of every project on the machine, hence the grep. Your port numbers will differ.
Try next
Section titled “Try next”On Windows, add --ssl-revoke-best-effort to the curl commands.
curl -N https://example-realtime-ws.localhost/eventsprints a tick every second as it happens, such asdata: {"lane":0,"tick":7,"time":"2026-11-07T01:07:20.376Z"}.- With a curl that lists
ws wssunder Protocols incurl --version,curl -s --max-time 2 wss://ws.example-realtime-ws.localhostprints the hello frame:{"type":"hello","lane":0,"lane_name":"main","via":"ws.example-realtime-ws.localhost","port_name":"ws","port":20422}. - Send a message from the terminal while the page is open:
devlanes exec --name chat -- npm run chat -- hello from the terminal. The page showslane 0 via ws.example-realtime-ws.localhost, port ws: hello from the terminal, anddevlanes logs chatprints the same echo aslane 0 (main) via ws.example-realtime-ws.localhost, port ws: hello from the terminal. - Start a second lane:
git worktree add ../examples-checkout -b feat/checkout, thencd ../examples-checkout/web-realtime-ws && devlanes start. Open https://example-realtime-ws1.localhost and send a message there: it shows up taggedlane 1and never reaches lane 0’s page, because each lane runs its own process on its own ports. - Without a second worktree,
devlanes lane new --name example-realtime-ws-review --startin this folder gives the same lane 1, anddevlanes exec --lane example-realtime-ws-review --name chat -- npm run chat -- hitalks to it. - Freeze the lane with the page open:
devlanes debug freeze.devlanes statusshowsrunning frozen 8sfor the lane andfrozenforrealtime, and the page’s SSE card counts up11s ago, no tick since. - Type a message in the frozen page and send it: the bytes on the open WebSocket count as activity, so the proxy thaws the lane, the echo comes back and the ticks resume.
devlanes debug eventslistslane.thawed example-realtime-ws@0 from frozen by a request. - Open https://admin.example-realtime-ws.localhost after the freeze:
connectionscounts the page’s SSE stream and its two sockets, andsse_tickstrailsuptime_sby about the time the lane spent frozen. devlanes lane clean 0 --yesstops lane 0 and deletes its data and logs. Run it with1for the second worktree’s lane, orexample-realtime-ws-reviewfor the extra lane of this folder.
devlanes.yaml: therealtimeservice with its named ports and three hostnames, and theinstalltask.src/index.ts: starts the three servers, the main port last.src/servers/: one module per port (main.ts,ws.ts,admin.ts), each mounting its routes.src/routes/:/eventswithstreamSSE, the chat upgrade with itsOrigincheck, the admin view and the page.src/client/: the page’sEventSourceand WebSocket code, built byvite.config.ts.src/scripts/chat.ts: sends one chat message from the terminal and prints the echo.