Web Interface Mode

Web Interface Mode (--web)

Mastui includes a high-performance, built-in web terminal server that lets you run Mastui in any modern web browser without installing terminal emulators or SSH clients.

mastui --web

When started with --web, Mastui hosts a local asynchronous HTTP/WebSocket server, opens your default web browser, and streams the interactive Textual TUI interface directly to an embedded Xterm.js terminal canvas.

---

🚀 Quick Usage

# 1. Start Mastui in web mode (opens default browser at http://127.0.0.1:8000)
mastui --web

# 2. Bind to custom port
mastui --web --web-port 8080

# 3. Headless / Server mode (bind to all network interfaces without opening a local browser)
mastui --web --web-host 0.0.0.0 --web-port 8080 --no-browser

Command-Line Arguments

Flag	Default	Description
--web	False	Enables Web Browser / WebView mode.
--web-host <HOST>	127.0.0.1	IP address to bind the web server. Use 0.0.0.0 to allow external access.
--web-port <PORT>	8000	TCP port for HTTP and WebSocket communication.
--no-browser	False	Suppresses automatically launching the system web browser on startup.

---

🏗️ Technical Architecture

The web interface is implemented in mastui/web.py with zero external server dependencies (using Python's standard library asyncio and http.server foundations):

┌────────────────────────────────────────────────────────┐
│ Modern Web Browser / Mobile Device                     │
│  - Xterm.js Terminal with DOM Renderer                 │
│  - Custom Unicode 15+ Emoji Provider (💖, Flags, etc.) │
│  - Automatic Viewport Resize & FitAddon                │
└───────────────────────────▲────────────────────────────┘
                            │ WebSocket (RFC 6455)
┌───────────────────────────▼────────────────────────────┐
│ Mastui Web Bridge (mastui.web)                         │
│  - Rolling Terminal History Replay Buffer (500k chars) │
│  - Asynchronous PTY / Pipe Multiplexer                 │
│  - UTF-8 Incremental Decoder & XTermParser             │
└───────────────────────────▲────────────────────────────┘
                            │ PTY / Pipe Driver
┌───────────────────────────▼────────────────────────────┐
│ Mastui Textual Application (mastui.app)               │
│  - Timelines, Compose Dialogs, Themes, Keymaps         │
└────────────────────────────────────────────────────────┘

Key Technical Features

1. RFC 6455 Compliant WebSocket Server: Lightweight, handshake-validated bidirectional communication.
2. Rolling History Replay Buffer: Caches early ANSI escape sequences emitted during app initialization. When a browser connects (or reconnects after a network drop), the full screen state is replayed immediately.
3. Advanced Unicode 15+ Provider: Registers an accurate character width provider covering modern emoji planes, sparkling heart (U+1F496), skin-tone modifiers, and Regional Indicator country flags (U+1F1E6-U+1F1FF, width 1 per symbol, 2 per flag pair) ensuring seamless cell alignment without visual gaps.
4. Fallback PipeDriver: Operates both with native Unix pseudo-terminals (pty.openpty()) and in restricted environments via bidirectional non-blocking OS pipes.

---

🌐 Remote Hosting & VPS Deployment

Running Mastui on a home server, Raspberry Pi, or cloud VPS allows you to access your Mastodon feeds from anywhere.

Running with Systemd

Create /etc/systemd/system/mastui-web.service:

[Unit]
Description=Mastui Web Interface
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/home/youruser
ExecStart=/usr/local/bin/mastui --web --web-host 127.0.0.1 --web-port 8080 --no-browser
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now mastui-web

---

Reverse Proxy Configuration

To expose Mastui securely over HTTPS with Let's Encrypt, configure a reverse proxy.

Nginx Configuration

server {
    server_name mastui.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        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 86400s;
        proxy_send_timeout 86400s;
    }
}

Caddy Configuration

mastui.yourdomain.com {
    reverse_proxy 127.0.0.1:8080
}

---

📱 Mobile & Tablet Support

When accessing Mastui Web on a mobile browser or tablet:

• Responsive Viewport: The terminal canvas automatically recalculates column and row dimensions on screen orientation changes.
• On-Screen Keyboard: Tapping the terminal opens the virtual keyboard.
• Touch-Friendly Modals: Dialog buttons, language selectors, and options switches respond to touch taps.