How to Use the Command 'ngrok' (with examples)

Ngrok is a popular tool that provides developers with a secure and easy method to expose their local web servers to the internet. Particularly useful for developing and testing locally-hosted web applications, Ngrok can create secure tunnels from public endpoints to private endpoints. This eliminates the need to deploy code to a live server for testing external integrations or sharing progress with stakeholders. By simply using a command, one can map a local server port to an external, internet-accessible address.

Use Case 1: Expose a Local HTTP Service on a Given Port

Code:

ngrok http 80

Motivation for Using This Example:

When developing a web application, testing how it interacts with external services or behaves under different network conditions is crucial. However, setting up a public server for testing every potential scenario can be cumbersome and time-consuming. By using Ngrok to expose a local HTTP service running on port 80, developers can instantly share their development environment with others or test webhooks and API interactions locally.

Explanation:

• http: This argument specifies that the protocol in use is HTTP. It tells Ngrok to expect a service that uses the HTTP protocol.
• 80: This indicates the port number on which the local HTTP server is running. Port 80 is typically used for HTTP servers.

Example Output:

When you run this command, Ngrok will output something like:

ngrok by @inconshreveable

Session Status                online
Account                       user@example.com (Plan: Free)
Version                       2.3.40
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://randomsubdomain.ngrok.io -> http://localhost:80
Forwarding                    https://randomsubdomain.ngrok.io -> http://localhost:80

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

This output shows the HTTP and HTTPS URLs that can be used to directly access the local service.

Use Case 2: Expose a Local HTTP Service on a Specific Host

Code:

ngrok http foo.dev:80

Motivation for Using This Example:

Sometimes a project requires binding services to a specific hostname for testing. This can often involve testing applications that manage multiple domains or subdomains. Using Ngrok, developers can expose a local service which runs on a specific hostname, allowing for a realistic test environment that replicates how the application will behave when deployed.

Explanation:

• http: Again, this specifies the HTTP protocol.
• foo.dev:80: This indicates that the service is running on the foo.dev hostname at port 80.

Example Output:

Expected output would be something like:

ngrok by @inconshreveable

Session Status                online
Account                       user@example.com (Plan: Free)
Version                       2.3.40
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://randomsubdomain.ngrok.io -> http://foo.dev:80
Forwarding                    https://randomsubdomain.ngrok.io -> http://foo.dev:80

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

This allows access to the service using either the HTTP or encrypted HTTPS URL.

Use Case 3: Expose a Local HTTPS Server

Code:

ngrok http https://localhost

Motivation for Using This Example:

Security is increasingly a priority in web development, and using HTTPS local servers is a common practice. By using ngrok to expose a local server running HTTPS, developers can share the same secure service setup with external users or clients securely, which closely mirrors the security settings in a production environment.

Explanation:

• http: Despite what it might seem, specifying http here is correct, as Ngrok wraps it appropriately.
• https://localhost: This indicates that the local server is running on localhost over HTTPS.

Example Output:

A typical output might look as follows:

ngrok by @inconshreveable

Session Status                online
Account                       user@example.com (Plan: Free)
Version                       2.3.40
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://randomsubdomain.ngrok.io -> https://localhost
Forwarding                    https://randomsubdomain.ngrok.io -> https://localhost

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

This output demonstrates access via both HTTP and HTTPS routes.

Use Case 4: Expose TCP Traffic on a Given Port

Code:

ngrok tcp 22

Motivation for Using This Example:

TCP is a core protocol in networking used for handling various types of connections, like SSH. By exposing TCP traffic on port 22, developers or administrators can remotely access the local machine securely, which is useful for remote debugging or server administration without exposing services directly to the internet.

Explanation:

• tcp: This specifies that the protocol in use is TCP. It instructs Ngrok to open a tunnel for TCP communications.
• 22: Indicates the port number being used, which is typically associated with SSH.

Example Output:

A typical output when running this command:

ngrok by @inconshreveable

Session Status                online
Account                       user@example.com (Plan: Free)
Version                       2.3.40
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    tcp://randomsubdomain.ngrok.io:44555 -> localhost:22

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

This output provides a TCP address through which connections to the local machine’s port 22 are available.

Use Case 5: Expose TLS Traffic for a Specific Host and Port

Code:

ngrok tls -hostname=foo.com 443

Motivation for Using This Example:

TLS (Transport Layer Security) is used to encrypt connections, and using Ngrok to expose TLS traffic from a specific host and port allows for secure, encrypted communication. It’s a practical choice for testing applications over secure connections and ensuring data privacy and integrity during transit.

Explanation:

• tls: This argument specifies the use of the TLS protocol.
• -hostname=foo.com: This option uniquely instructs Ngrok to expose services related to the specified hostname, foo.com.
• 443: This is the port number commonly used for HTTPS, indicating that this secure connection will listen to and expose traffic on port 443.

Example Output:

Typical output might be similar to:

ngrok by @inconshreveable

Session Status                online
Account                       user@example.com (Plan: Free)
Version                       2.3.40
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    tls://foo.com -> localhost:443

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

This output demonstrates a secure TLS connection established between the Ngrok server and the specified local host.

Conclusion:

Ngrok is a versatile tool useful for developers looking to expose their local development servers securely over the internet. It provides a variety of use cases involving different protocols and scenarios, with the added benefit of needing minimal configuration. Whether for testing web applications, securely handling local services, or sharing progress with others without a complex deployment process, Ngrok proves itself to be an indispensable tool in the developer’s arsenal.