Expose a local web server to the internet

ngrok allows you to expose a web server running on your local machine to the internet. Just tell ngrok what port your web server is listening on.

If you don't know what port your web server is listening on, it's probably port 80, the default for HTTP.

Example: Expose a web server on port 80 of your local machine to the internet

ngrok http 80

When you start ngrok, it will display a UI in your terminal with the public URL of your tunnel and other status and metrics information about connections made over your tunnel.

The ngrok console UI

ngrok by @inconshreveable
 
Tunnel Status                 online
Version                       2.0/2.0
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://92832de0.ngrok.io -> localhost:80
Forwarding                    https://92832de0.ngrok.io -> localhost:80
 
Connnections                  ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00
 

        

Inspecting your traffic

ngrok provides a real-time web UI where you can introspect all of the HTTP traffic running over your tunnels. After you've started ngrok, just open http://localhost:4040 in a web browser to inspect request details.

Try making a request to your public URL. After you have, look back at the inspection UI. You will see all of the details of the request and response including the time, duration, headers, query parameters and request payload as well as the raw bytes on the wire.

Detailed introspection of HTTP requests and responses

Replaying requests

Developing for webhooks issued by external APIs can often slow down your development cycle by requiring you do some work, like dialing a phone, to trigger the hook request. ngrok allows you to replay any request with a single click dramatically speeding up your iteration cycle. Click the Replay button at the top-right corner of any request on the web inspection UI to replay it.

Replay any request against your tunneled web server with one click

Request body validation

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

The location of a JSON syntax error is highlighted

Installing your Authtoken

Many advanced features of the ngrok.com service described in further sections require that you sign up for an account. Once you've signed up, you need to configure ngrok with the authtoken that appears on your dashboard. This will grant you access to account-only features. ngrok has a simple 'authtoken' command to make this easy. Under the hood, all the authtoken command does is to add (or modify) the authtokenproperty in your ngrok configuration file.

Install your authtoken

ngrok authtoken <YOUR_AUTHTOKEN>

HTTP Tunnels

Custom subdomain names

ngrok assigns random hexadecimal names to the HTTP tunnels it opens for you. This is okay for one-time personal uses. But if you're displaying the URL at a hackathon or integrating with a third-party webhook, it can be frustrating if the tunnel name changes or is difficult to read. You can specify a custom subdomain for your tunnel URL with the -subdomain switch.

Example: Open a tunnel with the subdomain 'inconshreveable'

ngrok http -subdomain=inconshreveable 80

ngrok by @inconshreveable
 
...
Forwarding                    http://inconshreveable.ngrok.com -> 127.0.0.1:80
Forwarding                    https://inconshreveable.ngrok.com -> 127.0.0.1:80

Password protecting your tunnel

Anyone who can guess your tunnel URL can access your local web server unless you protect it with a password. You can make your tunnels secure with the -auth switch. This enforces HTTP Basic Auth on all requests with the username and password you specify as an argument.

Example: Password-protect your tunnel

ngrok http -auth="username:password" 8080

Tunnels on custom domains (white label URLs)

Instead of your tunnel appearing as a subdomain of ngrok.io, you can run ngrok tunnels over your domains. To run a tunnel over dev.example.com, follow these steps:

1. Enter dev.example.com 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. On your dashboard, click on the 'CNAME' icon to copy your CNAME target.
3. Create a DNS CNAME record from dev.example.com to your CNAME target. In this example, we would point the CNAME record to XXX.cname.ngrok.io
4. Invoke ngrok with the -hostname switch and specify the name of your custom domain as an argument.

   Example: Run a tunnel over a custom domain

   ngrok http -hostname=dev.example.com 8000

Accessing custom domain tunnels over HTTPS will still work, but the certificate will not match. If you have a TLS certificate/key pair, try using a TLS tunnel.

Disabling Inspection

ngrok records each HTTP request and response over your tunnels for inspection and replay. While this is really useful for development, when you're running ngrok on production services, you may wish to disable it for security and performance. Use the -inspect switch to disable inspection on your tunnel.

Example: An http tunnel with no inspection

ngrok http -inspect=false 80

Rewriting the Host header

When forwarding to a local port, ngrok does not modify the tunneled HTTP requests at all, they are copied to your server byte-for-byte as they are received. Some application servers like WAMP, MAMP and pow use theHost header for determining which development site to display. For this reason, ngrok can rewrite your requests with a modified Host header. Use the -host-header switch to rewrite incoming HTTP requests.

If rewrite is specified, the Host header will be rewritten to match the hostname portion of the forwarding address. Any other value will cause the Host header to be rewritten to that value.

Rewrite the Host header to 'site.dev'

ngrok http -host-header=rewrite site.dev:80

