search

robbie-cahill / tunnelmole-client

Tunnelmole - Connect to local servers from anywhere
MIT License
1.27k stars 80 forks source link

readme

Tunnelmole

Tunnelmole

Tunnelmole is a simple tool to give your locally running HTTP(s) servers a public URL. For example, you could get a public URL for

So, you could have your application running locally on port 8080, then by running tmole 8080 you could have a URL such as https://df34.tunnelmole.net routing to your locally running application.

Quick Demo

Getting a Public URL for the Tunnelmole Website, which is running locally Tunnelmole Example

Tunnelmole has been compared to a similar tool known as ngrok, but is open source.

If you are using the default configuration you will get a HTTPs URL for free.

Heres what you could do with your new public URL

Installation

There are a couple of ways to install Tunnelmole.

If you have NodeJS 16.10 or later, you can install Tunnelmole by running

sudo npm install -g tunnelmole

Alternatively you can install the latest precompiled binary for your platform. This has the right version of Node built in. You don't need any specific version of Node installed for this approach

Linux, Mac and Windows Subsystem for Linux

Copy and paste the following into a terminal:

curl -O https://install.tunnelmole.com/xD345/install && sudo bash install

The script will detect your OS and install the right version.

Windows

  1. Download tmole.exe
  2. Put it somewhere in your PATH.

I'd like to have the install script for Linux and Mac also working in Cygwin and Mingw. Let me know if you're willing to help test!.

Install with NPM

