Web Terminal

Access TUIOS from any modern web browser with hardware-accelerated rendering and low-latency connections.

Installation

brew install tuios-web

yay -S tuios-web-bin
# or
paru -S tuios-web-bin

go install github.com/Gaurav-Gosain/tuios/cmd/tuios-web@latest

Quick Start

tuios-web

open http://localhost:7681

Features

• WebGL Rendering - GPU-accelerated terminal at 60fps
• Dual Protocols - WebTransport (QUIC) with WebSocket fallback
• Bundled Fonts - JetBrains Mono Nerd Font included
• Settings Panel - Configure transport, renderer, font size
• Mouse Support - Full interaction with cell-based optimization
• Auto-Reconnect - Automatic reconnection with backoff
• Read-Only Mode - View-only sessions for demos

Command Reference

tuios-web [flags]

Flags

TUIOS Flags

All TUIOS flags are forwarded to the spawned instance:

# With theme
tuios-web --theme dracula

# With show-keys overlay
tuios-web --show-keys

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

# Multiple flags
tuios-web --theme nord --ascii-only --debug

Client Settings

Click the ⚙ button in the top-right corner to access settings:

Transport

Renderer

Font Size

Adjustable from 10px to 24px. Settings persist in localStorage.

Architecture

Message Protocol

Reverse Proxy Setup

For production deployments, put TUIOS behind a reverse proxy with proper TLS.

Cloudflare Tunnel

Cloudflare Tunnels provide secure access without opening ports.

# macOS
brew install cloudflare/cloudflare/cloudflared

# Linux
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
chmod +x cloudflared
sudo mv cloudflared /usr/local/bin/

cloudflared tunnel login

cloudflared tunnel create tuios

tunnel: <your-tunnel-id>
credentials-file: /path/to/credentials.json

ingress:
  - hostname: tuios.yourdomain.com
    service: http://localhost:7681
  - service: http_status:404

# Terminal 1: Start TUIOS web server
tuios-web --host 127.0.0.1

# Terminal 2: Start tunnel
cloudflared tunnel run tuios

cloudflared tunnel route dns tuios tuios.yourdomain.com

Nginx

server {
    listen 80;
    server_name tuios.example.com;

    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;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 86400;
    }
}

server {
    listen 443 ssl http2;
    server_name tuios.example.com;

    ssl_certificate /etc/letsencrypt/live/tuios.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/tuios.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;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400;
        proxy_send_timeout 86400;
    }
}

server {
    listen 80;
    server_name tuios.example.com;
    return 301 https://$server_name$request_uri;
}

Caddy

Caddy automatically handles TLS certificates:

tuios.example.com {
    reverse_proxy localhost:7681
}

Traefik

# docker-compose.yml
services:
  tuios:
    image: ghcr.io/gaurav-gosain/tuios:latest
    command: web --host 0.0.0.0
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.tuios.rule=Host(`tuios.example.com`)"
      - "traefik.http.routers.tuios.entrypoints=websecure"
      - "traefik.http.routers.tuios.tls.certresolver=letsencrypt"
      - "traefik.http.services.tuios.loadbalancer.server.port=7681"

Security Considerations

Development Mode

By default, TUIOS generates a self-signed certificate for WebTransport:

• Valid for 10 days (Chrome requirement for serverCertificateHashes)
• Certificate hash provided via /cert-hash endpoint
• No browser warning for WebTransport connections

Production Recommendations

Basic Auth with Nginx

location / {
    auth_basic "TUIOS";
    auth_basic_user_file /etc/nginx/.htpasswd;
    
    proxy_pass http://127.0.0.1:7681;
    # ... rest of proxy config
}

Create password file:

htpasswd -c /etc/nginx/.htpasswd username

Performance

Server Optimizations

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

Client Optimizations

• requestAnimationFrame Batching - Writes batched per frame
• Mouse Deduplication - Only sends on cell position change
• Pre-allocated Buffers - Reusable send/receive buffers
• Cached DOM Elements - No repeated queries

Typical Metrics

Troubleshooting

WebTransport Not Connecting

1. Check browser support - Chrome 97+, Edge 97+
2. Verify UDP port - Port 7682 must be accessible
3. Check console - Look for certificate hash errors
4. Force WebSocket - Use settings panel to switch

Blank Terminal

1. Check console - Look for JavaScript errors
2. Verify fonts - Check if fonts loaded
3. Try different renderer - Switch in settings
4. Check server logs - Verify TUIOS process started

High Latency

1. Check network - Run speed test
2. Prefer WebTransport - Lower latency than WebSocket
3. Use WebGL - Hardware acceleration
4. Check server CPU - May be overloaded

Session Not Closing

When TUIOS quits (pressing q), the web session should close automatically. If not:

1. Check browser console for errors
2. Verify server logs show session cleanup
3. Refresh browser to start new session

Debug Mode

tuios-web --debug

Server logs include:

• Connection attempts
• Session lifecycle
• Bytes sent/received
• Terminal resize events
• Error details

Examples

Public Demo Server

# Read-only with connection limit
tuios-web \
  --host 0.0.0.0 \
  --port 7681 \
  --read-only \
  --max-connections 50 \
  --theme dracula

Development with Hot Reload

# With debug logging
tuios-web --debug --show-keys

Docker Deployment

docker run -it --rm \
  -p 7681:7681 \
  -p 7682:7682/udp \
  ghcr.io/gaurav-gosain/tuios:latest \
  web --host 0.0.0.0

Systemd Service

# /etc/systemd/system/tuios-web.service
[Unit]
Description=TUIOS Web Terminal
After=network.target

[Service]
Type=simple
User=tuios
ExecStart=/usr/local/bin/tuios-web --host 127.0.0.1 --port 7681
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl enable tuios-web
sudo systemctl start tuios-web

Related Documentation