Expose a local WebSocket server

Reach a WebSocket server on your laptop from anywhere, over a secure wss:// URL.

Before you beginCopy Anchor Link

• Node.js 18 or later
• A Horizon account and the CLI (see Getting started)
• Optional: a reserved subdomain for -s. Reserve one on the Subdomains page.

mkdir ws-demo && cd ws-demo
npm init -y
npm install ws

import { WebSocketServer } from "ws";

const server = new WebSocketServer({ port: 3000 });

server.on("connection", (socket) => {
  socket.on("error", console.error);
  socket.on("message", (data) => {
    console.log("received: %s", data);
    socket.send(`echo: ${data}`);
  });
  socket.send("connected");
});

node server.mjs

hrzn tunnel http://localhost:3000 -s my-app

HORIZON: Tunnel connected
  URL          https://my-app.hrzn.run (reserved)
  Forwarding   http://localhost:3000
  Request log  https://hrzn.run/dashboard/tunnels/my-app

import WebSocket from "ws";

const socket = new WebSocket("wss://my-app.hrzn.run");

socket.on("error", console.error);
socket.on("open", () => socket.send("hello"));
socket.on("message", (data) => {
  console.log("received: %s", data);
});

node client.mjs

Check it worksCopy Anchor Link

The client prints:

received: connected
received: echo: hello

The server prints:

received: hello

In a browser, new WebSocket("wss://my-app.hrzn.run") connects the same way.

TroubleshootingCopy Anchor Link

The connection failsCopy Anchor Link

• Use wss://, not ws://, with the tunnel URL.
• Check that the Horizon terminal is still running. If its last line is Connection lost. Reconnecting…, wait for Reconnected.
• Check that the server runs on the port in the hrzn tunnel command.

Visitors see a Before you continue pageCopy Anchor Link

A browser that opens the tunnel URL as a page sees it once every 7 days per IP address. They select Continue to site. Requests with an x-hrzn-skip-warning header or a non-browser user agent skip it.

The URL changed after a restartCopy Anchor Link

You started the tunnel without -s. Restart with -s my-app. -s needs a subdomain you reserved, see Pricing.

Next stepsCopy Anchor Link

• Stream Server-Sent Events through a tunnel
• Share your local dev site