# Does OmniRoute Support WebSocket Routing? Full Implementation Breakdown

> Explore OmniRoute WebSocket routing capabilities. Discover how it powers live dashboards, chat endpoints, and response bridging. Full implementation details inside.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-17

---

**Yes. OmniRoute includes a full-featured WebSocket routing layer that powers the live-dashboard event stream, the OpenAI-compatible chat WebSocket endpoint, and the Responses-over-WebSocket bridge.**

OmniRoute is an open-source routing platform that integrates **WebSocket routing** directly into its core architecture. The implementation spans authentication handshakes, live event broadcasting, and LLM response streaming across multiple server and client modules. According to the diegosouzapw/OmniRoute source code, the system handles upgrades, path resolution, and multi-turn message proxying through dedicated TypeScript files.

## How the WebSocket Handshake Works

In [`src/app/api/v1/ws/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/ws/route.ts), the API route processes incoming GET requests for WebSocket negotiation. A standard request triggers an upgrade handshake, and if the client cannot upgrade, the server returns a **426 Upgrade Required** response. When the caller includes the `handshake=1` query parameter, the route returns JSON containing the connection path, authentication tokens, and protocol details required to establish the persistent socket.

### API Route and Upgrade Handling

The entry point for all **WebSocket routing** traffic is [`src/app/api/v1/ws/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/ws/route.ts). This Next.js API route manages CORS headers and determines whether to proceed with the HTTP upgrade or return connection metadata. It serves as the gateway for both the live-dashboard daemon and the chat bridge endpoints.

### Authentication and Token Generation

The [`src/lib/ws/handshake.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/ws/handshake.ts) module authorizes every handshake request before any socket is allocated. It validates API-key or credential-based authentication, then populates the `wsAuth` token and `wsPath` fields that the client consumes to open the final WebSocket connection. This design keeps authentication logic decoupled from the persistent server daemons.

## WebSocket Server Architecture

### Live Dashboard Daemon

The actual event broadcasting server runs inside [`src/server/ws/liveServer.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/ws/liveServer.ts). This daemon pushes live-dashboard telemetry to connected clients and enforces network policies through [`src/server/ws/liveServerAllowList.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/ws/liveServerAllowList.ts), which maintains an explicit allow-list of permitted client IPs. Together these files provide both real-time streaming and perimeter security for the **WebSocket routing** layer.

### Path Resolution Logic

Before a client connects, [`src/shared/utils/wsPath.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/wsPath.ts) derives the public WebSocket pathname—defaulting to `/live-ws`—from the `NEXT_PUBLIC_LIVE_WS_PUBLIC_URL` environment variable. This utility centralizes path handling so that both the handshake API and the live server reference a single source of truth for route configuration.

## Client Implementation Examples

### Connecting to the Live Dashboard

The following client-side JavaScript performs the handshake and then opens an authenticated WebSocket to the live-dashboard daemon:

```js
// Example: Open a WebSocket connection to the live‑dashboard daemon
const ws = new WebSocket('ws://localhost:20132/live-ws?handshake=1');

// First, perform the handshake to obtain auth details
ws.addEventListener('open', async () => {
  const handshakeResp = await fetch(
    `${location.origin}/api/v1/ws?handshake=1`,
    { headers: { 'Authorization': `Bearer ${API_KEY}` } }
  );
  const { wsAuth, path, protocol } = await handshakeResp.json();

  // Attach auth token as a query param (or header, depending on server config)
  const wsUrl = `ws://localhost:20132${path}?auth=${wsAuth}`;
  const wsConn = new WebSocket(wsUrl);

  // Send a request adhering to the protocol defined in the handshake
  wsConn.addEventListener('open', () => {
    wsConn.send(JSON.stringify({
      type: 'request',
      id: 'req-1',
      payload: { model: 'openai/gpt-4', messages: [] }
    }));
  });

  // Listen for responses
  wsConn.addEventListener('message', ev => {
    const msg = JSON.parse(ev.data);
    console.log('Received:', msg);
  });
});

