Push-button DIY tunnel service. Run on your Raspberry Pi or VPS to create your own secure tunnel to access your devices from anywhere or simply to expose your localhost development to the outside world.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
AJ ONeal 5a395a299a Merge branch 'feat/snapcraft' of mkg20001/telebit-relay.js into master 1 year ago
admin add index.json 1 year ago
bin Show Bad Gateway rather than disconnect when south-end has gone missing. 1 year ago
dist/etc/systemd/system don't assume the use of /etc 1 year ago
examples update example config 1 year ago
installer de-hard-code TELEBIT_RELAY_PATH 1 year ago
lib touch device lastSeen on ws pong 1 year ago
snap feat: Initial snapcraft configuration 1 year ago
snippets fs cleanup 3 years ago
.gitignore feat: Initial snapcraft configuration 1 year ago
.jshintrc treat devices more like devices and less like domains 1 year ago
LICENSE turning into a service, first steps 2 years ago
README.md merge new features 1 year ago
package.json v0.20.0: use proxy-packer v2.x 1 year ago


Telebit Relay

Friends don't let friends localhost™

A server that works in combination with Telebit Remote to allow you to serve http and https from any computer, anywhere through a secure tunnel.

| Sponsored by ppl | Telebit Relay | Telebit Remote |


  • Expose your bits even in the harshest of network environments
    • NAT, Home Routers
    • College Dorms, HOAs
    • Corporate Firewalls, Public libraries, Airports
    • and even Airplanes, yep
  • Automated HTTPS (Free SSL)


Mac & Linux

Open Terminal and run this install script:

curl -fsSL https://get.telebit.cloud/relay | bash

Of course, feel free to inspect the install script before you run it.

This will install Telebit Relay to /opt/telebit-relay and put a symlink to /opt/telebit-relay/bin/telebit-relay in /usr/local/bin/telebit-relay for convenience.

You can customize the installation:

export NODEJS_VER=v10.2
export TELEBIT_RELAY_PATH=/opt/telebit-relay
curl -fsSL https://get.telebit.cloud/relay

That will change the bundled version of node.js is bundled with Telebit Relay and the path to which Telebit Relay installs.

You can get rid of the tos + email and server domain name prompts by providing them right away:

curl -fsSL https://get.telebit.cloud/relay | bash -- jon@example.com telebit-relay.example.com

Windows & Node.js

  1. Install node.js
  2. Open Node.js
  3. Run the command npm install -g telebit-relay

Note: Use node.js v8.x or v10.x

There is a bug in node v9.x that causes telebit-relay to crash.

Manually Install

git clone https://git.coolaj86.com/coolaj86/telebit-relay.js.git telebit-relay

# we're very picky to due to bugs in various versions of v8, v9, and v10
export NODEJS_VER="v10.2.1"

# We can keep everything self-contained
export NPM_CONFIG_PREFIX=/opt/telebit-relay
export NODE_PATH=/opt/telebit-relay/lib/node_modules

curl -fsSL https://bit.ly/node-installer | bash -s -- --no-dev-deps

pushd /opt/telebit-relay
  bin/node bin/npm install
  rsync -a examples/telebit-relay.yml etc/telebit-relay.yml
  rsync -a dist/etc/systemd/system/telebit-relay.service /etc/systemd/system/telebit-relay.service

# IMPORTANT: Season the config file to taste
# IMPORTANT: change your email address and domain
edit /opt/telebit-relay/etc/telebit-relay.yml

adduser --home /opt/telebit-relay --gecos '' --disabled-password telebit >/dev/null 2>&1
sudo chown -R telebit:telebit /opt/telebit-relay/

systemctl daemon-reload
systemctl restart telebit-relay

systemctl status telebit-relay
journalctl -xefu telebit-relay


telebit-relay --config /opt/telebit-relay/etc/telebit-relay.yml



email: 'jon@example.com'       # must be valid (for certificate recovery and security alerts)
agree_tos: true                # agree to the Telebit, Greenlock, and Let's Encrypt TOSes
community_member: true         # receive infrequent relevant but non-critical updates
telemetry: true                # contribute to project telemetric data
secret: ''                     # JWT authorization secret. Generate like so:
                               # node -e "console.log(crypto.randomBytes(16).toString('hex'))"
servernames:                   # hostnames that direct to the Telebit Relay admin console
  - telebit-relay.example.com
  - telebit-relay.example.net
vhost: /srv/www/:hostname      # securely serve local sites from this path (or false)
                               # (uses template string, i.e. /var/www/:hostname/public)
  store: le-store-certbot      # certificate storage plugin
  config_dir: /opt/telebit-relay/etc/acme    # directory for ssl certificates


The bottom line: As with everything in life, there is no such thing as anonymity or absolute security. Only use Telebit Relays that you trust or self-host. :D

Even though the traffic is encrypted end-to-end, you can't just trust any Telebit Relay willy-nilly.

A man-in-the-middle attack is possible using Let's Encrypt since an evil Telebit Relay would be able to complete the http-01 challenges without a problem (since that's where your DNS is pointed when you use the service).

Also, the traffic could still be copied and stored for decryption is some era when quantum computers exist (probably never).


We created this for anyone to use on their own server or VPS, but those generally cost $5 - $20 / month and so it's probably cheaper to purchase data transfer, which is only $1/month for most people.

In keeping with our no lock-in policy, we release a version of the server for anyone to use independently.

TODO show how to do on

* Node WS Tunnel (zero setup)
* Heroku (zero cost)
* Chunk Host (best deal per TB/month)

Useful Tidbits

As a systemd service

./dist/etc/systemd/system/telebit-relay.service should be copied to /etc/systemd/system/telebit-relay.service.

The user and group telebit should be created.

Use privileged ports without sudo

# Linux
sudo setcap 'cap_net_bind_service=+ep' $(which node)


The authentication method is abstract so that it can easily be implemented for various users and use cases.

// bin/telebit-relay.js
state.authenticate()                  // calls either state.extensions.authenticate or state.defaults.authenticate
                                      // which, in turn, calls Server.onAuth()

state.extensions = require('../lib/extensions');
  state: state                        // lib/relay.js in-memory state
, auth: 'xyz.abc.123'                 // arbitrary token, typically a JWT (default handler)

// lib/relay.js
Server.onAuth(state, srv, rawAuth, validatedTokenData);