Arkitektur

Overordnet flow

Standard (lokal tmux + tunnel):

Browser (phone)
  |
  | HTTPS
  v
Cloudflare Quick Tunnel
  |
  | HTTP/WS
  v
Local Termbridge server
  |
  | PTY
  v
Tmux session

Direkte sandkassetilstand (Daytona, uden tunnel):

Browser (phone)
  |
  | HTTPS
  v
Daytona preview link
  |
  | HTTP/WS
  v
Termbridge server (sandbox)
  |
  | PTY
  v
Tmux session (sandbox)

Når --no-tunnel er angivet, springer Termbridge Cloudflare over og bruger den offentlige URL, du har angivet.

Komponenter

CLI-proces

• Starter HTTP-serveren, der leverer UI-aktiverne.
• Starter WebSocket-serveren til terminalens I/O.
• Opretter en eller flere tmux-sessioner (eller Daytona-PTY'er).
• Udsteder engangstokens til indløsning.
• Starter og overvåger tunnelen, når den er aktiveret (Cloudflare i dag).
• I direkte sandkassetilstand starter den Termbridge i sandkassen og venter på delings-URL.

Terminalbackend

• tmux-backend: Bruger node-pty til at oprette forbindelse til tmux for at håndtere faktiske tastetryk og output.
• Daytona-backend: Bruger Daytona-PTY'er i en sandkasse.
• Angiver TERM=xterm-256color og COLORTERM=truecolor for fuld farveunderstøttelse.
• For tmux deaktiveres statuslinjen tmux, så UI holdes ryddelig.

Terminalregister

• Holder styr på tilgængelige terminalsessioner.
• Leverer en liste til UI og validerer valgte terminal-id'er.

Godkendelse og session

• Engangstokenet vises som en URL og indlejres i en QR-kode.
• GET /__tb/s/:token indløser tokenet og opretter en cookiesession.
• WebSocket-forbindelser kræver en gyldig sessionscookie og CSRF-token.
• CSRF-tokenet hentes via GET /__tb/api/csrf og sendes som en WebSocket-forespørgselsparameter.

Proxytilstand

Når --proxy <port> angives:

• Alle termbridge-ruter ligger under præfikset /__tb/
• Forespørgsler, der ikke er /__tb/, videresendes til målappen
• UI viser Terminal- og Preview-visninger via visningsvælgeren
• Preview-visningen indlæser en iframe, der peger på /
• WebSocket-forbindelser til HMR videresendes til målet

Sikkerhed

• CSRF-beskyttelse: WebSocket-opgraderinger kræver et CSRF-token for at forhindre kapring på tværs af websteder.
• Inputgrænser: 64KB HTTP-indhold, 1MB WebSocket-meddelelse, 64KB terminalinput pr. meddelelse.
• Begrænsning af anmodninger: Grænser pr. IP for tokenindløsning og WebSocket-forbindelser.

API-endpoints

Alle ruter ligger under præfikset /__tb/ for at undgå konflikter med proxiede apps:

• GET /__tb/healthz - sundhedstjek
• GET /__tb/s/:token - tokenindløsning → cookie → omdirigering
• GET /__tb/api/terminals - vis terminaler
• GET /__tb/api/csrf - hent CSRF-token til WebSocket
• GET /__tb/api/config - hent konfiguration (proxyPort, devProxyUrl)
• POST /__tb/api/terminals - opret en ny tmux-session
• GET /__tb/app/* - SPA-fallback
• WS /__tb/ws/terminal/:terminalId?csrf=<token> - stream terminalens I/O

Når proxytilstand er aktiveret:

• GET / - omdirigerer til den proxiede app (eller /__tb/app, hvis deaktiveret)
• * /* - videresendes til målappen

WebSocket-protokol

Klient -> server:

{ "type": "input", "data": "ls -la" }
{ "type": "resize", "cols": 120, "rows": 32 }
{ "type": "control", "key": "ctrl_c" }

Server -> klient:

{ "type": "output", "data": "..." }
{ "type": "status", "state": "connected" }

UI-stak

• Vite + TanStack Router
• xterm.js + Fit-tilføjelse + WebGL-renderer
• Mobilvenligt layout med fast inputlinje
• Automatisk genforbindelse med eksponentiel ventetid (op til 10 forsøg)
• Indikator for forbindelsesstatus