Seth/kitty-web
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

refactor: strip tmux/ttyd artifacts, kitty-web is now purely xpra+kitty

Browse Source 
tmux web terminal moved to sethmux (git.sethpc.xyz/Seth/sethmux)
This commit is contained in:
Mortdecai
2026-03-26 19:00:07 -04:00
parent dcf9a53309
commit 51e8932dde
9 changed files with 32 additions and 295 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+32 -80
View File
@@ -1,129 +1,81 @@
# kitty-web
Run the real [kitty terminal](https://sw.kovidgoyal.net/kitty/) in your browser. Mobile-friendly, GPU-accelerated, with full tab and split support.
Run the real [kitty terminal](https://sw.kovidgoyal.net/kitty/) in your browser via [Xpra](https://xpra.org/) HTML5 streaming.
Powered by [Xpra](https://xpra.org/) — serves kitty as an HTML5 application via its built-in web client. This is not a terminal emulator in JavaScript; it's the actual kitty running on your server, streamed to your browser.
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, ligatures, image protocol, all of it
- **Kitty tabs and splits** — native `ctrl+shift+t`, splits, layouts
- **Persistent session** — close the browser, reconnect later, everything is still there
- **Multi-client** — multiple browsers can view/interact with the same session
- **Mobile-friendly** — Xpra's HTML5 client handles touch input, keyboard, and scaling
- **Push notifications** — optional notification API for long-running commands
- **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
Browser -> Caddy (HTTPS + Auth) -> Xpra HTML5 (port 7681) -> kitty (Xvfb)
```
Xpra runs kitty inside a virtual X display (Xvfb) and streams the rendered output to browsers via WebSocket. The HTML5 client handles input, clipboard, and display scaling.
Xpra runs kitty in a virtual X display and streams the rendered pixels to browsers via WebSocket.
## Quick Start
## Setup
### Prerequisites
- Debian/Ubuntu (tested on Debian 13 Trixie)
- kitty (`apt install kitty`)
- Xpra (`https://xpra.org/` — add their repo for latest version)
### Install
```bash
# Add Xpra repo (Debian example)
# 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
```
# Create a service user (optional)
sudo useradd -m -s /bin/bash rdp
### Install
# Install systemd service
```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
```
### Manual Start
```bash
xpra start --bind-ws=0.0.0.0:7681 \
--start="kitty" \
--html=on \
--sharing=yes \
--no-daemon
```
Then open `http://YOUR_IP:7681` in a browser.
### Configuration
Edit `systemd/kitty-web.service` to customize:
| Option | Description |
|--------|-------------|
| `--bind-ws=HOST:PORT` | WebSocket listen address |
| `--start="CMD"` | Application to launch (default: `kitty`) |
| `--sharing=yes` | Allow multiple clients to connect |
| `--readonly=no` | Allow keyboard/mouse input |
Open `http://YOUR_IP:7681` in a browser.
### Reverse Proxy (Caddy)
```
terminal.example.com {
# Add your auth here (OAuth2 Proxy, Authentik, etc.)
kitty.example.com {
# your auth here
reverse_proxy YOUR_SERVER:7681
}
```
WebSocket support is required. Caddy handles this automatically. See `caddy-example.conf` for a full example with authentication options.
## Mobile Tips
### Kitty Config
Place your kitty config at `~/.config/kitty/kitty.conf` for the service user. See `config/kitty.conf` for a dark-themed example.
## Optional: Push Notifications
The `notify-server.py` and `kitty-notify` command provide a simple browser notification system:
```bash
# Install
sudo cp notify-server.py /opt/kitty-web/
sudo cp kitty-notify /usr/local/bin/
sudo cp systemd/kitty-notify.service /etc/systemd/system/
sudo systemctl enable --now kitty-notify
# Usage
kitty-notify "Build complete!"
echo "done" | kitty-notify
```
Requires proxying `/api/*` to port 7682 — see `caddy-example.conf`.
- **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/
README.md
LICENSE
install.sh # Automated installer
caddy-example.conf # Reverse proxy config template
notify-server.py # Push notification HTTP API (optional)
kitty-notify # CLI notification command (optional)
manifest.json # PWA manifest
icon-192.png # PWA icon
icon-512.png # PWA icon
config/
tmux.conf # tmux config (for optional tmux-inside-kitty usage)
kitty.conf # Kitty terminal config (dark theme)
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
kitty-notify.service # Notification API systemd unit
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