Web Terminal

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Gaurav-Gosain/tuios/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

• Full TUIOS Experience: All TUIOS features work in the browser
• WebGL Rendering: GPU-accelerated terminal rendering for smooth 60fps
• Dual Protocol Support: WebTransport (QUIC) with WebSocket fallback
• Bundled Nerd Fonts: No client-side font installation required
• Mouse Support: Full mouse interaction with cell-based optimization
• Auto-Reconnect: Automatic reconnection with exponential backoff
• Daemon Integration: Persistent sessions with multi-client support

​

Installation

brew install tuios-web

​

Quick Start

# Start web server on default port (7681)
tuios-web

# Open in browser
open http://localhost:7681

# With custom port
tuios-web --port 8080

# With TUIOS flags forwarded
tuios-web --theme dracula --show-keys

​

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Browser                               │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────┐  │
│  │  xterm.js   │◄──►│ terminal.js │◄──►│ WebTransport/WS │  │
│  │  (WebGL)    │    │  (client)   │    │   (transport)   │  │
│  └─────────────┘    └─────────────┘    └────────┬────────┘  │
└─────────────────────────────────────────────────┼───────────┘
                                                   │
                                     ┌─────────────┴─────────────┐
                                     │     QUIC (UDP:7682)       │
                                     │  or WebSocket (TCP:7681)  │
                                     └─────────────┬─────────────┘
                                                   │
┌─────────────────────────────────────────────────┼───────────┐
│                     Server                      │           │
├─────────────────────────────────────────────────┼───────────┤
│  ┌──────────────┐    ┌──────────────┐    ┌─────┴─────┐     │
│  │ HTTP Server  │    │  WT Server   │    │  Session  │     │
│  │  (static)    │    │   (QUIC)     │    │  Manager  │     │
│  │  :7681       │    │   :7682      │    └─────┬─────┘     │
│  └──────────────┘    └──────────────┘          │           │
│                                          ┌─────┴─────┐     │
│                                          │    PTY    │     │
│                                          │  (TUIOS)  │     │
│                                          └───────────┘     │
└─────────────────────────────────────────────────────────────┘

​

Key Technologies

• xterm.js: Terminal emulation in the browser
• WebGL/Canvas: Hardware-accelerated rendering
• WebTransport (QUIC): Low-latency communication over UDP
• WebSocket: Fallback for universal browser support
• JetBrains Mono Nerd Font: Bundled for proper icon rendering

​

Configuration

​

Command-Line Flags

​

Daemon Mode (Default)

# Start web server with daemon mode (default)
tuios-web

# All clients share a specific session
tuios-web --default-session shared

# Disable daemon mode (standalone sessions)
tuios-web --ephemeral

• Sessions persist when browser tabs close
• Multiple browsers/tabs can view the same session
• State (windows, workspaces) preserved across reconnections
• Integrates with tuios ls, tuios attach, and other session commands

• Terminal size uses minimum of all connected client dimensions
• State changes broadcast to all clients in real-time
• Clients notified when others join/leave

​

TUIOS Flags

# Theme and appearance
tuios-web --theme nord --border-style rounded

# Debug mode
tuios-web --debug --show-keys

# ASCII-only mode
tuios-web --ascii-only

# Disable animations for instant transitions
tuios-web --no-animations

​

Client Settings

• Transport: Auto, WebTransport, or WebSocket
• Renderer: Auto, WebGL, Canvas, or DOM
• Font Size: 10-24px

​

Transport Protocols

​

WebTransport (QUIC)

• Port: HTTP port + 1 (default: 7682)
• Protocol: HTTP/3 over QUIC (UDP)
• Benefits: Lower latency, better multiplexing, connection migration
• Requirements: Chrome 97+, Edge 97+, or compatible browser

​

WebSocket (Fallback)

• Port: Same as HTTP (default: 7681)
• Protocol: WebSocket over TCP
• Benefits: Universal browser support
• Used when: WebTransport unavailable or explicitly selected

​

Rendering

​

WebGL (Default)

• Smooth 60fps scrolling and updates
• Lower CPU usage
• Hardware-accelerated text rendering

​

Canvas (Fallback)

• Good performance on most devices
• Used when WebGL unavailable or context lost

​

DOM (Fallback)

• Most compatible option
• Higher CPU usage
• Used when Canvas addon unavailable

​

Examples

​

Example 1: Personal Web Access

# Start web server
tuios-web --port 7681

# Open in browser
open http://localhost:7681

​

Example 2: Shared Session for Team

# Start with shared default session
tuios-web --host 0.0.0.0 --port 7681 --default-session team-debug

# Team members open http://server:7681
# All see the same session in real-time

​

Example 3: Demo/Presentation Mode

# Start in read-only mode for audience
tuios-web --host 0.0.0.0 --port 7681 --read-only --default-session demo

# Presenter controls TUIOS separately
tuios attach demo

# Audience views at http://presenter:7681 (view-only)

​

Example 4: Custom Theme for Web

# Start with specific theme and features
tuios-web --theme dracula --show-keys --border-style thick

​

Performance

​

Server Optimizations

• Buffer Pools: Reusable buffers reduce GC pressure
• Atomic Counters: Lock-free connection counting
• Direct Streaming: No intermediate buffering for PTY output
• Structured Logging: charmbracelet/log with configurable levels

​

Client Optimizations

• requestAnimationFrame Batching: Terminal writes batched per frame
• Mouse Deduplication: Only sends events when cell position changes
• Pre-allocated Buffers: Reusable send/receive buffers
• Cached DOM Elements: No repeated querySelector calls

​

Typical Performance

​

Security

​

Certificate Handling

• Valid for 10 days (Chrome WebTransport requirement)
• Hash provided via /cert-hash endpoint
• No browser certificate warning needed for WebTransport

​

Production Recommendations

1. Use a reverse proxy (nginx, Caddy) with proper TLS
2. Set --host 127.0.0.1 and proxy external traffic
3. Use --max-connections to limit resource usage
4. Consider --read-only for public demos

server {
    listen 443 ssl;
    server_name terminal.example.com;

    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:7681;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

​

CORS

​

Troubleshooting

​

WebTransport Not Connecting

1. Check browser support (Chrome 97+)
2. Verify UDP port 7682 is accessible
3. Check console for certificate hash errors
4. Try forcing WebSocket in settings

​

Blank Terminal

1. Check browser console for errors
2. Verify fonts loaded (document.fonts.check())
3. Try switching renderer in settings
4. Check if TUIOS process started (server logs)

​

High Latency

1. Check network conditions
2. Prefer WebTransport over WebSocket
3. Use WebGL renderer for smoother updates
4. Check server CPU usage

​

Session Not Closing

1. Server sends MsgClose when PTY exits
2. Check for browser console errors
3. Verify session cleanup in server logs

​

Debug Mode

# Enable verbose logging
tuios-web --debug

• Connection attempts and session lifecycle
• Bytes sent/received per session
• Terminal resize events
• Error details

​

See Also

• SSH Server - SSH-based remote access
• Session Management - Managing TUIOS sessions
• CLI Reference - Complete web command reference
• Sip Library - Serve any Bubble Tea app in the browser