🌐 Guía Completa de ngrok para Desarrollo Local

🚀 ¿Qué es ngrok?

ngrok es una herramienta que expone servidores locales a internet de forma segura, creando un túnel HTTPS hacia tu máquina local. Es perfecto para:

✅ Testing de APIs locales desde dispositivos móviles
✅ Demostraciones en vivo
✅ Desarrollo frontend/backend separado
✅ Webhooks locales
✅ Acceso remoto temporal

📥 Instalación

Windows

# Descargar ngrok
curl -o ngrok.zip https://bin.equinox.io/c/bNyj1mQVY4c/ngrok-v3-stable-windows-amd64.zip

# Extraer
powershell -Command "Expand-Archive -Path ngrok.zip -DestinationPath . -Force"

# Verificar instalación
.\ngrok.exe version

macOS

# Con Homebrew
brew install ngrok/ngrok/ngrok

# Manual
curl -o ngrok.zip https://bin.equinox.io/c/bNyj1mQVY4c/ngrok-v3-stable-darwin-amd64.zip
unzip ngrok.zip
sudo mv ngrok /usr/local/bin/

Linux

# Con snap
sudo snap install ngrok

# Manual
curl -o ngrok.zip https://bin.equinox.io/c/bNyj1mQVY4c/ngrok-v3-stable-linux-amd64.zip
unzip ngrok.zip
sudo mv ngrok /usr/local/bin/

⚙️ Configuración Inicial

1. Crear cuenta en ngrok

Ve a https://ngrok.com
Crea una cuenta gratuita
Copia tu authtoken del dashboard

2. Configurar autenticación

# Windows
.\ngrok.exe config add-authtoken TU_TOKEN_AQUI

# macOS/Linux
ngrok config add-authtoken TU_TOKEN_AQUI

3. Verificar configuración

ngrok version

🛠️ Comandos Básicos

Exponer un puerto local

# Exponer puerto 3000
ngrok http 3000

# Exponer puerto específico con nombre
ngrok http 8080 --name="mi-api"

# Exponer con subdominio personalizado (plan pago)
ngrok http 3000 --subdomain=mi-app

Exponer múltiples puertos

# Terminal 1
ngrok http 3000

# Terminal 2
ngrok http 8080

Exponer con configuración personalizada

# Con archivo de configuración
ngrok http 3000 --config=./ngrok.yml

# Con headers personalizados
ngrok http 3000 --host-header=localhost:3000

🔍 Gestión de Túneles

Ver túneles activos

Método 1: Interfaz Web

# Abrir ngrok en el navegador
ngrok http 3000
# Luego ve a: http://localhost:4040

Método 2: API REST

# Ver todos los túneles
curl http://localhost:4040/api/tunnels

# Ver información específica
curl http://localhost:4040/api/tunnels/nombre-del-tunel

Método 3: PowerShell (Windows)

# Obtener información de túneles
$tunnels = Invoke-RestMethod -Uri 'http://localhost:4040/api/tunnels'
$tunnels.tunnels | Select-Object name, public_url, proto

Cerrar túneles

Método 1: Interfaz Web

Ve a http://localhost:4040
Haz clic en el botón "Stop" del túnel

Método 2: API REST

# Cerrar túnel específico
curl -X DELETE http://localhost:4040/api/tunnels/nombre-del-tunel

Método 3: Terminal

# Presionar Ctrl+C en la terminal donde está corriendo ngrok

Método 4: PowerShell (Windows)

# Cerrar todos los túneles
$tunnels = Invoke-RestMethod -Uri 'http://localhost:4040/api/tunnels'
foreach ($tunnel in $tunnels.tunnels) {
    Invoke-RestMethod -Uri "http://localhost:4040/api/tunnels/$($tunnel.name)" -Method DELETE
}

📱 Conectar tu App o Frontend a ngrok

Una vez que ngrok está corriendo, cualquier aplicación puede consumir tu API local usando la URL pública que genera.

1. Levantar tu servidor local

# Ejemplo: API en .NET Core
dotnet run --urls=http://localhost:5000

# Ejemplo: API en Node.js / Express
node server.js  # corre en puerto 3000

# Ejemplo: FastAPI (Python)
uvicorn main:app --port 8000

2. Iniciar el túnel apuntando a ese puerto

ngrok http 5000

3. Obtener la URL pública

La terminal mostrará algo así:

Session Status    online
Forwarding        https://abc123.ngrok-free.app -> http://localhost:5000

Copia la URL https://... — esa es tu API accesible desde internet.

4. Usar la URL en tu cliente

React / Next.js:

const API_BASE = "https://abc123.ngrok-free.app";

const response = await fetch(`${API_BASE}/api/products`);

App móvil (React Native):

// En tu archivo de configuración o .env de desarrollo
const API_URL = "https://abc123.ngrok-free.app";

Variables de entorno (.env.local):

NEXT_PUBLIC_API_URL=https://abc123.ngrok-free.app

Postman / Insomnia: Cambia la base URL de http://localhost:5000 a https://abc123.ngrok-free.app en tu colección.

5. Header requerido en ngrok v3

Desde ngrok v3, las peticiones desde navegador pueden ser bloqueadas por la pantalla de advertencia. Para evitarlo en APIs, agrega el header:

