Web Terminal

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

Installation

brew tap Gaurav-Gosain/tap
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
• 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-web starts the daemon automatically. If the daemon cannot be started it falls back to ephemeral mode silently, so sessions that you expected to persist will not.

Forwarded TUIOS Flags

Nine TUIOS flags are forwarded to the spawned instance: --debug, --ascii-only, --theme, --border-style, --dockbar-position, --hide-window-buttons, --scrollback-lines, --show-keys, and --no-animations.

tuios-web also sets TERM=xterm-kitty and TERM_PROGRAM=tuios-web for every session it spawns.

# 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

The code is the ASCII character '0' through '7' (bytes 0x30 to 0x37), not the raw byte values 0 to 7. It is the first byte of each frame.

Graphics in the Browser

Inline images work in the web client, but a narrower set of the Kitty graphics protocol is supported than in a native terminal.

Works: direct base64 transmission (t=d), the placement and deletion actions, RGB and RGBA and PNG formats, zlib compression, chunked transmission, source-region clipping, and repositioning on scroll. Sixel graphics also work.

Does not work: file transmission (t=f), temporary-file transmission (t=t), shared memory (t=s, including /dev/shm), the animation protocol (a=f, a=a, a=c), and Unicode placeholders (U=1).

The practical consequence is that a program which insists on passing a file path or a shared memory handle gets no image. mpv --vo=kitty is the common case: it prefers shared memory, which the browser client cannot read.

There is one conservative edge: the host probe shares a 300 ms budget, so a host that supports file transmission but answers slowly is treated as if it does not. That costs a server-side read and re-encode per frame rather than breaking anything, and there is no environment variable to force it back on.

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:
    # Build this yourself; no published image ships tuios-web.
    image: tuios-web:local
    command: ["--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.routers.tuios.middlewares=tuios-auth"
      - "traefik.http.middlewares.tuios-auth.basicauth.usersfile=/etc/traefik/htpasswd"
      - "traefik.http.services.tuios.loadbalancer.server.port=7681"

The basicauth middleware is doing the access control here. Without it this configuration publishes an unauthenticated shell on a public hostname.

Security Considerations

There is no authentication

Putting authentication in front of it

Because the server has no authentication of its own, a reverse proxy is the only place to add it. This is a requirement for any use beyond a local session you are actively watching, not a hardening tip.

WebTransport certificates

The server generates a self-signed certificate for WebTransport:

• Valid for 10 days, which is Chrome's limit for serverCertificateHashes
• The hash is served from the /cert-hash endpoint
• No browser warning is shown for the WebTransport connection

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

Measured Performance

There is no benchmark in the repository for the web path, so no latency, memory, or event-filtering figures are claimed here. The optimisations above are real code, but their effect has not been measured and published.

If you need numbers for your own deployment, measure them on your own hardware and network. Local latency is dominated by the transport in use, and WebTransport is only available when the browser reaches the server on 127.0.0.1.

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

FROM golang:1.25 AS build
WORKDIR /src
COPY . .
RUN go build -o /out/tuios-web ./cmd/tuios-web

FROM debian:bookworm-slim
COPY --from=build /out/tuios-web /usr/local/bin/tuios-web
EXPOSE 7681
ENTRYPOINT ["tuios-web", "--host", "0.0.0.0"]

Remember that this exposes an unauthenticated shell. See Security Considerations.

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