Exécution locale, tunnel HTTPS et disponibilité pour ChatGPT

1. localhost — c’est pour vous seulement, pas pour ChatGPT

Commençons par la principale dissonance cognitive de ce module. Vous ouvrez http://localhost:3000 dans le navigateur, tout fonctionne parfaitement, Next.js sourit, le widget se rend. Cela semble logique : « Puisque j’ai une URL, donnons‑la simplement à ChatGPT ».

Le problème, c’est que localhost n’est pas « le domaine magique de ma machine sur Internet ». C’est un nom spécial qui pointe toujours vers la même machine où est lancé le navigateur ou le client. Votre ordinateur portable s’adresse à lui‑même. Les serveurs d’OpenAI, où tourne ChatGPT, savent eux aussi s’adresser à localhost… mais au leur — à l’intérieur du datacenter. Et votre Next.js est confortablement caché derrière votre routeur domestique, un NAT et, éventuellement, un VPN d’entreprise.

Dans cette leçon, nous allons :

• comprendre pourquoi localhost est inaccessible pour ChatGPT ;
• configurer un tunnel HTTPS via cloudflared de localhost:3000 vers une URL publique ;
• brancher cette URL dans le Dev Mode de ChatGPT ;
• vérifier la chaîne « code → tunnel → ChatGPT » avec une petite modification du widget et passer en revue les pièges typiques.

Il en découle deux faits simples :

1. ChatGPT ne sait pas où se trouve votre ordinateur portable.
2. Même s’il le savait, il ne pourrait pas s’y connecter directement — les connexions entrantes sont fermées.

De plus, ChatGPT travaille par principe uniquement avec des endpoints HTTPS publics : il faut un vrai domaine et un certificat TLS. Pour des raisons de sécurité, les serveurs d’OpenAI n’accèdent pas à des adresses HTTP arbitraires sans chiffrement, il faut donc un domaine HTTPS avec un certificat valide. Exposer simplement http://mon‑IP‑publique:3000 — ce n’est déjà plus une option.

Nous avons donc besoin d’un intermédiaire — un service qui :

1. Vive sur Internet avec un vrai domaine HTTPS.
2. Puisse relayer en sécurité les requêtes depuis ce domaine vers votre localhost:3000.

C’est exactement ce qu’est un tunnel HTTPS.

2. Qu’est‑ce qu’un tunnel HTTPS : modèle intuitif

En laissant de côté le jargon, un tunnel est un service qui vous donne une URL publique temporaire (ou permanente) et qui transfère toutes les requêtes de cette URL vers votre port local. En termes réseaux, c’est en fait un serveur proxy inverse (reverse proxy) qui maintient une connexion sortante vers le cloud.

Analogiquement : vous êtes assis derrière une porte fermée (le routeur domestique), et le tunnel — c’est le coursier qui se tient dehors avec une pancarte « tout le courrier ici », et qui, de temps à autre, passe par l’entrée de service pour vous remettre le courrier en main propre.

Le cheminement d’une requête ressemble à ceci :

sequenceDiagram
    participant ChatGPT as ChatGPT (cloud)
    participant Tunnel as Tunnel HTTPS
(Cloudflare / ngrok)
    participant Dev as Votre serveur de dev
(localhost:3000)

    ChatGPT->>Tunnel: Requête HTTPS vers https://xyz.trycloudflare.com
    Tunnel->>Dev: Requête HTTP vers http://localhost:3000
    Dev-->>Tunnel: Réponse Next.js
    Tunnel-->>ChatGPT: Réponse HTTPS

Voici les points clés.

Premièrement, l’initiateur de la connexion au service de tunnel, c’est vous. L’outil (cloudflared, ngrok, etc.) établit lui‑même une connexion sortante vers le cloud. C’est presque toujours autorisé, même derrière un NAT/un pare‑feu.

Deuxièmement, le service de tunnel vous fournit un domaine HTTPS avec un certificat valide, vous n’avez donc pas besoin de gérer un TLS auto‑signé à la main.

Troisièmement, pour ChatGPT votre App ressemble à un service web classique avec un domaine HTTPS. Il ne se doute pas que le trafic est ensuite relayé vers l’ordinateur portable de quelqu’un.