# El cliente debe enviar este header
ngrok-skip-browser-warning: true

O en tu fetch:

const response = await fetch(`${API_BASE}/api/data`, {
  headers: { "ngrok-skip-browser-warning": "true" }
});

🔧 Configuración Avanzada

Archivo de configuración ngrok.yml

# ~/.ngrok2/ngrok.yml o ngrok.yml
version: "2"
authtoken: TU_TOKEN_AQUI

tunnels:
  web:
    proto: http
    addr: 3000
    subdomain: mi-app-web
  
  api:
    proto: http
    addr: 8080
    subdomain: mi-app-api
  
  db:
    proto: tcp
    addr: 5432

Usar configuración personalizada

ngrok start --all --config=ngrok.yml

🚨 Troubleshooting

Problemas Comunes

1. "tunnel session failed"

# Verificar authtoken
ngrok config check

# Reconfigurar token
ngrok config add-authtoken TU_TOKEN_AQUI

2. "bind: address already in use"

# Verificar puertos en uso
netstat -ano | findstr :4040

# Cambiar puerto de ngrok
ngrok http 3000 --web-addr=localhost:4041

3. "failed to start tunnel"

# Verificar que el puerto local esté activo
netstat -ano | findstr :3000

# Verificar firewall
# Windows: Permitir ngrok.exe en Windows Firewall

4. "ngrok not found"

# Agregar ngrok al PATH
# Windows: Agregar carpeta de ngrok al PATH del sistema
# macOS/Linux: sudo mv ngrok /usr/local/bin/

Comandos de Diagnóstico

# Verificar configuración
ngrok config check

# Ver logs detallados
ngrok http 3000 --log=stdout

# Verificar conectividad
ngrok version

📊 Monitoreo y Logs

Interfaz Web de ngrok

URL: http://localhost:4040
Funciones:
- Ver túneles activos
- Monitorear tráfico
- Ver requests/responses
- Cerrar túneles

Logs en tiempo real

# Ver logs detallados
ngrok http 3000 --log=stdout --log-level=debug

Métricas de uso

# Ver estadísticas
curl http://localhost:4040/api/requests/http

🎯 Casos de Uso Prácticos

Desarrollo Frontend + Backend separados

Cuando tu frontend (React/Next.js) y tu backend (.NET, Node, Python) corren en puertos distintos:

# Terminal 1: exponer el backend
ngrok http 5000 --log=stdout

# Terminal 2: exponer el frontend (si también necesitas compartirlo)
ngrok http 3000 --log=stdout

Ambas URLs quedan disponibles en http://localhost:4040.

Testing en dispositivos móviles reales

El simulador y el dispositivo físico no pueden alcanzar localhost de tu computadora. ngrok resuelve esto en segundos:

# Exponer tu API local
ngrok http 8080

# En tu app móvil usa la URL pública:
# https://abc123.ngrok-free.app/api/v1/endpoint

Webhooks de terceros (Stripe, PayPal, WhatsApp, etc.)

Los servicios externos necesitan una URL pública para enviar eventos. ngrok te permite recibirlos localmente durante el desarrollo:

# Exponer tu servidor de webhooks
ngrok http 3000

# Registra la URL en el panel de Stripe/PayPal:
# https://abc123.ngrok-free.app/webhooks/stripe

Demostraciones en vivo a clientes

Comparte tu trabajo en progreso sin necesidad de hacer deploy:

# Con subdominio fijo (plan pago) para compartir un link estable
ngrok http 3000 --subdomain=demo-cliente
# URL permanente: https://demo-cliente.ngrok.io

Integración con servicios de IA (OpenAI, Dialogflow)

Si tu backend maneja callbacks de servicios de IA:

ngrok http 8000
# Usa la URL en la configuración del webhook de tu asistente IA

🔒 Seguridad

Buenas Prácticas

✅ Usar HTTPS (automático con ngrok)
✅ No exponer servicios sensibles
✅ Cerrar túneles cuando no se usen
✅ Usar authtoken válido
✅ Monitorear tráfico en la interfaz web

Limitaciones del Plan Gratuito

🔸 1 túnel simultáneo
🔸 URLs aleatorias
🔸 Límite de conexiones
🔸 Sin subdominios personalizados

📚 Recursos Adicionales

Documentación oficial: https://ngrok.com/docs
Dashboard: https://dashboard.ngrok.com
API Reference: https://ngrok.com/docs/api
Comunidad: https://github.com/inconshreveable/ngrok

🎉 ¡Listo para usar!

Con esta guía puedes:

✅ Instalar y configurar ngrok en Windows, macOS y Linux
✅ Exponer cualquier API o servidor local a internet en segundos
✅ Conectar apps móviles, frontends y herramientas externas a tu entorno local
✅ Recibir webhooks de servicios como Stripe, PayPal o WhatsApp en desarrollo
✅ Gestionar y monitorear túneles activos desde la interfaz web
✅ Solucionar los problemas más comunes

ngrok es una de esas herramientas que, una vez que la usas, no puedes imaginar el workflow de desarrollo sin ella. Pequeña, rápida y sin configuración compleja.

¡Happy coding! 🚀