Warum Hot Reload über einen Tunnel bricht — und was es wirklich behebt

Vite und Next.js aktualisieren Ihren Browser-Tab nicht, wenn Sie eine Datei speichern. Sie schicken das geänderte Modul über eine persistente WebSocket-Verbindung und patchen es in die laufende Seite ein. Das ist schnell und auch der Grund, warum das Teilen eines lokalen Entwicklungsservers mit einem Client, einem Telefon oder einem Webhook-Anbieter fragiler ist, als es auf den ersten Blick erscheint.

Die meisten allgemeingültigen Tunnel handhaben einfache HTTP-Anfragen gut, scheitern aber beim WebSocket-Upgrade-Handshake, auf den HMR angewiesen ist. Dieser Beitrag erklärt, warum das passiert, was ein Tunnel tatsächlich anders machen muss und wo zwei aktuelle Tools — eines Open-Source, eines in ein umfassenderes AI-Agenten-Entwicklungstool integriert — ins Bild passen.

Warum das Problem speziell ein WebSocket-Problem ist

Ein WebSocket beginnt als normale HTTP-Anfrage mit den Headern Upgrade: websocket und Connection: Upgrade. Der Server (oder ein Proxy) soll diesen Handshake erkennen und die Verbindung von Request/Response in einen rohen, langlebigen, bidirektionalen Byte-Stream umwandeln. Ein Tunnel, der das nicht explizit berücksichtigt, kann diese Header entfernen oder die Verbindung abbrechen, weil sie wie eine zu lange hängende Anfrage aussieht.

Zwei konkrete Stellen, an denen sich das zeigt:

Vite. Wenn ein Reverse-Proxy (oder Tunnel) vor Vite WebSocket-Verkehr nicht korrekt weiterleitet, fällt der Vite-Client auf die direkte Verbindung seines HMR-Sockets zurück — und protokolliert eine Warnung in der Konsole. Vite-Dokumentation weist darauf hin, dass dieser Fallback-Fehler in einem normalen lokalen Netzwerk meist ignoriert werden kann, da die direkte Verbindung trotzdem funktioniert. Das Problem: Über einen öffentlichen Tunnel ist „direkt“ von außerhalb Ihrer Maschine nicht erreichbar, also scheitert auch der Fallback, und HMR bricht zusammen. Vite empfiehlt, den Reverse-Proxy so zu konfigurieren, dass WebSocket-Verkehr durchgeleitet wird, oder server.ws (clientPort, port) zu setzen, damit Client und Server sich auf die Verbindung einigen.

Next.js. Seit Version 12 nutzt Next.js Fast Refresh über eine WebSocket-Verbindung bei /_next/webpack-hmr anstelle des älteren server-sent-events-Mechanismus. Ein falsch konfigurierter Proxy zwischen Browser und Entwicklungsserver ist eine häufige Ursache für Fehler wie „WebSocket wurde vor Verbindungsaufbau geschlossen“ bei benutzerdefinierten Next.js-Setups — die Lösung ist, sicherzustellen, dass alles, was vor dem Entwicklungsserver sitzt, WebSocket-Upgrade-Anfragen unberührt durchlässt.

Keines dieser Probleme ist spezifisch für einen bestimmten Tunnelanbieter; sie sind Eigenschaften der Implementierung von HMR in Vite und Next.js, und jedes Tool in der Mitte muss aktiv damit umgehen.

Was ein “framework-bewusster” Tunnel richtig machen muss

• Das Upgrade-Handshaking erkennen und auf reinen TCP-Passthrough umstellen, anstatt die Verbindung als blockierte HTTP-Anfrage zu behandeln.
• Die Verbindung aktiv halten mit periodischen Ping/Pong-Frames, da inaktive, langlebige Verbindungen von Firewalls und Load Balancern häufig gekillt werden.
• Host-/Origin-Header nicht verfälschen, da Entwicklungsserver zunehmend Origin-Checks aus Sicherheitsgründen durchführen. Ein Tunnel, der diese falsch umschreibt, kann Anfragen vom Server abgelehnt bekommen, noch bevor sie im Code ankommen.

