Skip to content


Repository files navigation


Tunnel HTTP connections via streams. Inspired by localtunnel.

Blog Post

Read all about it

Npm install

Normal install as develop dependency.

npm install git+

Global install (recommended)

npm install -g git+

How to use?

socket-tunnel --server --subdomain YOURSUBDOMAIN --hostname --port 8000 #

Server Usage

  1. Clone this repo and cd into it
  2. docker build -t socket-tunnel .
  3. docker run -d -p 80:3000 --restart=always --name st-server socket-tunnel
  4. Get a domain name (i.e.
  5. Point your domain name's root A record at your server's IP
  6. Point a wildcard (*) A record at your server's IP

Client CLI Usage

  1. Start your http server that you'd like to expose to the public web (in this example we'll assume it's listening on
  2. Clone this repo and cd into it
  3. npm i
  4. node bin/client --server --subdomain YOURSUBDOMAIN --hostname --port 8000
  5. Browse to to see your local service available on the public internet

Client API Usage

Assuming a web server running on

  1. Clone this repo into your project
  2. npm i
  3. In your project file, require the socket-tunnel api and call connect():
const socketTunnel = require('./socket-tunnel/lib/api');

socketTunnel.connect('', 'YOURSUBDOMAIN', '8000')
  1. Browse to to see your local service available on the public internet

Client API Parameters

socketTunnel.connect(remoteServer, desiredSubdomain, localPort, localHostname) returns a promise which resolves to the requested URL/subdomain.

Property Default Description
remoteServer n/a IP address or hostname of the socket-tunnel server
desiredSubdomain n/a Subdomain to request for this client
localPort n/a Local port to tunnel to
localHostname '' Local host to tunnel to


Created by Eric Barch. Additional code provided by these generous contributors.


This project is licensed under the MIT License - see the LICENSE file for details


Tunnel HTTP Connections via streams.







No releases published


No packages published

Contributors 4