To install Tunnelmole with NPM you need to have NodeJS installed. If not, get it from (https://nodejs.org/).

npm install -g tunnelmole

Using Tunnelmole

Here's what it should look like

$ tmole 8080
http://evgtkh-ip-49-145-166-122.tunnelmole.net is forwarding to localhost:8080
https://evgtkh-ip-49-145-166-122.tunnelmole.net is forwarding to localhost:8080

Now, just go to either one of the URLs shown with your web browser.

You can also use another device, for example try hitting one of the URLs with your phones browser or a different computer.

The URLs are public - this means you can also share them with collaborators and others over the internet.

Custom subdomain

Sometimes, it can be useful to have a domain that does not change frequently. To use a custom subdoman run tmole 8080 as <yourdomain>.tunnelmole.net.

If you are using the hosted service (which is the default) and you want to use a custom subdomain you'll need to purchase a subscription Learn More.

Otherwise, you can self host. To learn more go to the Tunnelmole Service GitHub repo.

Integrating with NodeJS and TypeScript projects with NPM

Tunnelmole is available as an NPM dependency for integration with NodeJS and TypeScript projects.

Install as an npm dependency

To integrate tunnelmole with your project you first need to install it as an NPM dependency.

npm install --save tunnelmole

Starting tunnelmole using code

First import tunnelmole. Both ES and CommonJS modules are supported.

Importing tunnelmole as an ES module

import { tunnelmole } from 'tunnelmole';

Importing tunnelmole as a CommonJS module

const tunnelmole = require('tunnelmole/cjs');

Once the module is imported you can start tunnelmole with the code below, changing port 3000 to the port your application listens on if it is different.

const url = tunnelmole({
    port: 3000
});
// url = https://idsq6j-ip-157-211-195-169.tunnelmole.net

Tunnelmole will start in the background and you'll see output in the console log similar to the Tunnelmole command line application which will include the public URLs that now point to your application. The function is async and won't block execution of the rest of your code.

If you want to use a custom subdomain, you could also pass the domain as an option.

const url = tunnelmole({
    port: 3000,
    domain: '<your tunnelmole domain e.g. mysite.tunnelmole.net>'
});
// url = mydomain.tunnelmole.net

Again if you are using the hosted service (which is the default) and you want to use a custom subdomain you'll need to purchase a subscription Learn More.

Otherwise, you can self host. To learn more about this option go to the Tunnelmole Service GitHub repo.

Suppress output/logs

To suppress the initial output with the URLs, set the environment variable TUNNELMOLE_QUIET_MODE=1 somewhere in your environment. This might be useful in a CI/CD environment or in other scripts.

Using Tunnelmole with NPM scripts

Installing Tunnelmole as an NPM dependency will make the following executables available in your project:

node_modules/.bin/tmole
node_modules/.bin/tunnelmole

They both work identically to the Tunnelmole command line application.

You can run them manually in the same way as the command line application (for example node node_modules/.bin/tmole 3000), but its far more convenient to integrate them with NPM scripts in package.json. This way, you can automate starting your application and generating a public URL with a single command. For example:

{
    "name": "myapp",
    "version": "0.0.1",
    "scripts": {
        "start": "dist/index.js",
        "start-public": "npm run start && tmole 3000"
    }
}

In this example, npm run start-public will simultaneously start your application and get tunnelmole to generate public URLs tunneling to port 3000. Replace port 3000 with the port your application listens on if it is different. You will see the public URLs in the command line output.

This allows you to start your application and get a public URL with a single command, instead of needing to run two commands in separate terminals.

Building from source

Prerequisites

Install the dependencies with npm

Run npm install

Copy the example config

cp config-instance.example.ts config-instance.ts

The default settings are fine unless you want to self host your own tunnelmole service, in which case you'll need to modify the config to point to your server.

Start Tunnelmole

To start Tunnelmole, run npm start.

This does a few things for you automatically:

Alternatively you can invoke Tunnelmole manually with node dist/bin/tunnelmole.js <port number to forward to> after compiling the code with npm run build.

Debugging

This project has sourcemaps enabled, so you can set breakpoints in the TypeScript .ts files and they should behave normally.

If Tunnelmole crashes and you get a Stack Trace it will refer to the TypeScript files and line numbers which should make tracking down problematic code easier.

To set up debugging for Visual Studio Code, copy over the example config.

cp .vscode/launch.json.example .vscode/launch.json

Once this is done, run "Launch Tunnelmole" from the Run and Debug menu.

While debugging, hot reload is not supported as you'd loose your debug connection each time Tunnelmole restarts. So for every change, you will need to recompile the code (i.e. with npm run build) and then restart the debugger.

You can optionally run npm run watch to automatically recompile code as you make changes.

By default, Launch Tunnelmole invokes Tunnelmole to forward to port 8001 locally. You can change this by changing the port in the .vscode/launch.json config under the "args" section.

How it works

How Tunnelmole Works

Tunnelmole sets up a persistent Websocket connection between your device and a host machine running the tunnelmole service. By default, this is the hosted tunnlemole service at https://tunnelmole.com but you can self host.

As requests come in to the public URL, these requests are sent back through the Websocket connection to the client running on your machine.

The client then forwards on the request to your locally running web server.

Responses are handled in reverse. Your client forwards them to the Tunnelmole service, which then serves them up at the public URL.

Telemetry

To help improve the developer experience of Tunnelmole, some anonymized Telemetry data is collected by default.

For example

To disable the telemetery, add the variable TUNNELMOLE_TELEMETRY=0 to your environment.

On Linux and Mac, to opt out for a single run of Tunnelmole you could put this in front of the tmole command, for example

TUNNELMOLE_TELEMETRY=0 tmole 80

To opt out by default:

Contributing

There is no big company behind Tunnelmole and currently there is only one maintainer so any help is greatly appreciated!.

If you'd like a bug fixed or missing feature added, the fastest way to make that happen is to implement the changes yourself.

This repo has a few features to help with your developer experience including sample debugging configuration and hot reload.

Here are some different ways you can help

For any code changes, you will need to fork this repo and submit a PR. If you've never done this before, GitHub has a very good guide here.

FAQs

Is Tunnelmole fully open source?

Both the Tunnelmole client and server are fully open source.

You are free to self host or use our hosted service.

We welcome issue reports and PRs from the community.

Feel free to look over the code and see exactly what Tunnelmole is doing before running it.

The Tunnelmole client is licensed under the MIT license. The service is licensed under the Gnu Affero General Public License, version 3.

Does Tunnemole hide my IP?

In the past the Tunnelmole service did hide IP addresses. Unfortunately this encouraged bad actors to use the service. They would tunnel phishing sites through the service, then the abuse reports would get sent to my hosting provider instead of theirs.

Because of this, Tunnelmole now adds an X-Forwarded-For header with your IP in every response. So you can't use the Tunnelmole hosted service to hide your origin server. For the randomly generated URLs your IP is also added to the URL itself.

However, you can always self host Tunnelmole and remove the code that adds this header if you want. This would allow you to hide your origin server. You'll then be responsible for securing your service. The IP of the server you self host on will still be visible.

How can I help

Read the above "Contributing" section to learn how to contribute.

Links and resources

Uninstallation