Usage

Expose a local web server to the internet

ngrok lets you expose a locally running web service to the internet. Just tell ngrok which port your web server is running on. Let's try opening port 80 to the internet.

Example: Open port 80 on your local machine to the internet
$ ngrok 80
ngrok

Tunnel Status                 online
Version                       1.3/1.3
Forwarding                    http://3a4bfceb.ngrok.com -> 127.0.0.1:80
Forwarding                    https://3a4bfceb.ngrok.com -> 127.0.0.1:80
Web Interface                 http://127.0.0.1:4040
# Conn                        0
Avg Conn Time                 0.00ms

When you run ngrok, it will display a UI in your terminal with the current status of the tunnel. This includes the public URL it has allocated to you which will forward to your local web service: https://3a4bfceb.ngrok.com.

Inspecting your traffic

ngrok captures all of the HTTP traffic that runs through it and provides a real-time web UI where you can introsepct the requests in more detail. After starting ngrok, open http://localhost:4040. Make a request to your tunnel and you should see the web UI update with detailed information about the request including the time, duration, headers, form and query parameters as well access to examine the raw bytes sent over the wire.

ngrok's web interface allows detailed introspection of HTTP requests and responses

XML/JSON syntax checking

ngrok has special support for the most common data interchange formats in use on the web. Any XML or JSON data is automatically pretty-printed for you and checked for syntax errors.

ngrok highlighting the location of a JSON syntax error

Replaying requests

ngrok allows you to replay any http request that has been made through the tunnel. Click the Replay button at the top-right of any request in the web UI and ngrok will replay it to your server.

Replay any request with a single click

Requiring passwords to access your tunnels

By default, ngrok tunnels do not require any username or password to access them. This means anyone who knows or guesses the URL or your tunnel can make requests to it. You can secure your tunnels with a username and password by specifying the -httpauth option when creating your tunnel. This will force HTTP basic authentication on all incoming requests to your tunnels and require that the credentials match those you specify on the command line.

Example: Add a username and password to your tunnel
$ ngrok -httpauth="helmet:12345" 80
$ curl -u "helmet:12345" https://3a4bfceb.ngrok.com

Requesting a specific tunnel subdomain

ngrok assigns random hexadecimal names like https://3a4bfceb.ngrok.com to the tunnels it opens for you. For one-time personal use tunnels, this is OK. However, if you are displaying this URL at a public event like a hackathon, or you've set this URL as a webhook for some third-party application, it can be frustrating if the tunnel name changes or is difficult to read. ngrok allows you to open a tunnel with a custom subdomain of your choosing with the -subdomain option. Let's try opening a tunnel on the example subdomain.

Example: Open a tunnel with a custom subdomain, 'example'
$ ngrok -subdomain=example 80
ngrok

...
Forwarding                    https://example.ngrok.com -> 127.0.0.1:80
...

Forwarding non-HTTP services

Are you developing a service that runs on IRC, SMTP, SIP, POP3, XML-RPC or even a custom network protocol that isn't HTTP? ngrok can still expose this service to the internet for you by running in TCP mode! When you run ngrok in TCP mode, it will allocate a port for you on ngrok.com and forward all traffic on that port to your local service. Unfortunately, when you run in TCP mode, ngrok does not know how to understand and parse your traffic, so its diagnostic and debugging tools are much more primitive when operating in this mode.

Example: Forward traffic to a locally running TCP service
$ ngrok -proto=tcp 22
ngrok

...
Forwarding                    tcp://ngrok.com:50612 -> 127.0.0.1:22
...

Forwarding to non-local services

ngrok can also be used to forward traffic to services behind a NAT or firewall even if that service is not on the same machine. Forwarding traffic to another machine is as simple as adding an ip address or name before the port.

Example: Forward traffic to a service on a host on the private network
$ ngrok 192.168.0.1:80

Tunnels on custom domains (white label URLs) Paid Feature

ngrok has a -hostname option which allows you to forward traffic from your own domains without running your own ngrok server. For example, if you want ngrok to create a tunnel for dev.example.com, you must:

  1. Enter your custom hostname as a Reserved Domain on your ngrok.com dashboard. This guarantees that no one else can hijack your domain name with their own tunnel.
  2. Create a DNS CNAME record for dev.example.com that points to ngrok.com using whatever DNS management you have for example.com.
  3. Invoke ngrok with the -hostname option like so:
    $ ngrok -hostname dev.example.com 80