3. Quels tunnels existent et lequel choisir dans ce cours

Dans l’écosystème du développement web, plusieurs solutions populaires existent pour ce besoin :

• ngrok — un grand classique, longtemps le standard de facto pour « exposer du local vers l’extérieur ».
• Cloudflare Tunnel (cloudflared) — une solution moderne et gratuite de Cloudflare, qui fournit un domaine du type *.trycloudflare.com même sans inscription ; vous pouvez aussi rattacher votre propre domaine.
• LocalTunnel — un minimum de magie, juste un paquet npm qui fournit une URL HTTPS temporaire du genre https://something.loca.lt.

Toutes répondent au même besoin : donner à un serveur local un domaine HTTPS public, compatible avec ChatGPT.

Pour ce cours, nous voulons rester focalisés, donc comme outil « principal » nous utiliserons Cloudflare Tunnel avec l’utilitaire cloudflared. Raisons simples : pas d’inscription requise pour les tunnels rapides, HTTPS correct, et démarrage en une seule commande.

Cela dit, si vous êtes déjà fan de ngrok — aucun problème. Les commandes seront un peu différentes, mais le concept est identique : ngrok http 3000 au lieu de cloudflared tunnel --url http://localhost:3000.

Pour vous repérer plus facilement, voici un petit tableau récapitulatif.

https://*.trycloudflare.com

https://*.ngrok.app

https://*.loca.lt

Dans cette leçon, nous nous concentrerons sur Cloudflare Tunnel en mode « tunnel rapide à usage unique ». C’est largement suffisant pour « faire copain » entre votre Next.js et ChatGPT en Dev Mode.

4. Vérifier que le Next.js local est vivant

Avant d’exposer quoi que ce soit via un tunnel, il faut s’assurer que le serveur local fonctionne réellement. Sinon, vous déboguerez le tunnel alors que le problème est simplement que Next.js n’est pas lancé.

Rappel de l’ordre standard :

# depuis la racine du projet basé sur le template Apps SDK
npm install      # si ce n’est pas déjà fait
npm run dev      # lancement du serveur de dev Next.js

Par défaut, Next.js 16 écoute sur http://localhost:3000 (si le port n’est pas occupé). Dans le terminal, vous verrez quelque chose comme :

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

Ouvrez http://localhost:3000 dans le navigateur et assurez‑vous que la page du template s’ouvre. C’est votre « laboratoire local ». Si quelque chose ne fonctionne pas ici (erreur de build, TypeScript râle, port occupé) — corrigez cela d’abord, puis passez au tunnel.

5. Lancer Cloudflare Tunnel : de localhost vers un HTTPS public

Passons au plus savoureux — faisons en sorte que n’importe qui sur Internet (y compris ChatGPT) puisse ouvrir votre Next.js via une URL HTTPS.

Installation de cloudflared

La méthode d’installation dépend de l’OS. Le plus simple pour macOS — via Homebrew :

brew install cloudflare/cloudflare/cloudflared

Sur Windows et Linux, vous pouvez télécharger un binaire prêt à l’emploi ou utiliser un gestionnaire de paquets, comme recommandé par la documentation Cloudflare (des liens sont fournis dans les ressources complémentaires du module).

Vous pouvez vérifier l’installation avec :

cloudflared --version

Si l’utilitaire est introuvable, vérifiez votre PATH ou redémarrez le terminal.

Tunnel rapide à usage unique

Notre objectif pour l’instant — un tunnel minimal fonctionnel, sans compte, domaine ni configurations complexes. Pour cela, cloudflared a un mode quick tunnel, qui fournit une URL sur le domaine trycloudflare.com.

Avec npm run dev déjà lancé, exécutez dans un autre terminal :

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

Retenez une règle simple : HTTPS — à l’extérieur, HTTP — à l’intérieur. cloudflared vous fournit un domaine HTTPS côté public, mais pour joindre votre localhost:3000 il utilise du HTTP ordinaire.

Après un court log, vous verrez une ligne du genre :

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

