DevOps Spanish

Compartir un proyecto Laravel (Herd) con ngrok: link público en minutos

Posted on by Fernando Tamez
05
Feb

Compartir un proyecto Laravel (Herd) con ngrok: link público en minutos

Si estás corriendo tu proyecto Laravel en macOS con Laravel Herd (por ejemplo ejemplo.test) y quieres enseñárselo a tu Project Manager (PM) que está remoto, ngrok es una de las formas más rápidas de crear un enlace público temporal para que pueda entrar desde cualquier lugar.

En esta guía vas a:

  • Instalar ngrok en Mac.
  • Configurar tu authtoken de ngrok.
  • Generar un link público para un sitio servido por Herd.
  • Arreglar el error común de Herd: “Site not found” (Host header).
  • Ver comandos “tradicionales” de ngrok para servir un puerto (sin Herd).
  • Solucionar problemas típicos como CSRF 419 al hacer login.

Requisitos

  • macOS con Laravel Herd instalado y tu sitio funcionando (ej. http://ejemplo.test).
  • Homebrew instalado.
  • Una cuenta gratuita de ngrok.

Paso 1: Instalar ngrok en Mac

Instálalo con Homebrew:

brew install ngrok/ngrok/ngrok

Verifica que quedó instalado:

ngrok version

Paso 2: Configurar el authtoken de ngrok (una sola vez)

El authtoken no lo eliges tú: te lo da ngrok dentro de tu dashboard.

  1. Inicia sesión en ngrok y abre tu Dashboard.
  2. Busca la sección Auth Token.
  3. Copia el token y pégalo en este comando:
ngrok config add-authtoken TU_TOKEN_REAL

Si quieres confirmar que se guardó, revisa el archivo de configuración: 

cat "/Users/$USER/Library/Application Support/ngrok/ngrok.yml"

Tip de seguridad: no publiques tu authtoken. Es como una llave de tu cuenta.

Paso 3: Crear el link público para tu sitio de Herd

Aquí viene la parte clave: Herd sirve sitios por dominio (Host header). Si ejecutas ngrok “normal” contra el dominio, es muy común recibir un 404 con “Site not found”. La solución es reescribir el Host header para que Herd reciba el dominio correcto.

Opción A (recomendada): Reescribir el Host header

Detén cualquier ngrok que tengas corriendo (Ctrl + C) y ejecuta: 

ngrok http --host-header=rewrite http://ejemplo.test

ngrok mostrará un enlace público similar a: 

Forwarding  https://xxxxxx.ngrok-free.app -> http://ejemplo.test:80

Copia ese https://… y compártelo con tu PM.

Opción B: Forzar el host manualmente (alternativa)

Si por alguna razón la opción anterior no funciona, prueba forzando el host: 

ngrok http 80 --host-header=ejemplo.test

Solución del error típico: “404 Site not found” en Herd

Si tu PM entra al link de ngrok y ve algo como:

  • 404
  • Site not found
  • “Please ensure that the folder is within your parked paths.”

Entonces ngrok está enviando el Host como xxxx.ngrok-free.app y Herd no reconoce ese dominio. La solución es usar: 

ngrok http --host-header=rewrite http://ejemplo.test

Cómo validar localmente que el Host header es el problema

Puedes probar desde tu terminal que Herd responde correctamente cuando el Host es el dominio del site: 

curl -I http://127.0.0.1:80 -H "Host: ejemplo.test"

Si la respuesta cambia a 200 o 302 (en lugar de “Site not found”), confirmas que el fix de Host header es el correcto.

Problemas comunes y fixes rápidos

1) El login falla con error 419 (CSRF)

Cuando cambias de dominio (de .test a ngrok-free.app), Laravel puede bloquear la sesión/CSRF. Prueba esto:

  1. En tu archivo .env, actualiza APP_URL con el link de ngrok:
APP_URL=https://TU_SUBDOMINIO.ngrok-free.app
SESSION_SECURE_COOKIE=true

Luego limpia cachés:

php artisan optimize:clear

2) No cargan los assets (CSS/JS) si usas Vite

Si estás en modo dev con Vite y tu PM entra desde fuera, a veces los assets no cargan. Para demo rápida, lo más estable suele ser compilar: 

npm run build

Y asegúrate de estar usando el helper de Laravel (@vite) correctamente en tu layout.

3) El link cambia cada vez

En el plan gratuito de ngrok, el subdominio normalmente cambia al reiniciar el túnel. Si quieres un link más estable, considera:

  • Un plan de ngrok con dominio reservado.
  • Alternativa: Cloudflare Tunnel (también muy buena para links estables).

Comandos tradicionales de ngrok (sin Herd)

Si no estás usando Herd (o tu app sirve directamente en un puerto), estos son los comandos típicos. Aquí ngrok expone un puerto (por ejemplo, 3000, 8000 o 5173).

1) Exponer un puerto local (lo más común)

Ejemplo: si tu app corre en http://localhost:8000:

ngrok http 8000

Ejemplo: Vite suele correr en 5173:

ngrok http 5173

2) Exponer una URL local completa

También puedes pasar la URL:

ngrok http http://localhost:8000

3) Usar el panel de ngrok para ver requests (muy útil para debug)

Cuando ngrok está corriendo, abre esta URL en tu navegador: 

http://127.0.0.1:4040

Ahí puedes ver todas las requests, headers y respuestas.

Checklist final (para compartir con tu PM)

  • Tu sitio abre localmente: http://ejemplo.test
  • ngrok configurado con authtoken.
  • Túnel corriendo con Host header rewrite (Herd):
ngrok http --host-header=rewrite http://ejemplo.test
  • Compartes el link https://....ngrok-free.app con tu PM.

Conclusión

Con ngrok puedes enseñar avances de tu proyecto Laravel en Herd en cuestión de minutos. La clave para que funcione con Herd es reescribir el Host header, porque Herd decide qué sitio servir según el dominio.

Si quieres subir el nivel (links estables y más control), la siguiente mejora natural es usar Cloudflare Tunnel.

Fernando Tamez