Skip to main content
ngrok creates a secure tunnel from a public URL to your local Flask server, allowing remote access to your application without complex network configuration.

​
What is ngrok?

ngrok is a reverse proxy that creates a secure tunnel to your localhost. It’s useful for:
  • Sharing your local development environment with others
  • Testing webhooks that require a public URL
  • Demonstrating your application without deploying
  • Accessing your local server from mobile devices
The free tier of ngrok provides random URLs that change each time you restart the tunnel. For persistent URLs, consider upgrading to a paid plan.

​
Installation

Using Homebrew:
brew install ngrok
Verify installation:
ngrok --version

​
Authentication Setup

1

Create an ngrok account

Sign up for a free account at ngrok.com
2

Get your authtoken

After signing in, navigate to the dashboard to find your authtoken.
3

Configure ngrok with your token

Run this command once (replace YOUR_TOKEN with your actual token):
ngrok config add-authtoken YOUR_TOKEN
Expected output:
Authtoken saved to configuration file: /Users/your-name/.ngrok2/ngrok.yml
You only need to configure the authtoken once. It will be saved to your ngrok configuration file.

​
Using ngrok with the Application

​
Integrated with Automated Scripts

The run scripts (run.sh and run.ps1) include built-in ngrok support: 
./run.sh
When prompted:
[3/3] ¿Quieres levantar ngrok para acceso remoto? (s/n)
Type s and press Enter:
Levantando ngrok en puerto 5000...

​
Manual Setup

If you’re running the servers manually or want more control:
1

Start the ICE and Flask servers

Ensure both servers are running first:
# Terminal 1: ICE Server
cd backend
python3 server.py

# Terminal 2: Flask Server
cd backend
python3 web_server.py
The Flask server will display:
✓ Servidor Flask escuchando en http://localhost:5000
  Para exponerlo con ngrok ejecuta: ngrok http 5000
2

Start ngrok in a third terminal

ngrok http 5000
If you’re using a custom port via environment variables, replace 5000 with your configured port.
3

Copy the public URL

ngrok will display a status screen:
ngrok                                                           

Session Status                online
Account                       [email protected]
Version                       3.x.x
Region                        United States (us)
Latency                       50ms
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://abc-123-def.ngrok-free.app -> http://localhost:5000

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00
Your public URL is shown in the Forwarding line: https://abc-123-def.ngrok-free.app

​
Accessing Your Application

Once ngrok is running, you can access your application via the public URL: 
https://abc-123-def.ngrok-free.app
Share this URL with anyone who needs access to your local server.
ngrok free tier displays an interstitial page before redirecting to your application. Users need to click “Visit Site” to proceed.

​
ngrok Web Interface

ngrok provides a local web interface for inspecting traffic: 
http://localhost:4040
Features:
  • View all HTTP requests and responses
  • Replay requests for testing
  • Inspect request/response headers and bodies
  • Monitor tunnel status
The web interface is extremely useful for debugging webhook integrations and API calls.

​
Advanced Configuration

​
Custom Subdomain

With a paid ngrok plan, you can use custom subdomains: 
ngrok http 5000 --subdomain=my-converter
This creates a persistent URL: https://my-converter.ngrok-free.app

​
Custom Domain

With a paid plan, you can use your own domain: 
ngrok http 5000 --domain=converter.yourdomain.com

​
Basic Authentication

Add password protection to your tunnel: 
ngrok http 5000 --basic-auth="username:password"
Visitors will need to enter the username and password to access your application.

​
Configuration File

For complex setups, create an ngrok configuration file at ~/.ngrok2/ngrok.yml:
ngrok.yml
version: "2"
authtoken: YOUR_TOKEN
tunnels:
  converter:
    proto: http
    addr: 5000
    inspect: true
    bind_tls: true
Start the tunnel: 
ngrok start converter

​
Automated Script Implementation

The run scripts include ngrok integration: 
# Terminal 3: ngrok (opcional)
echo ""
echo -e "${GREEN}[3/3] ¿Quieres levantar ngrok para acceso remoto? (s/n)${NC}"
read -r response
if [[ "$response" =~ ^[Ss]$ ]]; then
    echo -e "${BLUE}Levantando ngrok en puerto 5000...${NC}"
    ngrok http 5000
else
    echo -e "${BLUE}✅ Servidores activos:${NC}"
    echo -e "   - ICE Server: http://localhost:10000"
    echo -e "   - Web App: http://localhost:5000"
    echo -e "${YELLOW}Presiona Ctrl+C para detener${NC}"
    wait
fi

​
Security Considerations

When using ngrok, your local server is exposed to the internet. Follow these security best practices:
  • Only run ngrok when you need remote access
  • Don’t expose sensitive data or credentials
  • Use basic authentication for production-like testing
  • Monitor the ngrok web interface (port 4040) for suspicious traffic
  • Stop the tunnel when you’re done using it

​
Troubleshooting

​
ngrok: command not found

ngrok is not installed or not in your PATH. Follow the installation steps above.

​
Authentication Failed

If you see an authentication error: 
ERR_NGROK_108: The authtoken you specified does not look like a proper ngrok tunnel authtoken.
Reconfigure your authtoken: 
ngrok config add-authtoken YOUR_TOKEN

​
Tunnel Connection Failed

Ensure the Flask server is running before starting ngrok: 
# Check if Flask is running on port 5000
curl http://localhost:5000/api/status

​
Free Tier Limitations

The free tier has limitations:
  • 1 online ngrok process
  • 40 connections per minute
  • Random URLs that change on restart
For higher limits, consider upgrading to a paid plan.

​
Stopping ngrok

Press Ctrl+C in the terminal running ngrok to stop the tunnel: 
Stopping tunnel...
Tunnel stopped successfully
The public URL will immediately become unavailable.

​
Alternative Solutions

If ngrok doesn’t meet your needs, consider these alternatives:

​
Next Steps

Local Setup

Learn how to run the application locally

Environment Variables

Configure host, port, and debug settings

Build docs developers (and LLMs) love

Get started for freeTalk to us