ngrok

Expose a local HTTP service on a given port

$ ngrok http [80]

$ ngrok http [foo.dev]:[80]

$ ngrok http https://localhost

$ ngrok tcp [22]

$ ngrok tls -hostname=[example.com] [443]

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

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

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

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.

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.

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.

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.

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.

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.

ssh(1), socat(1)