NB: With the -hostname option, you may still access your tunnel over SSL, but the certificate will not match.



The ngrok configuration file

The ngrok configuration file is a completely optional very simple YAML file that allows you to use some of ngrok's more advanced features like:

  1. Running multiple tunnels simultaneously.
  2. Connecting to a custom ngrok server
  3. Tweaking some of ngrok's more arcane settings.
The ngrok configuration file is loaded by default from ~/.ngrok. You can override this to point at a different location with the -config command line switch.

Running multiple tunnels simultaneously

To run multiple tunnels, you need to configure each tunnel in the configuration file using the tunnels parameter. The tunnels parameter takes a dictionary of names to tunnel configurations. As an example, let's define the configuration for three different tunnels. The first will be a tunnel for a client site that we're working on that only runs https traffic and has authentication. The second will be the configuration for a tunnel to allow us to access our own machine remotely via SSH by tunneling to port 22. And lastly, we'll create a tunnel that will run on my own custom domain for showing off projects at a hackathon.

tunnels:
  client:
    auth: "user:password"
    proto:
      https: 8080
  ssh:
    proto: 
      tcp: 22
  hacks.inconshreveable.com:
    proto:
      http: 9090

We can then start all three tunnels simultaneously by using the ngrok start command followed by the names of the tunnels we want to start:

ngrok start client ssh hacks.inconshreveable.com

The terminal should then look something like:

ngrok

Tunnel Status                 online
Version                       1.3/1.3
Forwarding                    https://client.ngrok.com -> 127.0.0.1:8080
Forwarding                    http://hacks.inconshreveable.com -> 127.0.0.1:9090
Forwarding                    tcp://ngrok.com:44764 -> 127.0.0.1:22
...

Tunnel configuration

Each configured tunnel may specify any of five parameters: proto, subdomain, auth, hostname, and remote_port. Every tunnel must have a proto section defined which is a dictionary of protocol to local forwarding address. The auth parameter is the optional authentication used for http/https tunnels. The remote_port parameter is the optional port to bind on the remote server and is only used for tcp tunnels. ngrok uses the name of the tunnel as the subdomain or hostname for the tunnel it creates, but you can override this:

tunnels:
  client:
    subdomain: "example"
    auth: "user:password"
    proto:
      https: 8080

Now when you ngrok start client it will forward example.ngrok.com -> 127.0.0.1:8080. Similarly, this works for custom hostnames, which can let you alias them to something shorter to type:

tunnels:
  hacks:
    hostname: "hacks.inconshreveable.com"
    proto:
      http: 9090

For TCP tunnels, you may optionally request a specific port from the server with the remote_port parameter. If not specified, the server will assign you a random port.

tunnels:
  ssh:
    remote_port: 60123
    proto:
      tcp: 22

Other configuration options

The ngrok configuration file additionally lets you tweak some less-common configuration settings by specifying additional top-level parameters in the config file. For example, you may explicitly set the authtoken used when validating to ngrok.com with the auth_token parameter. You may also change the address that ngrok binds with to serve its web inspection interface by setting inspect_addr:

auth_token: abc123
inspect_addr: "0.0.0.0:8888"
tunnels:
  ...

Connecting to a custom ngrokd server

ngrok supports connecting to another ngrokd server not hosted by ngrok.com. First, you must obviously set up your own ngrokd server. Instructions on how to run your own ngrokd are posted here: Running your own ngrokd server. When you run your own ngrokd server, you need to configure two configuration parameters to let ngrok connect securely to your custom server. First you'll set server_addr to point ngrok at your custom server and then trust_host_root_certs to make sure your TLS connections are trusted.

server_addr: "example.com:4443"
trust_host_root_certs: true
tunnels:
  ...

Running behind an http proxy

Lastly, you can configure ngrok to run behind an http proxy server, which is sometimes necessary when you're on restrictive corporate networks. ngrok respects the standard unix environment variable http_proxy, but you can also specify it explicitly by setting the parameter http_proxy in the configuration file:

http_proxy: "http://user:password@10.0.0.1:3128"
tunnels:
  ...