Zwei Tools, die das heute tatsächlich tun

OutRay — Open-Source, selbst hostbar

OutRay ist ein echtes, aktiv gepflegtes Open-Source-Projekt (AGPL-3.0, ca. 1k GitHub-Sterne) und eine Alternative zu ngrok. Es unterstützt HTTP-, TCP- und UDP-Tunnel via CLI (outray http 3000, outray tcp 5432), benutzerdefinierte Domains, ein Dashboard mit Traffic-Analysen und Framework-Integrationen.

Die Express-Integration ist klar dokumentiert als echtes npm-Middleware-Paket (@outray/express) — Sie importieren es, umwickeln Ihre App, und es gibt eine Tunnel-URL zusammen mit dem normalen Server-Log aus. OutRay listet auch Plugins für Next.js, Vite und NestJS, wobei die Behauptung, das Next.js-Plugin ändere next.config.ts automatisch ohne CLI-Schritte, unbestätigt bleibt — diese spezielle Funktion sollte man erst prüfen, wenn man es selbst ausprobiert. Der Kernvorteil, der gut dokumentiert ist: Es ist Open Source, sodass Sie den gesamten Stack inspizieren oder selbst hosten können, anstatt einem Drittanbieter zu vertrauen.

AgentsRoom — ein Tunnel, eingebunden in ein größeres Tool, kein eigenständiges Produkt

Der ursprüngliche Entwurf bezeichnete das als ein dediziertes “browser-natives” Tunnel-Produkt. Das ist falsch: AgentsRoom ist eine native Desktop-App (Mac/Linux/Windows) zur Orchestrierung mehrerer AI-Coding-Agenten — Claude Code, Codex, Antigravity CLI und andere — mit einem Aufgaben-Board, projektbezogenen Terminals, einem in der App integrierten Browser-Automation QA-Agent und einer iOS/Android-Companion-App. Der localhost-Tunnel ist eine Funktion unter mehreren, kein eigenständiges Produkt, und läuft nicht “im Browser” — es ist eine native App-Funktion, die vom Desktop-Dashboard oder der mobilen App gestartet wird.

Was die Tunnel-Funktion laut eigener Dokumentation macht: Sie scannt offene lokale Ports, lässt Sie eine benutzerdefinierte Subdomain wählen und leitet HTTP/WebSocket-Verkehr zu Ihrem Next.js-, Vite-, Expo Metro- oder anderen Entwicklungsserver mit einem Start unter 2 Sekunden. Es sendet einen 25-Sekunden-Heartbeat mit bis zu fünf automatischen Wiederholungsversuchen und zeigt eine stilisierte Offline-Seite, wenn der Tunnel gestoppt ist, anstelle eines rohen Verbindungsfehlers. Die mobile App kann einen Tunnel aus der Ferne starten, sodass Sie eine Seite vom Telefon aus vorab ansehen können, ohne die Maschine zu berühren.

Zwei Dinge, die Sie wissen sollten, bevor Sie es als allgemeine Tunnel-Lösung betrachten: Es wird von einem einzelnen unabhängigen Entwickler gebaut (laut App Store), nicht von einem Unternehmen mit eigenem Netzwerkprodukt, und die kostenlose Stufe ist auf drei Projekte begrenzt — “null Kosten” gilt nur, wenn Ihr Nutzungsvolumen darunter bleibt.

Wo ngrok aktuell steht, da es der Vergleichspunkt ist

Die Kritik an ngrok bezüglich Bandbreitenbegrenzung und “ephemerer URL” ist meist gerechtfertigt: Der aktuelle Preisplan limitiert die kostenlose Stufe auf 1 GB Datenübertragung und 20.000 HTTP-Anfragen pro Monat, mit maximal drei Online-Endpunkten, einem automatisch zugewiesenen (nicht benutzerdefinierten) Domain und einer interstitial-Browser-Warnseite bei kostenlosen HTTP-Endpunkten (diese kann mit einem Header umgangen werden).

