Skip to content

devlanes is in beta and not ready for production use.Report an issue

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.

  • devlanes, with devlanes setup run once
  • Node 22 or later
Terminal window
cd web-realtime-ws
devlanes start

devlanes start --no-ui prints the start as text:

example-realtime-ws@0 (main): 1/1 ready
ready realtime http://127.0.0.1:20421 https://example-realtime-ws.localhost

Open 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.

  1. The first start of a lane runs the install task (npm install), because a new worktree has no node_modules.
  2. The realtime service’s env mentions self.ports.ws and self.ports.admin, so devlanes gives it two more ports next to PORT, with the same offsets in every lane.
  3. It runs npm run dev, which builds the page’s browser code from src/client/ into dist/client with Vite, then runs tsx watch src/index.ts. Server edits restart the server; after a client edit, devlanes restart realtime rebuilds it.
  4. The server opens the ws and admin ports first and the main port last, so the http ready check on /healthz passes once all three listen.
HostnamePortServes
example-realtime-ws.localhostmain (PORT)the page, SSE on /events, a WebSocket on /ws, /lane, /healthz
ws.example-realtime-ws.localhostws (WS_PORT)the chat’s WebSocket, on any path
admin.example-realtime-ws.localhostadmin (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 status
example-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-ws
example-realtime-ws.localhost -> example-realtime-ws@0:realtime 20421 ready
ws.example-realtime-ws.localhost -> example-realtime-ws@0:realtime 20422 ready
admin.example-realtime-ws.localhost -> example-realtime-ws@0:realtime 20420 ready

url ls lists the hostnames of every project on the machine, hence the grep. Your port numbers will differ.

On Windows, add --ssl-revoke-best-effort to the curl commands.

  • curl -N https://example-realtime-ws.localhost/events prints a tick every second as it happens, such as data: {"lane":0,"tick":7,"time":"2026-11-07T01:07:20.376Z"}.
  • With a curl that lists ws wss under Protocols in curl --version, curl -s --max-time 2 wss://ws.example-realtime-ws.localhost prints 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 shows lane 0 via ws.example-realtime-ws.localhost, port ws: hello from the terminal, and devlanes logs chat prints the same echo as lane 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, then cd ../examples-checkout/web-realtime-ws && devlanes start. Open https://example-realtime-ws1.localhost and send a message there: it shows up tagged lane 1 and 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 --start in this folder gives the same lane 1, and devlanes exec --lane example-realtime-ws-review --name chat -- npm run chat -- hi talks to it.
  • Freeze the lane with the page open: devlanes debug freeze. devlanes status shows running frozen 8s for the lane and frozen for realtime, and the page’s SSE card counts up 11s 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 events lists lane.thawed example-realtime-ws@0 from frozen by a request.
  • Open https://admin.example-realtime-ws.localhost after the freeze: connections counts the page’s SSE stream and its two sockets, and sse_ticks trails uptime_s by about the time the lane spent frozen.
  • devlanes lane clean 0 --yes stops lane 0 and deletes its data and logs. Run it with 1 for the second worktree’s lane, or example-realtime-ws-review for the extra lane of this folder.
  • devlanes.yaml: the realtime service with its named ports and three hostnames, and the install task.
  • 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/: /events with streamSSE, the chat upgrade with its Origin check, the admin view and the page.
  • src/client/: the page’s EventSource and WebSocket code, built by vite.config.ts.
  • src/scripts/chat.ts: sends one chat message from the terminal and prints the echo.