Ejecución local, túnel HTTPS y disponibilidad para ChatGPT

1. localhost es solo para ti, no para ChatGPT

Empecemos por la principal disonancia cognitiva de este módulo. Abres http://localhost:3000 en el navegador, todo funciona perfecto, Next.js sonríe, el widget se renderiza. Parece lógico: «Como ya tengo una URL, vamos a dársela a ChatGPT».

El problema es que localhost no es «un dominio mágico de mi máquina en Internet». Es un nombre especial que siempre apunta a la misma máquina donde se ejecuta el navegador o el cliente. Tu portátil se está llamando a sí mismo. Los servidores de OpenAI, donde se ejecuta ChatGPT, también pueden hacer peticiones a localhost… pero al suyo, dentro del centro de datos. Y tu Next.js está felizmente escondido detrás de tu router doméstico, NAT y, posiblemente, una VPN corporativa.

En esta lección vamos a:

• entender por qué localhost no está disponible para ChatGPT;
• configurar un túnel HTTPS mediante cloudflared desde localhost:3000 hasta una URL pública;
• conectar esa URL en el Dev Mode de ChatGPT;
• comprobar la cadena «código → túnel → ChatGPT» con un cambio sencillo en el widget y comentar las típicas trampas.

De aquí se desprenden dos hechos simples:

1. ChatGPT no sabe dónde está tu portátil.
2. Aunque lo supiera, tampoco podría conectarse directamente: las conexiones entrantes están cerradas.

Además, ChatGPT solo trabaja con endpoints públicos HTTPS (puntos de entrada): se necesita un dominio normal y un certificado TLS. Los servidores de OpenAI, por motivos de seguridad, no acceden a direcciones HTTP arbitrarias sin cifrado, por lo que hace falta un dominio HTTPS con certificado válido. Sacar fuera simplemente http://mi‑IP‑publica:3000 ya no es una opción.

Por eso necesitamos un intermediario: un servicio que:

1. Viva en Internet con un dominio HTTPS normal.
2. Pueda encaminar de forma segura las solicitudes desde ese dominio a tu localhost:3000.

Eso es un túnel HTTPS.

2. Qué es un túnel HTTPS: modelo intuitivo

Si dejamos de lado los términos rimbombantes, un túnel es un servicio que te da una URL pública (temporal o permanente) y reenvía todas las solicitudes desde allí a tu puerto local. En terminología de redes, es básicamente un servidor proxy inverso (reverse proxy) que mantiene una conexión saliente hacia la nube.

Analogía intuitiva: estás sentado detrás de una puerta cerrada (tu router doméstico) y el túnel es un mensajero que está fuera con un cartel «todas las cartas aquí», a veces entra por la puerta trasera y te entrega las cartas en mano.

El recorrido de la solicitud se ve más o menos así:

sequenceDiagram
    participant ChatGPT as ChatGPT (nube)
    participant Tunnel as Túnel HTTPS
(Cloudflare / ngrok)
    participant Dev as Tu servidor de desarrollo
(localhost:3000)

    ChatGPT->>Tunnel: Solicitud HTTPS a https://xyz.trycloudflare.com
    Tunnel->>Dev: Solicitud HTTP a http://localhost:3000
    Dev-->>Tunnel: Respuesta de Next.js
    Tunnel-->>ChatGPT: Respuesta HTTPS

Puntos clave:

Primero, el iniciador de la conexión con el servicio de túnel eres tú. La utilidad (cloudflared, ngrok, etc.) establece por sí sola una conexión saliente a la nube. Esto casi siempre está permitido incluso detrás de NAT/firewall.

Segundo, el servicio de túnel te otorga un dominio HTTPS con certificado válido, por lo que no necesitas montar manualmente un TLS autofirmado.

Tercero, para ChatGPT tu App parece un servicio web normal con dominio HTTPS. No sospecha que el tráfico luego va al portátil de alguien.

3. Qué tipos de túneles hay y cuál usaremos en el curso

En el ecosistema de desarrollo web hay varias soluciones populares para esta tarea:

• ngrok: el clásico, durante mucho tiempo fue el estándar de facto de «cómo exponer lo local hacia fuera».
• Cloudflare Tunnel (cloudflared): solución moderna y gratuita de Cloudflare, da dominios del tipo *.trycloudflare.com incluso sin registro; puedes adjuntar tu propio dominio si quieres.
• LocalTunnel: mínima magia, simple paquete de npm que emite una URL HTTPS temporal como https://something.loca.lt.

Todos resuelven la misma tarea: dar a un servidor local un dominio HTTPS público que sea válido para ChatGPT.

Para el curso, no queremos dispersarnos, así que como herramienta «principal» usaremos Cloudflare Tunnel con la utilidad cloudflared. Razones: no requiere registro para túneles rápidos, proporciona HTTPS real, y se lanza con un solo comando.