Ein häufig wiederholtes Gerücht ist jedoch falsch: ngrok’s kostenlose Stufe erzwingt keine harte Session-Timeout. Die Dokumentation von ngrok sagt explizit, dass kostenlose Endpunkte kein Timeout haben und unbegrenzt im Hintergrund laufen können — die tatsächlichen Beschränkungen sind die oben genannten monatlichen Daten- und Request-Limits. Wenn Sie die Aussage “2-Stunden-Session im Free-Tarif” anderswo sehen, prüfen Sie die Quelle gegen die ngrok-Dokumentation.

Praktische Erkenntnis

Wenn Sie bereits Vite oder Next.js verwenden und die WebSocket-Warnung sehen, lohnt es sich, zuerst die Konfiguration zu prüfen — server.ws in Vite oder sicherzustellen, dass alles, was vor Ihrem Next.js-Entwicklungsserver sitzt, Upgrade-Header durchlässt — bevor Sie eine neue Lösung in Betracht ziehen. Wenn Sie regelmäßig eine öffentliche HTTPS-URL für Webhook-Entwicklung oder mobile QA brauchen, spart ein Tunnel, der WebSocket-Upgrades explizit unterstützt, Konfigurationsaufwand. Und bei der Wahl zwischen Optionen ist es wichtig, echte Open-Source-Tools wie OutRay von einem Tunnel zu unterscheiden, der nur eine Komfortfunktion in einem größeren (bei AgentsRoom sogar von einem einzelnen Entwickler gepflegten) Produkt ist — das Vertrauen und die Wartung unterscheiden sich.

---

Changelog

Revidiert aus einem eingereichten Entwurf und überprüft am 28. Juli 2026.

1. SEO-Optimierung entfernt: wiederholte Keyword-Phrasen (“Next.js tunnel no CLI,” “zero deploy preview,” “zero-context-switching”) für Suchmaschinenzwecke gestrichen, stattdessen auf die tatsächlichen technischen Aussagen fokussiert.
2. AgentsRoom neu eingeordnet: ursprüngliche Annahme, es sei ein “browser-natives” Tool, korrigiert: Es ist eine native Desktop-App für Multi-Agenten-AI-Codierung mit integriertem Tunnel, kein eigenständiges Tunnel-Produkt und läuft nicht “im Browser”. Es wird von einem einzelnen Entwickler gebaut; das kostenlose Kontingent ist auf 3 Projekte begrenzt.
3. Unbestätigte OutRay-Funktion korrigiert: Die Behauptung, OutRay’s Next.js-Plugin ändere next.config.ts automatisch ohne CLI, konnte nicht bestätigt werden. Stattdessen ist die Express-Integration ein Standard-Middleware-Import, geprüft auf npmjs.com. Die spezielle Mechanik bleibt unbestätigt.
4. Vite WebSocket-Fallback erklärt: Der ursprüngliche Text, dass die “Direkt-WebSocket-Verbindung” immer ein Fehler ist, ist zu pauschal. Vite-Dokumentation weist darauf hin, dass dieser Fehler meist ignoriert werden kann, solange die direkte Verbindung gelingt; es wird nur problematisch, wenn der Client den Server nicht direkt erreicht, z.B. über einen Tunnel. Quelle: vite.dev/config/server-options.
5. Bestätigung Next.js HMR-Details: Next.js nutzt seit Version 12 eine WebSocket-Verbindung bei /_next/webpack-hmr für Fast Refresh, ersetzt eine frühere SSE-Lösung. Falsch konfigurierte Proxies sind eine bekannte Fehlerquelle.
6. ngrok Limits korrigiert und Mythos geprüft: Die aktuellen Zahlen (1 GB/Monat, 20.000 Requests, 3 Endpunkte, eine automatische Domain, umgehbare Warnseite) wurden direkt bei ngrok.com geprüft. Der Mythos eines “2-Stunden-Timeouts” ist falsch; die Dokumentation sagt, dass kostenlose Endpunkte unbegrenzt laufen können.
7. Tonfall: Die werblichen Formulierungen wurden in eine neutrale technische Erklärung umgeschrieben; keine Aussagen ohne Quellenprüfung übernommen.