Rewrite the Host header to 'example.com'

ngrok http -host-header=example.com 80

Tunneling only HTTP or HTTPS

By default, when ngrok runs an HTTP tunnel, it opens endpoints for both HTTP and HTTPS traffic. If you wish to only forward HTTP or HTTPS traffic, but not both, you can toggle this behavior with the -bind-tls switch.

Example: Only listen on an HTTP tunnel endpoint

ngrok http -bind-tls=false site.dev:80

Example: Only listen on an HTTPS tunnel endpoint

ngrok http -bind-tls=true site.dev:80

TLS Tunnels

HTTPS tunnels terminate all TLS (SSL) traffic at the ngrok.com servers using ngrok.com certificates. For production-grade services, you'll want your tunneled traffic to be encrypted with your own TLS key and certificate. ngrok makes this extraordinarily easy with TLS tunnels.

Forward TLS traffic to a local HTTPS server on port 443

ngrok tls -subdomain=encrypted 443

Once your tunnel is running, try accessing it with curl.

curl --insecure https://encrypted.ngrok.io

TLS Tunnels without certificate warnings

Notice that --insecure option in the previous curl command example? You need to specify that because your local HTTPS server doesn't have the TLS key and certificate necessary to terminate traffic for anyngrok.io subdomains. If you try to load up that page in a web browser, you'll notice that it tells you the page could be insecure because the certificate does not match.

If you want your certificates to match and be protected from man-in-the-middle attacks, you need two things. First, you'll need to buy an SSL (TLS) certificate for a domain name that you own and configure your local web server to use that certificate and its private key to terminate TLS connections. How to do this is specific to your web server and SSL certificate provider and beyond the scope of this documentation. For the sake of example, we'll assume that you were issued an SSL certificate for the domain secure.example.com.

Once you have your key and certificate and have installed them properly, it's now time to run a a TLS tunnel on your own custom domain name. The instructions to set this up are identical to those described in the HTTP tunnels section: Tunnels on custom domains. The custom domain you register should be the same as the one in your SSL certificate (secure.example.com). After you've set up the custom domain, use the -hostnameargument to start the TLS tunnel on your own domain.

Forward TLS traffic over your own custom domain

ngrok tls -hostname=secure.example.com 443

Terminating TLS connections

It's possible that the service you're trying to expose may not have the capability to terminate TLS connections. The ngrok client can do this for you so that you can encrypt your traffic end-to-end but not have to worry about whether the local service has TLS support. Specify both the -crt and -key command line options to specify the filesystem paths to your TLS certificate and key and the ngrok client will take care of terminating TLS connections for you.

Offload TLS Termination to the ngrok client

ngrok tls -hostname secure.example.com -key /path/to/tls.key -crt /path/to/tls.crt 80

Running non-HTTP services over TLS tunnels

ngrok TLS tunnels make no assumptions about the underlying protocol being transported. All examples in this documentation use HTTPS because it is the most common use case, but you can run run any TLS-wrapped protocol over a TLS tunnel (e.g. imaps, smtps, sips, etc) without any changes.

Compatible Clients

TLS tunnels work by inspecting the data present in the Server Name Information (SNI) extension on incoming TLS connections. Not all clients that initiate TLS connections support setting the SNI extension data. These clients will not work properly with ngrok's TLS tunnels. Fortunately, nearly all modern browsers use SNI. Some modern software libraries do not though. The following list of clients do not support SNI and will not work with TLS tunnels:

• Microsoft Internet Explorer 6.0
• Microsoft Internet Explorer 7 & 8 on Windows XP or earlier
• Native browser on Android 2.X
• Java <=1.6

A more complete list can be found on the Server Name Indiciation page on Wikipedia

TCP Tunnels

Not all services you wish to expose are HTTP or TLS based. ngrok TCP tunnels allow you to expose any networked service that runs over TCP. This is commonly used to expose SSH, game servers, databases and more. Starting a TCP tunnel is easy.

Expose a TCP based service running on port 1234

ngrok tcp 1234

Examples

Expose an SSH server listening on the default port

ngrok tcp 22

Expose a Postgres server listening on the default port

ngrok tcp 5432

Expose a Minecraft server listening on the default port

ngrok tcp 25565

Listening on a reserved remote address

Normally, the remote address and port is assigned randomly each time you start a TCP tunnel. For production services (and convenience) you often want a stable, guaranteed remote address. To do this, first, log in to your ngrok.com dashboard and click "Reserve Address" in the "Reserved TCP Addresses" section. Then use the-remote-addr option when invoking ngrok to bind a tunnel on your reserved TCP address.

Bind a TCP tunnel on a reserved remote address

ngrok tcp --remote-addr 1.tcp.ngrok.io:20301 22