Ce https://giftgenius-1234.trycloudflare.com — c’est la nouvelle adresse publique de votre application locale. Le tunnel reçoit les requêtes HTTPS sur ce domaine et les relaie vers http://localhost:3000.

Quelques points importants.

Premièrement, le terminal où tourne cloudflared doit rester ouvert tant que le tunnel est nécessaire. Dès que vous le fermez (ou appuyez sur Ctrl+C), le tunnel s’arrête et l’URL cesse de fonctionner.

Deuxièmement, à chaque lancement du quick tunnel, l’URL peut changer. Pour notre développement pédagogique, c’est normal : l’objectif de ce module est simplement de donner à ChatGPT un accès à votre Next.js local via n’importe quelle adresse HTTPS fonctionnelle. Mais cela signifie que, dans le Dev Mode de ChatGPT, il faudra parfois mettre à jour l’URL. Dans le module 7, nous reviendrons sur le sujet des tunnels et nous configurerons un domaine de dev stable, pour ne plus courir après les adresses.

Vérifier le tunnel comme un site ordinaire

Avant de brancher tout cela à ChatGPT, vérifions que le tunnel est bien ouvert depuis Internet.

1. Ouvrez l’URL obtenue https://...trycloudflare.com dans un navigateur.
2. Vous devez voir la même interface que sur http://localhost:3000.
3. Dans la console où tourne npm run dev, vous verrez de nouvelles requêtes — preuve que Next.js sert bien l’accès externe.

Si la page ne s’ouvre pas ou affiche une erreur, vérifiez d’abord :

