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.
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`);
})();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 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.
This project is the Node.js wrapper for the ngrok client. Version 5 of this project uses ngrok client version 3. For ngrok client version 2, check out version 4.
Install the package with npm:
npm install ngrok
Then use ngrok.connect() to start ngrok and open a tunnel.
const ngrok = require('ngrok');
(async function() {
const url = await ngrok.connect();
})();
This module uses node>=10.19.0 with async/await. For a callback-based version use 2.3.0.
npm install ngrok -g
ngrok http 8080
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.
You can create basic http-https-tcp tunnel without an authtoken. For custom subdomains and more you should obtain an authtoken by signing up at ngrok.com. Once you set the authtoken, it is stored in ngrok config and used for all tunnels. You can set the authtoken directly:
await ngrok.authtoken(token);
Or pass the authtoken to the connect method like so:
await ngrok.connect({authtoken: token, ...});
There are a number of ways to create a tunnel with ngrok using the connect method.
By default, connect will open an HTTP tunnel to port 80
const url = await ngrok.connect(); // https://757c1652.ngrok.io -> http://localhost:80
You can pass the port number to connect to specify that port:
const url = await ngrok.connect(9090); // https://757c1652.ngrok.io -> http://localhost:9090
Or you can pass an object of options, for example:
const url = await ngrok.connect({proto: 'tcp', addr: 22}); // tcp://0.tcp.ngrok.io:48590
const url = await ngrok.connect(opts);
There are many options that you can pass to connect, here are some examples:
const url = await ngrok.connect({
proto: 'http', // http|tcp|tls, defaults to http
addr: 8080, // port or network address, defaults to 80
basic_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, sa, jp, in), defaults to us
configPath: '~/git/project/ngrok.yml', // custom path for ngrok config file
binPath: path => path.replace('app.asar', 'app.asar.unpacked'), // custom binary path, eg for prod in electron
onStatusChange: status => {}, // 'closed' - connection is lost, 'connected' - reconnected
onLogEvent: data => {}, // returns stdout messages from ngrok process
});
See the ngrok documentation for all of the tunnel definition options including: name, inspect, host_header, scheme, hostname, crt, key, remote_addr.
Note on regions:
The ngrok process and all tunnels will be killed when node process is complete. To stop the tunnels manually use:
await ngrok.disconnect(url); // stops one
await ngrok.disconnect(); // stops all
await ngrok.kill(); // kills ngrok process
You can use ngrok's configurations files, and pass name option when making a tunnel. Configuration files allow to store tunnel options. Ngrok looks for them here:
| System | Path |
|---|---|
| MacOS (Darwin) | "~/Library/Application Support/ngrok/ngrok.yml" |
| Linux | "~/.config/ngrok/ngrok.yml" |
| Windows | "%HOMEPATH%\AppData\Local\ngrok\ngrok.yml" |
You can specify a custom configPath when making a tunnel.
With the upgrade to ngrok version 3, an older config file will no longer be compatible without a few changes. The ngrok agent provides a command to upgrade your config. On the command line you can run:
ngrok config upgrade
The default locations of the config file have changed too, you can upgrade and move your config file with the command:
ngrok config upgrade --relocate
The library makes this command available as well. To get the same effect you can run:
await ngrok.upgradeConfig();
// relocate the config file too:
await ngrok.upgradeConfig({ relocate: true });
When a tunnel is established you can use the ngrok interface hosted at http://127.0.0.1:4040 to inspect the webhooks made via ngrok.
The same URL hosts the internal client api. This package exposes an API client that wraps the API which you can use to manage tunnels yourself.
const url = await ngrok.connect();
const api = ngrok.getApi();
const tunnels = await api.listTunnels();
You can also get the URL of the internal API:
const url = await ngrok.connect();
const apiUrl = ngrok.getUrl();
The API wrapper gives access to all the ngrok client API methods:
const url = await ngrok.connect();
const api = ngrok.getApi();
const tunnels = await api.listTunnels();
const tunnel = await api.startTunnel(opts);
const tunnel = await api.tunnelDetail(tunnelName);
await api.stopTunnel(tunnelName);
await api.listRequests(options);
await api.replayRequest(requestId, tunnelName);
await api.deleteAllRequests();
const request = await api.requestDetail(requestId);
HTTPS_PROXY env var to fix it. ngrok's postinstall scripts uses the got module to fetch the binary and the hpagent module to support HTTPS proxies. You will need to install the hpagent module as a dependencyNGROK_ROOT_CA_PATH. The path is needed for downloading the ngrok binary in the postinstall scriptnpm install downloads the ngrok binary for your platform from the official ngrok hosting. To host binaries yourself set the NGROK_CDN_URL environment variable before installing ngrok. To force specific platform set NGROK_ARCH, eg NGROK_ARCH=freebsdia32.
The first time you create a tunnel the ngrok process is spawned and runs until you disconnect or when the parent process is killed. All further tunnels are connected or disconnected through the internal ngrok API which usually runs on http://127.0.0.1:4040.
If you would like to force an update of the ngrok binary directly from your software, you can require the ngrok/download module and call the downloadNgrok function directly:
const downloadNgrok = require('ngrok/download');
downloadNgrok(myCallbackFunc, { ignoreCache: true });
If you want your application to restart as you make changes to it, you may use nodemon. This blog post shows how to use nodemon and ngrok together so your server restarts but your tunnel doesn't.
Please run git update-index --assume-unchanged bin/ngrok to not override ngrok stub in your PR. Unfortunately it can't be gitignored.
The test suite covers the basic usage without an authtoken, as well as features available for free and paid authtokens. You can supply your own tokens as environment variables, otherwise a warning is given and some specs are ignored (locally and in PR builds). GitHub Actions supplies real tokens to master branch and runs all specs always.
Please read the upgrade notes for the ngrok agent. Library specific changes are described below and there is more in the CHANGELOG:
The format and default location of the config file has changed. Please see the section on upgrading your config file for more detail.
The bind_tls option is now scheme. When bind_tls was true (the default), ngrok agent version 2 would start two tunnels, one on http and one on https. Now, when scheme is set to https (the default), only an https tunnel will be created. To create both tunnels, you will need to pass ["http", "https"] as the scheme option.
The auth option, also available as httpauth, is now just basic_auth. Note also that the password for basic_auth must be between 8 and 128 characters long.
The main impetus to update the package was to remove the dependency on the deprecated request module. request was replaced with got. Calls to the main ngrok functions, connect, authtoken, disconnect, kill, getVersion and getUrl respond the same as in version 3.
Updating the HTTP library, meant that the wrapped API would change, so a client class was created with methods for the available API calls. See the documentation above for how to use the API client.
The upside is that you no longer have to know the path to the API method you need. For example, to list the active tunnels in version 3 you would do:
const api = ngrok.getApi();
const tunnels = await api.get('api/tunnels');
Now you can call the listTunnels function:
const api = ngrok.getApi();
const tunnels = await api.listTunnels();
From version 3 to version 4 the bundled types were also overhauled. Most types live within the Ngrok namespace, particularly Ngrok.Options which replaces INgrokOptions.
FAQs
node wrapper for ngrok
The npm package ngrok receives a total of 118,875 weekly downloads. As such, ngrok popularity was classified as popular.
We found that ngrok demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.