Arhitectură

Fluxul general

Implicit (local tmux + tunel):

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

Mod sandbox direct (Daytona, fără tunel):

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

Când este setat --no-tunnel, Termbridge omite Cloudflare și folosește URL public furnizat de dumneavoastră.

Componente

Procesul CLI

• Pornește serverul HTTP care servește resursele UI.
• Pornește serverul WebSocket pentru I/O-ul terminalului.
• Creează una sau mai multe sesiuni tmux (sau PTY-uri Daytona).
• Emite tokenuri de revendicare cu o singură utilizare.
• Pornește și monitorizează tunelul când este activat (Cloudflare în prezent).
• În modul sandbox direct, lansează Termbridge în sandbox și așteaptă linkul de partajare URL.

Backendul terminalului

• Backend tmux: Folosește node-pty pentru a se conecta la tmux și a transmite apăsările de taste și ieșirea în timp real.
• Backend Daytona: Folosește PTY-uri Daytona în interiorul unui sandbox.
• Setează TERM=xterm-256color și COLORTERM=truecolor pentru suport complet al culorilor.
• Pentru tmux, dezactivează bara de stare tmux pentru a păstra curat UI.

Registrul terminalelor

• Urmărește sesiunile de terminal disponibile.
• Oferă o listă pentru UI și validează ID-urile terminalelor selectate.

Autentificare și sesiune

• Tokenul cu o singură utilizare este afișat ca URL și codificat într-un cod QR.
• GET /__tb/s/:token revendică tokenul și setează o sesiune prin cookie.
• Conexiunile WebSocket necesită un cookie de sesiune valid și un token CSRF.
• Tokenul CSRF este preluat prin GET /__tb/api/csrf și transmis ca parametru în interogarea WebSocket.

Modul proxy

Când se transmite --proxy <port>:

• Toate rutele termbridge se află sub prefixul /__tb/
• Cererile care nu sunt /__tb/ sunt direcționate prin proxy către aplicația țintă
• UI afișează vizualizările Terminal/Preview prin comutatorul Views
• Vizualizarea Preview încarcă un iframe care indică spre /
• Conexiunile WebSocket pentru HMR sunt redirecționate către țintă

Securitate

• Protecție CSRF: upgrade-urile WebSocket necesită un token CSRF pentru a preveni deturnarea între site-uri.
• Limite de intrare: corp HTTP de 64KB, mesaj WebSocket de 1MB, intrare în terminal de 64KB per mesaj.
• Limitarea ratei: limite per IP pentru revendicarea tokenurilor și conexiunile WebSocket.

Endpointuri API

Toate rutele se află sub prefixul /__tb/ pentru a evita conflictele cu aplicațiile direcționate prin proxy:

• GET /__tb/healthz - verificare a stării
• GET /__tb/s/:token - revendicare token → cookie → redirecționare
• GET /__tb/api/terminals - listare terminale
• GET /__tb/api/csrf - obținere token CSRF pentru WebSocket
• GET /__tb/api/config - obținere configurație (proxyPort, devProxyUrl)
• POST /__tb/api/terminals - creare sesiune nouă tmux
• GET /__tb/app/* - fallback SPA
• WS /__tb/ws/terminal/:terminalId?csrf=<token> - transmitere I/O terminal

Când modul proxy este activat:

• GET / - redirecționează către aplicația prin proxy (sau /__tb/app dacă este dezactivat)
• * /* - direcționat prin proxy către aplicația țintă

Protocol WebSocket

Client -> server:

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

Server -> client:

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

Stiva UI

• Vite + TanStack Router
• xterm.js + extensia Fit + randare WebGL
• Interfață concepută pentru mobil, cu bară de introducere fixă
• Reconectare automată cu pauze exponențiale (până la 10 încercări)
• Indicator al stării conexiunii