Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


    ngrok Build Status TypeScript compatible npm npm



    npm install ngrok
    const ngrok = require('ngrok');
    const url = await ngrok.connect();


    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


    You can create basic http-https-tcp tunnel without authtoken. For custom subdomains and more you should obtain authtoken by signing up at 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, ...});


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


    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
        authtoken: '12345', // your authtoken from
        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.


    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().


    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.


    When tunnel is established you can use the ngrok interface 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');

    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


    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.


    npm i ngrok

    Downloadslast 7 days







    last publish


    • avatar