```

### Using the Responses-over-WebSocket Bridge

For LLM inference streaming, clients can use the Responses-over-WebSocket bridge. The example below uses the `ws` library to send JSON-RPC-like requests and receive streamed tokens:

```ts
// Example: Use the Responses‑over‑WebSocket bridge (client side)
import { WebSocket } from 'ws';

async function startResponsesWs() {
  const respWs = new WebSocket('ws://localhost:20132/api/v1/responses?api_key=local-token');

  respWs.on('open', () => {
    // Send a `response.create` request (JSON‑RPC‑like)
    respWs.send(JSON.stringify({
      method: 'response.create',
      id: 'r1',
      params: { model: 'openai/gpt-4', messages: [{ role: 'user', content: 'Hello' }] }
    }));
  });

  respWs.on('message', data => {
    const msg = JSON.parse(data.toString());
    console.log('Response:', msg);
  });
}

```

## Testing and Validation

OmniRoute validates its **WebSocket routing** layer through dedicated unit tests. The file [`tests/unit/v1-ws-bridge.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/v1-ws-bridge.test.ts) confirms that the `/api/v1/ws` endpoint performs proper upgrade handling and handshake authentication. Additional suites such as `tests/unit/responses-ws-proxy-*.test.ts` verify multi-turn history logging and compression parity for the Responses-over-WebSocket proxy.

## OpenAPI Documentation

Client generators and API explorers can reference [`docs/openapi.yaml`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/openapi.yaml) in the repository. This specification formally documents the `/api/v1/ws` endpoint, including its handshake parameters and expected response schema, making it straightforward to generate typed clients for the **WebSocket routing** interface.

## Summary

- OmniRoute supports **WebSocket routing** through a dedicated handshake API at `/api/v1/ws` implemented in [`src/app/api/v1/ws/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/ws/route.ts).
- Authentication tokens and paths are generated by [`src/lib/ws/handshake.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/ws/handshake.ts) before any persistent connection is established.
- The live-dashboard event stream runs on the daemon in [`src/server/ws/liveServer.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/ws/liveServer.ts), protected by [`src/server/ws/liveServerAllowList.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/ws/liveServerAllowList.ts).
- Path resolution is centralized in [`src/shared/utils/wsPath.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/wsPath.ts), which derives routes from the `NEXT_PUBLIC_LIVE_WS_PUBLIC_URL` environment variable.
- Client code can connect to the live dashboard or use the Responses-over-WebSocket bridge for streaming LLM responses.
- Comprehensive unit tests in [`tests/unit/v1-ws-bridge.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/v1-ws-bridge.test.ts) and `tests/unit/responses-ws-proxy-*.test.ts` validate upgrade flows and message proxying.

## Frequently Asked Questions

### Does OmniRoute support WebSocket routing natively?

Yes. As implemented in diegosouzapw/OmniRoute, the framework includes native **WebSocket routing** across multiple subsystems. The [`src/app/api/v1/ws/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/ws/route.ts) file handles HTTP upgrades, while [`src/server/ws/liveServer.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/ws/liveServer.ts) maintains the persistent event socket.

### How does OmniRoute authenticate WebSocket connections?

The [`src/lib/ws/handshake.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/ws/handshake.ts) module validates API keys or credentials during the initial HTTP handshake. Upon success, it returns a `wsAuth` token and a `wsPath` that the client uses to open the final authenticated WebSocket connection.

### Which OmniRoute features rely on WebSocket routing?

The live-dashboard telemetry stream, the OpenAI-compatible chat endpoint, and the Responses-over-WebSocket bridge all depend on the same core **WebSocket routing** layer. Each feature uses the shared handshake and path utilities but targets different runtime daemons or API routes.

### Is the OmniRoute WebSocket API documented for client generation?

Yes. The repository includes [`docs/openapi.yaml`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/openapi.yaml), which formally specifies the `/api/v1/ws` endpoint. This allows OpenAPI client generators to produce typed interfaces for the handshake and connection logic automatically.