Aun así, si ya eres fan de ngrok, no pasa nada. Los comandos serán algo diferentes, pero el concepto es el mismo: ngrok http 3000 en lugar de cloudflared tunnel --url http://localhost:3000.

Para orientarnos mejor, reunimos las herramientas en una tabla pequeña.

https://*.trycloudflare.com

https://*.ngrok.app

https://*.loca.lt

En esta lección nos centraremos en Cloudflare Tunnel en modo «túnel rápido de un solo uso». Esto es más que suficiente para «amigar» tu Next.js con ChatGPT en Dev Mode.

4. Comprobamos que el Next.js local está vivo

Antes de exponer nada a través de un túnel, hay que asegurarse de que el servidor local realmente funciona. De lo contrario, vas a depurar el túnel cuando el problema es que Next.js simplemente no está arrancado.

Recordatorio del orden estándar:

# desde la raíz del proyecto con la plantilla de Apps SDK
npm install      # si aún no lo has hecho
npm run dev      # arranque del servidor de desarrollo de Next.js

Por defecto, Next.js 16 se levantará en http://localhost:3000 (si el puerto no está ocupado). En la terminal verás algo como:

ready - started server on 0.0.0.0:3000, url: http://localhost:3000

Abre en el navegador http://localhost:3000 y asegúrate de que se carga la página de la plantilla. Es tu «laboratorio local». Si aquí algo no funciona (error de build, TypeScript se queja, puerto en uso), arregla esto primero y luego pasa al túnel.

5. Lanzamos Cloudflare Tunnel: de localhost a HTTPS público

Vamos a lo jugoso: hacemos que cualquiera en Internet (incluido ChatGPT) pueda abrir tu Next.js con una URL HTTPS.

Instalación de cloudflared

El método de instalación depende del sistema operativo. La forma más simple en macOS es con Homebrew:

brew install cloudflare/cloudflare/cloudflared

En Windows y Linux puedes descargar el binario o usar el gestor de paquetes recomendado por la documentación de Cloudflare (los enlaces están en los materiales adicionales del módulo).

Puedes comprobar la instalación con:

cloudflared --version

Si no se encuentra la utilidad, revisa el PATH o reinicia la terminal.

Túnel rápido de un solo uso

Nuestro objetivo ahora es un túnel mínimo funcional, sin cuenta, dominio ni configuraciones complejas. Para ello cloudflared tiene el modo quick tunnel, que da una URL en el dominio trycloudflare.com.

Con npm run dev en ejecución, lanza en otra terminal:

cloudflared tunnel --url http://localhost:3000

Recuerda una regla simple: HTTPS — hacia fuera, HTTP — hacia dentro. cloudflared te dará por fuera un dominio HTTPS, pero hacia tu localhost:3000 irá por HTTP normal.

Tras un breve log verás una línea como:

INF +-------------------------------------------------------------+
INF |  Your quick Tunnel has been created!                        |
INF |  https://giftgenius-1234.trycloudflare.com                  |
INF +-------------------------------------------------------------+

Este https://giftgenius-1234.trycloudflare.com es la nueva dirección pública de tu aplicación local. El túnel acepta solicitudes HTTPS en ese dominio y las reenvía a http://localhost:3000.

Dos puntos importantes.

Primero, la terminal con cloudflared debe permanecer abierta mientras necesites el túnel. En cuanto la cierres (o pulses Ctrl+C), el túnel cae y la URL deja de funcionar.

Segundo, en cada arranque del quick tunnel la URL puede ser nueva. Para nuestro desarrollo didáctico está bien: el objetivo de este módulo es dar a ChatGPT acceso a tu Next.js local mediante cualquier dirección HTTPS que funcione. Pero significa que a veces tendrás que actualizar la URL en el Dev Mode de ChatGPT. En el módulo 7 volveremos al tema y configuraremos un dominio de desarrollo estable para no ir persiguiendo direcciones.

Probamos el túnel como un sitio normal

Antes de conectarlo a ChatGPT, verifiquemos que el túnel es accesible desde Internet.

1. Abre en el navegador la https://...trycloudflare.com que obtuviste.
2. Deberías ver la misma interfaz que en http://localhost:3000.
3. En la consola donde corre npm run dev verás nuevas solicitudes: Next.js realmente está atendiendo el acceso externo.

Si la página no abre o muestra error, comprueba primero:

