ngrok

What is ngrok?

The ngrok npm package allows you to expose a local server to the internet securely. It is commonly used for testing webhooks, developing APIs, and sharing local websites. Ngrok provides a public URL that tunnels traffic to your local server, making it accessible from anywhere.

What are ngrok's main functionalities?

Expose Local Server

This feature allows you to expose a local server running on port 3000 to the internet. The ngrok.connect method creates a tunnel and returns a public URL.

const ngrok = require('ngrok');
(async function() {
  const url = await ngrok.connect(3000);
  console.log(`Server is publicly accessible at ${url}`);
})();

Custom Subdomains

This feature allows you to specify a custom subdomain for your public URL. This is useful for branding or easier access.

const ngrok = require('ngrok');
(async function() {
  const url = await ngrok.connect({ addr: 3000, subdomain: 'mycustomsubdomain' });
  console.log(`Server is publicly accessible at ${url}`);
})();

Secure Tunnels

This feature allows you to create secure HTTPS tunnels to your local server, ensuring that the data transmitted is encrypted.

const ngrok = require('ngrok');
(async function() {
  const url = await ngrok.connect({ addr: 3000, proto: 'https' });
  console.log(`Server is securely accessible at ${url}`);
})();

Inspect Traffic

Ngrok provides a web interface to inspect the traffic going through your tunnels. This is useful for debugging and monitoring.

const ngrok = require('ngrok');
(async function() {
  const url = await ngrok.connect(3000);
  console.log(`Server is publicly accessible at ${url}`);
  console.log(`Inspect traffic at http://127.0.0.1:4040`);
})();

Other packages similar to ngrok

localtunnel

Localtunnel allows you to easily share a local server with the world. It provides a public URL that tunnels traffic to your local server. Compared to ngrok, Localtunnel is simpler and has fewer features but is easier to set up.

serveo

Serveo is another tool for exposing local servers to the internet. It uses SSH to create tunnels, which can be more secure. Serveo does not require any installation and can be used directly from the command line.

README

ngrok

usage

npm install ngrok
const ngrok = require('ngrok');
(async function() {
  const url = await ngrok.connect();
})();

or

npm install ngrok -g
ngrok http 8080

This module uses node>=8.3.0 with async-await. For callback-based version use 2.3.0

For global install on Linux, you might need to run sudo npm install --unsafe-perm -g ngrok due to the nature of npm postinstall script.

authtoken

You can create basic http-https-tcp tunnel without authtoken. For custom subdomains and more you should obtain authtoken by signing up at ngrok.com. Once you set it, it's stored in ngrok config and used for all tunnels. Few ways:

await ngrok.authtoken(token);
await ngrok.connect({authtoken: token, ...});

connect

const url = await ngrok.connect(); // https://757c1652.ngrok.io -> http://localhost:80
const url = await ngrok.connect(9090); // https://757c1652.ngrok.io -> http://localhost:9090
const url = await ngrok.connect({proto: 'tcp', addr: 22}); // tcp://0.tcp.ngrok.io:48590
const url = await ngrok.connect(opts);

options

const url = await ngrok.connect({
	proto: 'http', // http|tcp|tls, defaults to http
	addr: 8080, // port or network address, defaultst to 80
	auth: 'user:pwd', // http basic authentication for tunnel
	subdomain: 'alex', // reserved tunnel name https://alex.ngrok.io
	authtoken: '12345', // your authtoken from ngrok.com
	region: 'us', // one of ngrok regions (us, eu, au, ap), defaults to us
	configPath: '~/git/project/ngrok.yml' // custom path for ngrok config file
	binPath: default => default.replace('/bin', '.unpacked/bin'); // custom binary path, eg for prod in electron
});

Other options: name, inspect, host_header, bind_tls, hostname, crt, key, client_cas, remote_addr - read here

Note on regions: region used in first tunnel will be used for all next tunnels too.

disconnect

The ngrok and all tunnels will be killed when node process is done. To stop the tunnels use

await ngrok.disconnect(url); // stops one
await ngrok.disconnect(); // stops all
await ngrok.kill(); // kills ngrok process

Note on http tunnels: by default bind_tls is true, so whenever you use http proto two tunnels are created - http and https. If you disconnect https tunnel, http tunnel remains open. You might want to close them both by passing http-version url, or simply by disconnecting all in one go ngrok.disconnect().

configs

You can use ngrok's configurations files, and just pass name option when making a tunnel. Configuration files allow to store tunnel options. Ngrok looks for them here:

OS X	/Users/example/.ngrok2/ngrok.yml
Linux	/home/example/.ngrok2/ngrok.yml
Windows	C:\Users\example\.ngrok2\ngrok.yml

You can specify a custom configPath when making a tunnel.

inspector

When tunnel is established you can use the ngrok interface http://127.0.0.1:4040 to inspect the webhooks done via ngrok. Same url hosts internal client api. You can get it as wrapped request and manage tunnels yourself.

const url = await ngrok.connect();
const api = ngrok.getApi();
const tunnels = await api.get('api/tunnels');

proxy

If you are behind a corporate proxy an have issues installing ngrok, you can set HTTP_PROXY or HTTPS_PROXY env var to fix it. Ngrok's posinstall uses request module to fetch the binary, and request supports these env vars

how it works

npm install downloads ngrok binary for your platform from official ngrok hosting. To host binaries yourself set NGROK_CDN_URL env var before installing ngrok. To force specific platform set NGROK_ARCH, eg NGROK_ARCH=freebsdia32

First time you create tunnel ngrok process is spawned and runs until you disconnect or when parent process killed. All further tunnels are created or stopped by using internal ngrok api which usually runs on http://127.0.0.1:4040

contributors

Please run git update-index --assume-unchanged bin/ngrok to not override ngrok stub in your pr. Unfortunately it can't be gitignored.

Test suite covers basics usage without authtoken, as well as features available for free and paid authtokens. You can supply your own tokens into env vars, otherwise warning given and some specs are ignored (locally and in PR builds). Travis supplies real tokens to master branch and runs all specs always.