La fin des tunnels CLI : partage local natif dans le navigateur

Vite et Next.js ne rafraîchissent pas l’onglet de votre navigateur lorsque vous enregistrez un fichier. Ils envoient le module modifié via une connexion WebSocket persistante et l’intègrent dans la page en cours d’exécution. C’est rapide, mais cela explique aussi pourquoi partager un serveur de développement local avec un client, un téléphone ou un fournisseur de webhook est plus fragile qu’il n’y paraît.

La plupart des tunnels génériques gèrent bien les requêtes HTTP classiques, mais échouent lors de la handshake de mise à niveau WebSocket dont dépend le HMR. Cet article examine pourquoi cela se produit, ce qu’un tunnel doit faire différemment, et comment deux outils — l’un open-source, l’autre intégré dans un outil de développement AI plus large — s’intègrent dans cette problématique.

Pourquoi le problème est spécifiquement lié à WebSocket

Un WebSocket commence comme une requête HTTP ordinaire avec les en-têtes Upgrade: websocket et Connection: Upgrade. Le serveur (ou tout proxy) doit reconnaître cette handshake et basculer la connexion d’une requête/réponse vers un flux binaire bidirectionnel, long et en temps réel. Un tunnel qui ne gère pas explicitement cela peut supprimer ces en-têtes ou interrompre la connexion si elle semble suspendue trop longtemps.

Voici deux cas concrets où cela se manifeste :

Vite. Lorsqu’un reverse proxy (ou tunnel) devant Vite ne proxy pas correctement le trafic WebSocket, le client Vite revient à se connecter directement à son socket HMR — en contournant le proxy — et affiche un avertissement dans la console. La documentation de Vite indique que cette erreur de fallback peut généralement être ignorée sur un réseau local, car la connexion directe fonctionne encore. Mais en tunnel public, « direct » n’est pas accessible depuis l’extérieur, donc le fallback échoue aussi, et le HMR ne fonctionne plus. Vite recommande de configurer le proxy pour faire passer le trafic WebSocket ou de régler server.ws (clientPort, port) pour que le client et le serveur se mettent d’accord sur la façon d’atteindre le socket.

Next.js. Depuis la version 12, Next.js utilise Fast Refresh via WebSocket à l’adresse /_next/webpack-hmr au lieu de l’ancien mécanisme SSE. Un proxy mal configuré entre le navigateur et le serveur de développement peut provoquer l’erreur « WebSocket est fermé avant que la connexion ne soit établie ». La solution consiste à s’assurer que le proxy laisse passer les mises à niveau WebSocket sans modification.

Aucun de ces cas n’est spécifique à un fournisseur de tunnel ; ils dépendent de la façon dont Vite et Next.js implémentent le HMR, et tout outil intermédiaire doit gérer cela activement.

Ce qu’un tunnel « conscient du framework » doit faire

• Reconnaître la handshake de mise à niveau et basculer en mode passthrough TCP brut, plutôt que de traiter la connexion comme une requête HTTP bloquée.
• Maintenir la connexion vivante avec des frames ping/pong réguliers, car les connexions longues et inactives sont souvent tuées par les firewalls ou load balancers.
• Ne pas altérer les en-têtes Host/Origin, car les serveurs de développement vérifient de plus en plus l’origine pour des raisons de sécurité. Un tunnel qui modifie ces en-têtes peut faire rejeter les requêtes avant qu’elles n’atteignent votre code.

Deux outils qui font cela aujourd’hui

OutRay — open-source, auto-hébergeable

OutRay est un projet open-source actif (AGPL-3.0, environ 1k étoiles GitHub) qui se présente comme une alternative à ngrok. Il supporte les tunnels HTTP, TCP et UDP via CLI (outray http 3000, outray tcp 5432), les domaines personnalisés, un tableau de bord avec analytics, et des intégrations avec des frameworks.

Son intégration avec Express est documentée comme un middleware npm (@outray/express) — vous l’importez, enveloppez votre app, et il affiche une URL de tunnel dans les logs. La documentation mentionne aussi des plugins pour Next.js, Vite, et NestJS, mais la vérification indépendante de la claim selon laquelle le plugin Next.js modifie automatiquement next.config.ts avec aucune étape CLI reste à faire. La valeur principale : c’est open source, vous pouvez inspecter ou héberger vous-même tout le stack.

