Skip to main content

ngrok - Secure Tunnels to Your Localhost

A detailed guide to using ngrok for exposing local servers to the internet, testing webhooks, and streamlining development workflows.

Table of Contents​

What is ngrok?​

ngrok is a tool that creates secure tunnels from the public internet to your local machine. It is widely used for testing webhooks, sharing local sites, and remote debugging.

  • Expose local servers behind NATs and firewalls
  • Test webhooks from third-party services (Stripe, GitHub, etc.)
  • Share local development sites with teammates or clients

Installation​

macOS​

brew install --cask ngrok

Windows​

choco install ngrok

Linux​

sudo snap install ngrok

Or download from ngrok.com/download

Basic Usage​

Start a tunnel to your local server (e.g., running on port 3000):

ngrok http 3000

You will get a public URL (https and http) that forwards to your local port.

Common Use Cases​

  • Webhook Testing:
    • Use the public URL in services like Stripe, GitHub, or Twilio to receive webhooks on your local machine.
  • Sharing Local Sites:
    • Share the ngrok URL with others to demo your app.
  • Mobile App Development:
    • Test mobile apps against a backend running on your laptop.

Authentication & Dashboard​

Sign up at ngrok.com for a free account to get an authtoken. This unlocks more features and higher limits.

ngrok config add-authtoken <your-token>

Access the web dashboard at http://localhost:4040 to inspect requests and responses in real time.

Advanced Features​

  • Custom Subdomains:
    • Paid plans allow you to reserve subdomains: ngrok http -subdomain=myapp 3000
  • TCP/UDP Tunnels:
    • Expose other protocols: ngrok tcp 22 (for SSH)
  • Request Inspection:
    • Inspect, replay, and modify HTTP requests via the dashboard.
  • Access Control:
    • Restrict tunnel access with basic auth: ngrok http -auth="user:pass" 3000

Security Considerations​

  • Do not expose sensitive or production services without proper authentication.
  • Tunnels are public; anyone with the URL can access your local server.
  • Use ngrok's access control and IP restrictions for sensitive endpoints.

Troubleshooting​

  • Tunnel Not Working:
    • Check your local server is running and accessible.
    • Ensure firewall allows incoming connections.
  • Port Already in Use:
    • Use a different port or stop the conflicting service.
  • ngrok Limits:
    • Free plan has connection and session limits. Upgrade for more.

References​