✨ hypertunnel

When localtunnel/ngrok is not enough.

This free TCP relay/reverse proxy service can be used to expose any TCP/IP service running behind a NAT. It's using hypertunnel-tcp-relay under the hood, which itself is based on the excellent node-tcp-relay from tewarid, adding self-service multi-client support similar to localtunnel, a cool project name with "hyper" in it and a free public server.

Installation

# Use directly with no installation (npx is part of npm):
❯❯❯ npx hypertunnel --port 8080

# Or install globally:
❯❯❯ npm install -g hypertunnel

Usage

❯❯❯ hypertunnel --help

  Usage: hypertunnel --port 8080 [options]

  Expose any local TCP/IP service on the internet.

  Options:

    -v, --version                output the version number
    -p, --port [port]            local TCP/IP service port to tunnel
    -l, --localhost [localhost]  local server (default: localhost)
    -s, --server [server]        hypertunnel server to use (default: https://hypertunnel.ga)
    -t, --token [token]          token required by the server (default: free-server-please-be-nice)
    -i, --internet-port [port]   the desired internet port on the public server
    --ssl                        enable SSL termination (https://) on the public server    
    -h, --help                   output usage information

Examples ^{_{(click to expand)}}

❯❯❯ npx http-server -p 7777

❯❯❯ npx hypertunnel -p 7777

  ✨ Hypertunnel created.

  Tunneling hypertunnel.ga:19432 > localhost:7777

❯❯❯ npx hypertunnel@latest -p 7777 --ssl

  ✨ Hypertunnel created.

  Tunneling https://hypertunnel.ga:26949 > localhost:7777

❯❯❯ (npx http-server -p 7777 & npx hypertunnel --port 7777 --ssl)

# Create a tunnel for the local SSH service running on port 22
❯❯❯ npx hypertunnel --port 22

# Example, adjust the port based on the previous output:
❯❯❯ ssh hypertunnel.ga -p 21357

Warning: Permanently added 'hypertunnel.ga:21357' (ECDSA) to the list of known hosts.
Password:

❯❯❯ npx netchat server -p 3000

❯❯❯ npx hypertunnel -p 3000

❯❯❯ telnet hypertunnel.ga 31967

Trying 159.69.23.189...
Connected to hypertunnel.ga.
Escape character is '^]'.
bob
Welcome, ::ffff:127.0.0.1:56252
Type "quit" to exit.

Enter username: You are now bob
> hello world
> _

Comparison to localtunnel/ngrok

Both are great services! If your use-case is to simply tunnel local http web server traffic I suggest using them. :-)

I ran into issues when trying to expose a local proxy server (to use the client as forwarding proxy). Both services need to inspect and rewrite HTTP headers for routing, so using the tunnel as a proxy in e.g. Chrome won't work. There are a couple other use-cases where raw TCP stream tunnelling is desired and hypertunnel is the only available option.

Technical differences

Instead of using hostnames to direct traffic to clients, hypertunnel is using a dedicated public port per tunnel. This greatly simplifies things as TCP/IP traffic can be routed based on the assigned port, without http header inspection and rewriting.

Free server: hypertunnel.ga

I really like the simplicity of services like localtunnel & ngrok as they're generously offering a free server. I'm doing the same for hypertunnel but beware of using this free server in mission critical settings. If you'd like to offer sponsorship for the public server feel cheered at and please raise a ticket. :-)

PS: You can also self-host a private hypertunnel-server and point the client to it.

Limits

There are currently no enforced usage limits, in the hopes that you will use the server in good faith. Tunnels are destroyed when you exit the client and latest after 24 hours of creation.

Status

It's doing what it says on the tin. Certain things could be improved and battle-hardened. It works for my current use-case so please raise an issue if you encounter problems.

The CLI interface is stable, but programmatic usage comes with no warranty as internals might change in the future (the internals are also not properly documented currently).

Have a look at the tests to get an idea of how to use hypertunnel programmatically.

Given that there is no alternative to hypertunnel I figured I'd rather release it early. :-)

Contributing

Contributions are welcome.

We use a monorepo powered by Lerna (and yarn workspaces), ava for testing and the standard style for linting.

# Make sure you have a recent version of yarn & lerna installed:
npm install -g yarn lerna

# Bootstrap the packages in the current Lerna repo. 
# Installs all of their dependencies and links any cross-dependencies.
yarn bootstrap

# Install debug in all packages
lerna add debug

# Install debug in all packages as dev dependency
lerna add --dev debug

# Install fs-extra to hypertunnel-server
lerna add fs-extra --scope=hypertunnel-server

# Remove dependency
# https://github.com/lerna/lerna/issues/833
lerna exec -- yarn remove fs-extra

# Run test in all packages
yarn test

Todo

server & client

• Hook into hypertunnel-tcp-relay events for better cleanup, error reporting and to show established connections
• Support environment variables next to cli params

client

• Support --basic-auth flag as a simple way to secure a local http server
• Add --timeout flag, so a tunnel will self-destruct after a specified delay

server

• Use e.g. redis or message passing for tunnel manager data to support clustering
• Battle-hardening (e.g. rate-limits to keep bad actors out) - don't make this a necessity please ಠ_ಠ

Related

• localtunnel
• ngrok
• serveo
• telebit.js

License

MIT