• Si npm run dev est lancé.
• Si vous ne vous êtes pas trompé d’URL locale pour le tunnel (http://localhost:3000, et non https:// ni le port 3001).
• Si rien ne bloque les connexions sortantes (rare, mais possible dans des réseaux d’entreprise stricts).

6. Faire passer cette URL dans le Dev Mode de ChatGPT

Nous avons désormais tout ce qu’il faut pour relier la chaîne :

ChatGPT (cloud) → votre tunnel HTTPS → Next.js local.

Vous avez déjà vu la partie interface du Dev Mode dans la leçon précédente, nous allons simplement refaire la même chose, mais avec une URL HTTPS réelle, et pas uniquement théorique.

La séquence générale des actions dans ChatGPT est la suivante.

Ouvrez d’abord ChatGPT dans le navigateur et allez dans la section pour les développeurs (généralement « Developer », « Apps », « My apps » — les intitulés exacts peuvent changer avec l’UI).

Créez une nouvelle application ou modifiez votre application de dev existante, si vous l’avez déjà créée.

Dans le champ où l’on vous demande l’URL de votre App, indiquez l’adresse racine du tunnel, par exemple :

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

Le point d’entrée est notre /route/mcp.ts. Lors de la connexion, ChatGPT commencera par celui‑ci, puis récupérera toutes les informations nécessaires. Le README du template peut indiquer un autre chemin si plusieurs applications existent ; pour l’instant, partons du principe que l’URL racine du tunnel + /mcp — c’est ce qu’il vous faut.

Enregistrez la configuration de l’application. À ce moment, ChatGPT effectue plusieurs requêtes à votre application via le tunnel :

• Il lit le manifeste de l’App (métadonnées, outils, etc.).
• Il vérifie la disponibilité de l’endpoint MCP.
• Il récupère la liste de tous les tools et ressources.
• Il met en cache le code HTML de tous les widgets (!)

Si tout va bien, vous verrez votre application dans la liste des Dev‑Apps. Si quelque chose est cassé (manifeste invalide, serveur qui ne répond pas, tunnel tombé), ChatGPT affichera une erreur du type « App unavailable » ou quelque chose de proche.

Important : ChatGPT utilisera cette même URL HTTPS du tunnel à la fois pour appeler les outils (MCP) et pour charger le widget et les fichiers statiques. Dans la section suivante, nous détaillerons ces deux rôles séparément.

7. Comment circulent les requêtes maintenant : deux rôles pour votre tunnel

Il est important de bien comprendre ce que ChatGPT fait exactement avec cette URL. Dans l’architecture de l’Apps SDK, il y a deux points d’entrée principaux : l’endpoint MCP et le widget d’UI.

Schématiquement, la chaîne ressemble à ceci :

flowchart LR
    ChatGPT["ChatGPT (modèle)"] 
    subgraph Internet
        Tunnel[Tunnel HTTPS
giftgenius-1234.trycloudflare.com]
    end
    Local["Serveur de dev Next.js http://localhost:3000"]

    ChatGPT -- Requêtes HTTP(S) vers /mcp --> Tunnel
    ChatGPT -- Chargement de l’iframe /widget --> Tunnel
    Tunnel --> Local

Le tunnel a en fait deux rôles principaux :

• Rôle 1 : endpoint MCP (outils). Quand le modèle décide d’appeler un outil (tool), il fait un HTTP POST sur l’endpoint MCP (dans le template, c’est la route app/mcp/route.ts dans Next.js) sur le même domaine du tunnel.
• Rôle 2 : widget d’UI et fichiers statiques. Quand le modèle décide d’afficher un widget, il intègre un iframe avec votre URL (généralement /widget ou ce qui est indiqué dans le manifeste), et le chargement passe également par le tunnel.

Le tunnel n’est pas « pour une seule chose », c’est une porte unique vers votre App locale : UI, MCP, statique, tout passe par le même domaine public en HTTPS.

8. Pratique : vérifier la chaîne « code → tunnel → ChatGPT »

Pour vous assurer que tout fonctionne réellement, et pas seulement sur les schémas, suivez ce scénario minimal.

Premièrement, lancez npm run dev et assurez‑vous que http://localhost:3000 s’ouvre dans le navigateur.

Deuxièmement, lancez cloudflared tunnel --url http://localhost:3000 et obtenez une URL HTTPS publique. Testez‑la dans un autre navigateur ou même sur un autre appareil (par exemple, sur votre téléphone via le réseau mobile) — vous serez ainsi certain que les requêtes passent par Internet et ne tournent pas uniquement sur votre machine.

Troisièmement, ouvrez ChatGPT, passez en Dev Mode et assurez‑vous que votre App est connectée à cette URL. Dans le Composer du chat ChatGPT, choisissez votre App, démarrez un dialogue et vérifiez si ChatGPT insère le widget et charge votre UI.

Pour voir clairement que c’est bien votre code, modifiez quelque chose de très simple dans le widget, par exemple le titre :

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

export default function GiftGeniusWidget() {
  return <h1>GiftGenius via tunnel 🚇</h1>;
}

Après avoir enregistré le fichier :

1. Attendez que Next.js relance le fast refresh,
2. Allez dans la section de ChatGPT où vous avez ajouté votre application, et actualisez‑la (refresh).
3. Ouvrez/actualisez la session avec l’App dans ChatGPT
4. Saisissez une nouvelle requête à ChatGPT en lui demandant d’afficher votre widget
5. Vérifiez que le nouveau texte du titre est visible à l’intérieur de ChatGPT.

C’est le petit moment de vérité : vous venez de modifier du code sur votre machine, et ce changement s’est reflété dans l’interface cloud de ChatGPT via le tunnel.

9. Un mot sur la sécurité et « ce que vous exposez exactement »

Tout tunnel n’est pas un jouet, mais une vraie porte publique vers votre machine. Dans notre scénario pédagogique, nous ne relayons que localhost:3000, où tourne l’application Next.js. C’est relativement sûr si :

• ce port n’est utilisé pour rien d’autre ;
• vous n’avez pas une « application‑monstre » qui embarque une admin de base de données, phpMyAdmin et encore quatre services de démo.

Quelques règles pratiques importantes.

Le tunnel est un outil de développement, pas une infrastructure de production. Nous l’utilisons sciemment en Dev Mode, pas pour de vrais utilisateurs et certainement pas pour encaisser des paiements.

Évitez de faire tourner sur ce même port (3000) des panneaux d’administration, des bases sans mot de passe et autres outils du genre. Tout ce qui répond sur ce port devient visible depuis Internet tant que le tunnel est actif.

Ne partagez pas votre URL trycloudflare.com n’importe où. Certes, la probabilité que quelqu’un commence à la scanner activement pendant que vous faites un projet d’apprentissage est faible. Mais l’habitude « on balance le lien du serveur de dev partout » peut coûter cher en production.

Plus tard, quand nous aborderons Vercel et l’environnement de production, nous utiliserons un hébergement normal avec des domaines stables et une sécurité de production, tandis que le tunnel restera un outil strictement de dev.

10. Erreurs typiques avec l’exécution locale et le tunnel

Nous avons désormais un Next.js local lancé, un tunnel HTTPS opérationnel et le Dev Mode branché dans ChatGPT. Pour finir — quelques erreurs typiques que presque tout le monde rencontre au début, et comment les diagnostiquer rapidement.

Erreur n° 1 : tenter d’utiliser http://localhost:3000 directement dans ChatGPT.
Parfois, les débutants copient simplement cette URL dans la config du Dev Mode et s’étonnent que ChatGPT n’arrive pas à joindre l’App. Rappel : localhost signifie « moi‑même » pour celui qui fait la requête. Pour ChatGPT, c’est les serveurs d’OpenAI, pas votre ordinateur. Vous ne verrez aucun log particulier chez vous, car les requêtes n’arrivent tout simplement jamais à votre machine.

Erreur n° 2 : lancer un tunnel vers un port inexistant ou erroné.
Scénario fréquent : vous faisiez tourner npm run dev sur le port 3000, le serveur est tombé, mais dans un second terminal vous lancez machinalement cloudflared tunnel --url http://localhost:3000. Cloudflare vous donne un beau domaine HTTPS, mais à l’ouverture — erreur. Le diagnostic est simple : le serveur local n’est pas vivant. Vérifiez toujours d’abord http://localhost:3000 dans le navigateur, puis activez le tunnel.

Erreur n° 3 : confusion entre http:// et https:// lors du lancement du tunnel.
Le tunnel vous donne HTTPS côté public, mais vers le serveur local il faut utiliser HTTP, par exemple http://localhost:3000. Tenter d’indiquer https://localhost:3000 conduit souvent à des erreurs TLS internes ou simplement à une indisponibilité. Rappelez‑vous la règle : HTTPS — à l’extérieur, HTTP — à l’intérieur.

Erreur n° 4 : fermer le terminal du tunnel alors que vous testez dans ChatGPT.
Autre grand classique : tout est réglé, l’App fonctionne dans ChatGPT, puis vous fermez par erreur la fenêtre du terminal avec cloudflared. Dix minutes plus tard, vous revenez dans ChatGPT — et voyez « App unavailable ». La raison est simple : l’URL est restée dans la configuration de l’App, mais le tunnel lui‑même est éteint. Retenez la règle : tant que vous testez l’App en Dev Mode, un terminal avec le tunnel doit rester ouvert à côté.

Erreur n° 5 : utiliser sans le savoir une nouvelle URL après avoir relancé le tunnel.
En mode quick tunnel, Cloudflare fournit à chaque lancement un nouvel *.trycloudflare.com. Si vous avez arrêté puis relancé cloudflared, mais que ChatGPT référence encore l’ancienne URL, ChatGPT essaiera de l’utiliser et obtiendra des timeouts ou un autre service. Quand l’URL du tunnel change, mettez‑la toujours à jour dans le Dev Mode. Plus tard, nous verrons comment avoir un domaine de dev stable pour éviter de courir après les URL.

Erreur n° 6 : exposer des services superflus ou risqués sur le même port.
Par commodité, certains développeurs font tourner sur le port 3000 non seulement Next.js, mais aussi divers « outils internes » : panneau de debug, API expérimentale sans auth, etc. Dès que vous exposez ce port via le tunnel, toutes ces choses deviennent accessibles de l’extérieur. Pour un projet d’apprentissage, il ne se passera peut‑être rien de grave, mais cette habitude augmente fortement le risque de fuites et d’intrusions dans des projets réels. Gardez toujours à l’esprit : tout ce qui répond sur le port indiqué dans le tunnel est visible depuis Internet.