• Si está ejecutándose npm run dev.
• Si no te equivocaste en la URL local al arrancar el túnel (http://localhost:3000, no https:// ni el puerto 3001).
• Si algo no bloquea las conexiones salientes (raro, pero pasa en redes corporativas estrictas).

6. Inyectamos esta URL en el Dev Mode de ChatGPT

Ahora ya tenemos todo para unir la cadena:

ChatGPT (nube) → tu túnel HTTPS → Next.js local.

La parte de la interfaz de Dev Mode ya la viste en la lección anterior; ahora repetimos lo mismo pero con una URL HTTPS real, no teórica.

La secuencia general en ChatGPT es así.

Primero, abre ChatGPT en el navegador y ve a la sección para desarrolladores (normalmente algo como «Developer», «Apps», «My apps»; los nombres concretos pueden cambiar con las actualizaciones del UI).

Crea una nueva aplicación o edita la app de desarrollo existente si ya la creaste.

En el campo donde se requiere la URL de tu App, indica la dirección raíz del túnel, por ejemplo:

https://giftgenius-1234.trycloudflare.com/mcp

El punto de entrada es nuestro /route/mcp.ts. Al conectarse, ChatGPT empezará por ahí y luego obtendrá toda la información necesaria. En el README de la plantilla puede indicarse otro path si hay varias aplicaciones; por ahora asumimos que la URL raíz del túnel + /mcp es lo que necesitas.

Guarda la configuración de la aplicación. En ese momento ChatGPT hará varias solicitudes a tu app a través del túnel:

• Lee el manifiesto del App (metadatos, herramientas, etc.).
• Comprueba la disponibilidad del endpoint MCP.
• Obtiene la lista de todas las tools y recursos.
• Cachea el código HTML de todos los widgets(!)

Si todo va bien, verás tu aplicación en la lista de Dev‑Apps. Si algo falla (manifiesto no válido, servidor no responde, túnel caído), ChatGPT mostrará un error como «App unavailable» o algo similar.

Importante: ChatGPT usará esa misma URL HTTPS del túnel tanto para invocar herramientas (MCP) como para cargar el widget y los estáticos. En la siguiente sección veremos estos dos roles por separado.

7. Cómo circulan ahora las solicitudes: dos roles de tu túnel

Es clave entender qué hace exactamente ChatGPT con esa URL. En la arquitectura de Apps SDK hay dos puntos de entrada principales: el endpoint MCP y el widget de UI.

La cadena simplificada se ve así:

flowchart LR
    ChatGPT["ChatGPT (modelo)"] 
    subgraph Internet
        Tunnel[Túnel HTTPS
giftgenius-1234.trycloudflare.com]
    end
    Local["Servidor de desarrollo de Next.js http://localhost:3000"]

    ChatGPT -- Solicitudes HTTP(S) a /mcp --> Tunnel
    ChatGPT -- Carga del iframe /widget --> Tunnel
    Tunnel --> Local

El túnel tiene, en la práctica, dos roles principales:

• Rol 1: endpoint MCP (herramientas). Cuando el modelo decide invocar una herramienta (tool), realiza un HTTP POST al endpoint MCP (en la plantilla es la ruta app/mcp/route.ts en Next.js) en el mismo dominio del túnel.
• Rol 2: widget de UI y estáticos. Cuando el modelo decide mostrar un widget, incrusta un iframe con tu URL (normalmente /widget o lo indicado en el manifiesto), y la carga también va a través del túnel.

El túnel no es «para una cosa concreta», es una única puerta hacia tu App local: UI, MCP, estáticos; todo pasa por el mismo dominio público HTTPS.

8. Práctica: comprobamos la cadena «código → túnel → ChatGPT»

Para asegurarnos de que todo realmente funciona y no es solo bonito en los diagramas, hagamos un escenario práctico mínimo.

Primero, ejecuta npm run dev y comprueba que http://localhost:3000 se abre en el navegador.

Segundo, lanza cloudflared tunnel --url http://localhost:3000 y obtén una URL HTTPS pública. Pruébala en otro navegador o incluso en otro dispositivo (por ejemplo, en el móvil con datos) para asegurarte de que las solicitudes van por Internet y no se quedan solo en tu máquina.

Tercero, abre ChatGPT, ve a Dev Mode y verifica que tu App está conectada a esa URL. En el Composer del chat de ChatGPT elige tu App, inicia un diálogo y observa si ChatGPT inserta el widget y carga tu UI.

Para ver de forma evidente que es tu código, cambia algo muy simple en el widget, por ejemplo, el encabezado:

// app/widget/page.tsx (ejemplo)
'use client';

export default function GiftGeniusWidget() {
  return <h1>GiftGenius a través del túnel 🚇</h1>;
}

Después de guardar el archivo:

1. Espera a que Next.js haga fast refresh,
2. Ve a la sección de ChatGPT donde añadiste tu aplicación y actualízala (refresh).
3. Abre/actualiza la sesión con la App en ChatGPT.
4. Escribe una nueva petición a ChatGPT solicitando mostrar tu widget.
5. Asegúrate de que el nuevo texto del encabezado ya se ve dentro de ChatGPT.

Ese es el pequeño momento de la verdad: acabas de cambiar código en tu máquina, y el cambio se reflejó en la interfaz en la nube de ChatGPT a través del túnel.

9. Un poco de seguridad y «qué has expuesto exactamente»

Cualquier túnel no es un juguete, sino una entrada pública real a tu máquina. En nuestro escenario didáctico exponemos solo localhost:3000, donde corre la aplicación Next.js. Esto es relativamente seguro si:

• ese puerto no se usa para nada más;
• no tienes un «monstruo de app» donde, por alguna razón, haya una consola de administración de base de datos, phpMyAdmin y cuatro servicios demo más.

Algunas reglas prácticas importantes.

El túnel es una herramienta de desarrollo, no un entorno de producción. Lo usamos conscientemente en Dev Mode, no para usuarios reales y, desde luego, no para cobrar dinero.

Evita ejecutar en ese mismo puerto (3000) paneles administrativos, bases sin contraseña y cosas similares. Todo lo que responda en ese puerto será visible desde Internet mientras el túnel esté activo.

No compartas tu URL de trycloudflare.com por todas partes. Sí, la probabilidad de que alguien la escanee activamente mientras haces un proyecto didáctico es baja. Pero el hábito de «pasar el enlace del servidor de dev a cualquiera» puede pasarte factura en producción.

Más adelante, cuando lleguemos a Vercel y a entornos de producción, usaremos un hosting normal con dominios estables y seguridad de producción, y el túnel quedará como herramienta de desarrollo.

10. Errores típicos al trabajar con la ejecución local y el túnel

Ya tenemos levantado el Next.js local, el túnel HTTPS funcionando y el Dev Mode conectado en ChatGPT. Para terminar, algunos errores típicos que casi todo el mundo comete al principio y cómo diagnosticarlos rápido.

Error n.º 1: intentar usar http://localhost:3000 directamente en ChatGPT.
A veces los principiantes copian esa URL en la configuración del Dev Mode y se sorprenden de que ChatGPT diga que no puede llegar a la App. Recuerda: localhost es «yo mismo» para quien hace la solicitud. Para ChatGPT eso son los servidores de OpenAI, no tu portátil. No verás logs especiales en tu máquina, porque las solicitudes ni siquiera llegan.

Error n.º 2: arrancar el túnel hacia un puerto inexistente o incorrecto.
Escenario común: en algún momento usaste npm run dev en el puerto 3000, el servidor ya cayó, pero en otra terminal, por costumbre, ejecutas cloudflared tunnel --url http://localhost:3000. Cloudflare te da un dominio HTTPS bonito, pero al abrirlo hay error. El diagnóstico es simple: el servidor local no está vivo. Comprueba siempre http://localhost:3000 en el navegador antes de encender el túnel.

Error n.º 3: confundir http:// y https:// al arrancar el túnel.
El túnel te da HTTPS por fuera, pero hacia el servidor local debe ir por HTTP, por ejemplo http://localhost:3000. Intentar poner https://localhost:3000 suele causar errores extraños de TLS o simple indisponibilidad. Recuerda la regla: HTTPS por fuera, HTTP por dentro.

Error n.º 4: cerrar la terminal con el túnel mientras pruebas activamente en ChatGPT.
Otro clásico: todo configurado, la App funciona en ChatGPT, luego cierras accidentalmente la ventana de la terminal con cloudflared. Diez minutos después vuelves a ChatGPT y ves «App unavailable». La razón es simple: la URL quedó en la configuración del App, pero el túnel está apagado. Regla de oro: mientras pruebes la App en Dev Mode, debe estar viva una terminal con el túnel.

Error n.º 5: usar sin darte cuenta una URL nueva tras reiniciar el túnel.
En el modo quick tunnel, Cloudflare da una nueva *.trycloudflare.com en cada ejecución. Si detuviste y volviste a arrancar cloudflared, pero en ChatGPT sigue la URL antigua, ChatGPT irá allí y obtendrá timeouts o incluso otro servicio. Cuando cambie la URL del túnel, actualízala siempre en la configuración del Dev Mode. Más adelante veremos cómo tener un dominio de desarrollo estable para no perseguir URLs.

Error n.º 6: exponer servicios extra o peligrosos en el mismo puerto.
A veces, por comodidad, se ejecutan en el puerto 3000 no solo Next.js, sino también «herramientas» varias: panel de debug, APIs experimentales sin autorización, etc. En cuanto expones ese puerto por el túnel, todo eso queda accesible desde fuera. En un proyecto didáctico quizá no pase nada, pero ese hábito en proyectos reales aumenta mucho el riesgo de fugas y hackeos. Ten siempre presente: todo lo que responda en el puerto indicado en el túnel mira a Internet.