# kitty-web

Run the real [kitty terminal](https://sw.kovidgoyal.net/kitty/) in your browser via [Xpra](https://xpra.org/) HTML5 streaming.

This is not a JavaScript terminal emulator — it's the actual kitty with GPU rendering, image protocol, ligatures, and native tabs, streamed to your browser.

## Features

- **Real kitty** — GPU rendering, kitty image protocol, all features intact
- **Native kitty tabs/splits** — `Ctrl+Shift+T`, layouts, everything works
- **Persistent session** — close browser, reconnect later, session is still there
- **Multi-client** — multiple browsers can connect simultaneously
- **Mobile-friendly** — Xpra HTML5 client handles touch, scaling, on-screen keyboard

## Architecture

```
Browser -> Caddy (HTTPS + Auth) -> Xpra HTML5 (port 7681) -> kitty (Xvfb)
```

Xpra runs kitty in a virtual X display and streams the rendered pixels to browsers via WebSocket.

## Setup

### Prerequisites

```bash
# Add Xpra repo
curl -sL https://xpra.org/xpra.asc | sudo tee /usr/share/keyrings/xpra.asc
echo "deb [signed-by=/usr/share/keyrings/xpra.asc] https://xpra.org/ $(lsb_release -cs) main" | \
  sudo tee /etc/apt/sources.list.d/xpra.list
sudo apt update && sudo apt install -y xpra kitty
```

### Install

```bash
sudo cp systemd/kitty-web.service /etc/systemd/system/
sudo cp config/kitty.conf /home/YOUR_USER/.config/kitty/kitty.conf
sudo cp config/xpra-html5-settings.txt /usr/share/xpra/www/default-settings.txt
sudo systemctl daemon-reload
sudo systemctl enable --now kitty-web
```

Open `http://YOUR_IP:7681` in a browser.

### Reverse Proxy (Caddy)

```
kitty.example.com {
    # your auth here
    reverse_proxy YOUR_SERVER:7681
}
```

## Mobile Tips

- **Floating menu** (circle in corner) — on-screen keyboard, fullscreen, clipboard, scaling
- **Pinch to zoom** works
- **Kitty tab bar** at bottom — touch to switch tabs
- DPI set to 144 for readable text on mobile

## Files

```
kitty-web/
  config/
    kitty.conf                # Kitty config (dark theme, 16pt, mobile-optimized)
    xpra-html5-settings.txt   # Xpra HTML5 client defaults
  systemd/
    kitty-web.service         # Xpra + kitty systemd unit
  caddy-example.conf          # Reverse proxy template
```

## See Also

- [sethmux](https://git.sethpc.xyz/Seth/sethmux) — lightweight web terminal (ttyd + tmux) at `mux.sethpc.xyz`

## License

MIT