tunnler/README.md

Tunnler

English | Deutsch

---

English

Disclaimer: This tool was vibe coded with Claude Code — architecture and structure were planned together with AI, and all implementation was done through prompts. Not a single line was written by hand.

Routes only Chrome and Codex through a wstunnel server on a home Raspberry Pi, even behind a corporate proxy that blocks sites.

Unlike a web proxy, the tunnel passes raw TCP connections. TLS ends at the real server, so Google and ChatGPT logins work.

Features

• Local proxy on 127.0.0.1:1080, used only by a dedicated Chrome profile and Codex
• Tunnel as WebSocket over wss:// on port 443, optionally through a corporate proxy
• Access only via a secret URL path
• Server allows only TCP 80/443 to public destinations, the home network is blocked
• Client needs no admin rights and runs on Windows PowerShell 5.1

Installation

Prerequisites:

• Raspberry Pi with Docker and Nginx Proxy Manager, own domain with SSL certificate
• Windows 10/11 with Google Chrome

Step-by-step guide for server and client (German): docs/installation.md

Usage

Double-click client\Chrome-Tunnel.cmd. The tunnel starts hidden in the background, then a separate Chrome window opens that runs entirely through the Pi.

Run client\PATH-eintragen.cmd once. Afterwards type codexx instead of codex in any project folder, for example in the VS Code terminal. Arguments are passed through.

Tunnel-Start.cmd starts only the tunnel. Then set 127.0.0.1:1080 as HTTP proxy in any program. Tunnel-Status.cmd shows the public IP through the tunnel. Tunnel-Stop.cmd stops the tunnel.

Configuration

All client values live in client\config.ps1 (copy from config.example.ps1).

Variable	Meaning	Default
$TunnelSecret	Secret path, identical to the server	empty
$TunnelServer	Server address	wss://deine-domain.de:443
$LocalProxy	Local proxy for Chrome and Codex	127.0.0.1:1080
$UpstreamProxy	Corporate proxy, empty = direct	empty
$UpstreamProxyUser / $UpstreamProxyPassword	Corporate proxy login	empty
$SkipTlsVerify	Disable certificate check, only if the proxy breaks TLS	$false

After a change, run client\Tunnel-Stop.cmd and start the tunnel again.

Known blockers

• On a corporate network the tunnel times out without $UpstreamProxy. See corporate proxy.
• The first start downloads wstunnel.exe from GitHub. Without access to github.com, place it in client\bin\ manually.
• Private addresses such as 192.168.x.x are blocked through the tunnel. The client log then shows Invalid status code: 400. Add them to the program's proxy exceptions.
• client\config.ps1 and server/restrictions.yaml contain the secret. Do not share or commit them.

Further documentation

• docs/installation.md — installation, corporate proxy, rotating the secret, updating, troubleshooting (German)
• wstunnel — the tunnel software used

---

Deutsch

Hinweis: Dieses Tool wurde mit Claude Code vibe coded — Architektur und Struktur wurden gemeinsam mit KI geplant, die gesamte Implementierung erfolgte per Prompt. Keine einzige Zeile wurde von Hand geschrieben.

Leitet nur Chrome und Codex über einen wstunnel-Server auf dem Raspberry Pi zu Hause ins Internet, auch hinter einem Firmen-Proxy, der Seiten sperrt.

Anders als ein Web-Proxy reicht der Tunnel reine TCP-Verbindungen durch. TLS endet beim echten Server, daher funktionieren Google- und ChatGPT-Logins.

Funktionen

• Lokaler Proxy auf 127.0.0.1:1080, den nur ein eigenes Chrome-Profil und Codex nutzen
• Tunnel als WebSocket über wss:// auf Port 443, optional durch einen Firmen-Proxy
• Zugang nur mit geheimem URL-Pfad
• Server erlaubt nur TCP 80/443 zu öffentlichen Zielen, das Heimnetz ist gesperrt
• Client ohne Admin-Rechte, läuft mit Windows PowerShell 5.1

Installation

Voraussetzungen:

• Raspberry Pi mit Docker und Nginx Proxy Manager, eigene Domain mit SSL-Zertifikat
• Windows 10/11 mit Google Chrome

Schritt-für-Schritt-Anleitung für Server und Client: docs/installation.md

Nutzung

client\Chrome-Tunnel.cmd doppelklicken. Der Tunnel startet unsichtbar im Hintergrund, danach öffnet sich ein eigenes Chrome-Fenster, das komplett über den Pi läuft.

Einmal client\PATH-eintragen.cmd ausführen. Danach in jedem Projektordner codexx statt codex eingeben, zum Beispiel im VS-Code-Terminal. Argumente werden durchgereicht.

Tunnel-Start.cmd startet nur den Tunnel. Danach 127.0.0.1:1080 in beliebigen Programmen als HTTP-Proxy eintragen. Tunnel-Status.cmd zeigt die öffentliche IP über den Tunnel. Tunnel-Stop.cmd beendet den Tunnel.

Konfiguration

Alle Client-Werte stehen in client\config.ps1 (Vorlage: config.example.ps1).

Variable	Bedeutung	Standard
$TunnelSecret	Geheimer Pfad, identisch mit dem Server	leer
$TunnelServer	Adresse des Servers	wss://deine-domain.de:443
$LocalProxy	Lokaler Proxy für Chrome und Codex	127.0.0.1:1080
$UpstreamProxy	Firmen-Proxy, leer = direkt	leer
$UpstreamProxyUser / $UpstreamProxyPassword	Anmeldung am Firmen-Proxy	leer
$SkipTlsVerify	Zertifikatsprüfung abschalten, nur bei TLS-Aufbruch	$false

Nach einer Änderung client\Tunnel-Stop.cmd ausführen und den Tunnel neu starten.

Bekannte Stolpersteine

• Im Firmennetz läuft der Tunnel ohne $UpstreamProxy in einen Timeout. Siehe Einsatz hinter einem Firmen-Proxy.
• Der erste Start lädt wstunnel.exe von GitHub. Ohne Zugriff auf github.com die Datei von Hand nach client\bin\ legen.
• Private Adressen wie 192.168.x.x sind über den Tunnel gesperrt. Das Client-Log zeigt dann Invalid status code: 400. Solche Adressen im Programm als Proxy-Ausnahme eintragen.
• client\config.ps1 und server/restrictions.yaml enthalten das Secret. Nicht weitergeben und nicht committen.

Weitere Dokumentation

• docs/installation.md — Installation, Firmen-Proxy, Secret tauschen, Aktualisieren, Fehlerbehebung
• wstunnel — verwendete Tunnel-Software