LinuxCommandLibrary

ngrok

Expose local server to public internet

TLDR

Expose a local HTTP service on a given port

$ ngrok http [80]
copy

Expose a local HTTP service on a specific host
$ ngrok http [foo.dev]:[80]
copy

Expose a local HTTPS server
$ ngrok http https://localhost
copy

Expose TCP traffic on a given port
$ ngrok tcp [22]
copy

Expose TLS traffic for a specific host and port
$ ngrok tls -hostname=[example.com] [443]
copy

SYNOPSIS

ngrok
[options]
<command>
[command_options]
<arguments>

Common usage:
ngrok http 80
ngrok tcp 22
ngrok start my_tunnel

PARAMETERS

--authtoken <token>
    Authenticates the ngrok agent with your account to enable advanced features like custom domains and more concurrent tunnels.

--region <region>
    Specifies the ngrok server region to connect to (e.g., us, eu, ap, au, sa, jp, in).

--config <path>
    Specifies an alternate path to the ngrok configuration file. Default is ~/.ngrok2/ngrok.yml.

--log <mode>
    Configures where ngrok's logs are sent (e.g., stdout, none, file, json).

--debug
    Enables verbose debug logging for troubleshooting.

--version
    Prints the ngrok client version and exits.

--host-header <value>
    (Used with `http` command) Rewrites the Host header of the incoming HTTP request before forwarding it to your local server.

--auth <user:pass>
    (Used with `http` command) Adds HTTP basic authentication to your tunnel, requiring a username and password to access the public URL.

--subdomain <name>
    (Used with `http` command) Requests a specific subdomain for your tunnel's public URL (e.g., <name>.ngrok.io). Requires an authenticated account.

DESCRIPTION

Ngrok is a powerful cross-platform command-line tool that creates secure, publicly accessible tunnels to your local machine. It acts as a reverse proxy, allowing you to expose a web server, API, or any other network service running on your local development environment to the internet. This is particularly useful for testing webhooks, demonstrating in-progress work to clients, accessing devices behind a firewall or NAT, or setting up temporary public access for collaborators without complex network configurations. Ngrok handles the complexities of NAT traversal and firewall bypass, providing a simple, one-line command to get a public URL or TCP address. It also offers features like traffic inspection via a local web UI, custom subdomains, HTTP basic authentication, and TLS termination. It supports HTTP, TCP, and TLS tunnels, making it versatile for various development and testing scenarios.

CAVEATS

Security Risks: Exposing local services to the internet via ngrok can introduce significant security risks if not properly secured. Ensure sensitive services are protected with authentication or only exposed temporarily.
Reliance on Ngrok Service: Ngrok is a cloud-based service, meaning its availability and performance depend on ngrok's infrastructure. It's not a purely local solution.
Free Tier Limitations: The free tier has limitations on concurrent tunnels, tunnel duration, custom subdomains, and bandwidth, which might require a paid subscription for heavier usage.
Network Latency: Data travels through ngrok's servers, which can introduce additional latency compared to direct local access.

LOCAL WEB INTERFACE (TRAFFIC INSPECTION)

When ngrok is running, it typically provides a local web interface accessible at http://localhost:4040. This interface allows you to inspect all HTTP traffic passing through your ngrok tunnels, view request/response headers, and even replay requests, which is incredibly useful for debugging.

CONFIGURATION FILE

Ngrok can be configured via a YAML file, usually located at ~/.ngrok2/ngrok.yml or ~/.config/ngrok/ngrok.yml. This file can store your authentication token, define persistent tunnels (e.g., `http`, `tcp`), and specify other default options, allowing for easier ngrok start command usage.

COMMON USE CASES

Beyond simple local server exposure, ngrok is widely used for:
- Webhooks Testing: Receiving webhook payloads from services like Stripe, GitHub, or Twilio directly to your local development environment.
- API Development: Testing APIs that rely on external callbacks or need to be accessed by external clients.
- Demoing Applications: Quickly sharing a live demo of a web application in progress without deployment.
- SSH Access: Creating a public TCP tunnel to SSH into a Raspberry Pi or other device behind a NAT.

HISTORY

Ngrok was created by Alan Shreve, who initially released it as an open-source project around 2013. It quickly gained popularity among developers due to its simplicity and effectiveness in solving the common problem of exposing local development servers. Over time, the project evolved into a commercial service, with a free tier still available, allowing for sustainable development and the introduction of advanced features like custom domains, improved security, and dedicated regions. Its ease of use and immediate utility solidified its place as a staple in many web developers' toolkits.

SEE ALSO

ssh(1), socat(1)

Copied to clipboard