AgentsRoom — un tunnel intégré dans un outil plus large, pas un produit autonome

L’ébauche initiale le présentait comme un produit « natif dans le navigateur » ; c’est une erreur. AgentsRoom est une application desktop native (Mac/Linux/Windows) pour orchestrer plusieurs agents IA de codage — Claude Code, Codex, Antigravity CLI, etc. — avec un tableau de tâches, des terminaux par projet, un agent QA d’automatisation, et une app mobile iOS/Android. Le tunnel localhost est une fonctionnalité parmi d’autres, pas le produit lui-même, et rien ne tourne « dans le navigateur » — c’est une fonction native démarrée depuis un tableau de bord desktop ou l’app mobile.

Ce que fait la fonctionnalité de tunnel, selon la documentation d’AgentsRoom : scanner vos ports locaux ouverts, vous laisser choisir un sous-domaine personnalisé, et proxy le trafic HTTP/WebSocket vers votre serveur Next.js, Vite, Expo Metro ou autre, avec un démarrage en moins de 2 secondes. Il envoie un heartbeat de 25 secondes avec jusqu’à 5 tentatives de reconnexion, et affiche une page offline stylisée si le tunnel est arrêté, plutôt qu’une erreur brute. L’app mobile peut lancer un tunnel à distance pour prévisualiser un site depuis votre téléphone.

Deux points importants : c’est développé par un seul indépendant (d’après la fiche App Store), pas une grande entreprise, et la limite gratuite est à 3 projets — donc « zéro coût » seulement si vous restez sous cette limite.

La position de ngrok, en comparaison

Les critiques sur la bande passante et les « URL éphémères » de ngrok sont justifiées : leur tarif limite la version gratuite à 1 Go de transfert et 20 000 requêtes HTTP par mois, avec 3 endpoints en ligne, un domaine auto-assigné, et une page d’avertissement dans le navigateur. Mais la claim du « timeout de session de 2 heures » est fausse : la documentation officielle indique que les endpoints gratuits n’ont pas de timeout et peuvent fonctionner indéfiniment en tâche de fond. Les contraintes réelles sont les limites de données et requêtes par mois. Vérifiez toujours la source.

Conclusion pratique

Si vous utilisez déjà Vite ou Next.js et voyez l’avertissement de fallback WebSocket, essayez d’abord la configuration : server.ws pour Vite, ou assurez-vous que le proxy devant votre serveur Next.js laisse passer Upgrade — avant d’adopter un nouvel outil. Pour un URL HTTPS public pour webhook ou QA mobile, un tunnel conçu pour gérer WebSocket évite cette configuration. Enfin, distinguez outils open-source auto-hébergeables comme OutRay d’un tunnel intégré dans un produit plus large, souvent développé par un seul auteur, avec une politique tarifaire différente.

---

Changelog

Reformulé à partir d’un brouillon soumis, vérifié le 28 juillet 2026.

1. Suppression du SEO : suppression des phrases clés répétées pour le référencement, restructuration autour des revendications techniques.
2. Correction de la présentation d’AgentsRoom : ce n’est pas un outil de partage localhost « natif dans le navigateur », mais une application desktop multi-agent IA avec tunnel intégré, développé par un seul indépendant, avec une limite de 3 projets gratuits.
3. Clarification d’OutRay : la claim selon laquelle le plugin Next.js modifie automatiquement next.config.ts avec zéro CLI n’a pas été confirmée. La seule intégration vérifiée est un middleware npm (@outray/express).
4. Explication du fallback WebSocket de Vite : le message d’erreur n’est pas toujours critique, il peut être ignoré en local. La vraie erreur survient quand le client ne peut pas atteindre le serveur directement, comme en tunnel. Source : vite.dev/config/server-options.
5. Confirmation de la mécanique Next.js : Next.js utilise WebSocket à /_next/webpack-hmr depuis la v12 pour Fast Refresh, et un proxy mal configuré peut causer des erreurs.
6. Limites de ngrok et mythes : vérification des chiffres officiels (1 Go/mois, 20 000 requêtes, 3 endpoints, domaine auto, page d’avertissement). La claim du « timeout de 2 heures » est fausse : pas de timeout, seulement des limites de données. Source : ngrok.com/docs/pricing-limits.
7. Ton général : reformulation en un exposé technique neutre, vérifié contre sources officielles.