Mortdecai
138 lines
4.8 KiB
Markdown
138 lines
4.8 KiB
Markdown
# kitty-web
|
|
|
|
Mobile-first web terminal powered by [ttyd](https://github.com/tsl0922/ttyd) + [tmux](https://github.com/tmux/tmux). One persistent tmux session, multiple tabs, accessible from any browser. Designed for phones and tablets.
|
|
|
|
## Features
|
|
|
|
- **Single persistent session** — one tmux session shared across all connected clients
|
|
- **Mobile touch toolbar** — on-screen buttons for common shortcuts (new tab, ^C, ^D, Esc, arrows, split panes, etc.)
|
|
- **Text selection mode** — tap `Sel` to enter selection mode, long-press to select and copy text, tap `Done` to resume typing
|
|
- **Push notifications** — send browser notifications from any terminal command
|
|
- **PWA installable** — add to home screen for an app-like experience
|
|
- **Dark theme** — styled for dark-mode terminals with orange accents
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Browser -> Caddy (HTTPS + Auth) -> ttyd (port 7681) -> tmux session
|
|
-> notify-server (port 7682) -> /api/notifications
|
|
```
|
|
|
|
- **ttyd** serves the terminal UI with a custom index page that loads `toolbar.js`
|
|
- **toolbar.js** injects the mobile toolbar (shortcut buttons, selection mode) into the page at runtime
|
|
- **notify-server.py** provides a simple HTTP endpoint for push notifications
|
|
- **kitty-notify** is a CLI command to trigger notifications from scripts
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
sudo ./install.sh
|
|
```
|
|
|
|
This installs ttyd, tmux, systemd services, and the notification system. The terminal will be available at `http://YOUR_IP:7681`.
|
|
|
|
### Configuration
|
|
|
|
Set environment variables before running the installer:
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `KITTY_USER` | `rdp` | System user that owns the tmux session |
|
|
| `TTYD_PORT` | `7681` | Port for ttyd web terminal |
|
|
| `NOTIFY_PORT` | `7682` | Port for notification API |
|
|
| `FONT_SIZE` | `18` | Terminal font size (optimized for mobile) |
|
|
|
|
### Reverse Proxy
|
|
|
|
See `caddy-example.conf` for a complete Caddy v2 configuration with authentication. The setup supports OAuth2 Proxy, Authentik, or Authelia for access control.
|
|
|
|
Key requirements for the reverse proxy:
|
|
- WebSocket support (ttyd uses WebSockets for terminal I/O)
|
|
- Serve `/toolbar.js`, `/manifest.json`, `/icon-*.png` as static files
|
|
- Proxy `/api/*` to the notification server (port 7682)
|
|
- Proxy everything else to ttyd (port 7681)
|
|
|
|
## Mobile Toolbar
|
|
|
|
The toolbar appears automatically on screens narrower than 900px. Buttons:
|
|
|
|
| Button | Action | tmux Key |
|
|
|--------|--------|----------|
|
|
| **+Tab** | New tab | `Ctrl-A c` |
|
|
| **Next** | Next tab | `Ctrl-A n` |
|
|
| **Prev** | Previous tab | `Ctrl-A p` |
|
|
| **^C** | Interrupt | `Ctrl-C` |
|
|
| **^D** | EOF / logout | `Ctrl-D` |
|
|
| **Clr** | Clear screen | `Ctrl-L` |
|
|
| **Esc** | Escape key | `Escape` |
|
|
| **Tab** | Tab completion | `Tab` |
|
|
| **Up/Down** | History navigation | Arrow keys |
|
|
| **Sel** | Toggle text selection mode | — |
|
|
| **Spl** | Split pane vertically | `Ctrl-A %` |
|
|
| **Pane** | Cycle between panes | `Ctrl-A o` |
|
|
| **Kill** | Kill current pane/tab | `Ctrl-A x` |
|
|
|
|
## Push Notifications
|
|
|
|
Send notifications from any terminal session:
|
|
|
|
```bash
|
|
# Direct message
|
|
kitty-notify "Build complete!"
|
|
|
|
# Pipe output
|
|
echo "Deploy finished" | kitty-notify
|
|
|
|
# Use in scripts
|
|
make build && kitty-notify "Build succeeded" || kitty-notify "Build FAILED"
|
|
```
|
|
|
|
Notifications appear as browser push notifications on mobile. Tap the bell icon in the terminal UI to enable them. Notifications expire after 30 seconds.
|
|
|
|
## tmux Keybindings
|
|
|
|
The included tmux config uses `Ctrl-A` as the prefix (easier on mobile than the default `Ctrl-B`):
|
|
|
|
| Key | Action |
|
|
|-----|--------|
|
|
| `Ctrl-A c` | New window/tab |
|
|
| `Ctrl-A n` / `Ctrl-A p` | Next / previous window |
|
|
| `Ctrl-A %` / `Ctrl-A "` | Split vertical / horizontal |
|
|
| `Ctrl-A o` | Cycle panes |
|
|
| `Ctrl-A x` | Kill pane |
|
|
| `Alt-1` through `Alt-5` | Jump to window 1-5 |
|
|
| `Alt-Left` / `Alt-Right` | Previous / next window |
|
|
| `Alt-t` | New window |
|
|
| Mouse scroll | Scroll through history |
|
|
|
|
## Files
|
|
|
|
```
|
|
kitty-web/
|
|
toolbar.js # Mobile toolbar (injected into ttyd page)
|
|
notify-server.py # Push notification HTTP API
|
|
kitty-notify # CLI notification command
|
|
manifest.json # PWA manifest
|
|
icon-192.png # PWA icon (192x192)
|
|
icon-512.png # PWA icon (512x512)
|
|
install.sh # Installer script
|
|
caddy-example.conf # Reverse proxy configuration example
|
|
config/
|
|
tmux.conf # tmux configuration (dark theme, mobile-friendly)
|
|
systemd/
|
|
ttyd-kitty.service # ttyd systemd unit
|
|
kitty-notify.service # Notification API systemd unit
|
|
```
|
|
|
|
## Requirements
|
|
|
|
- Linux (Debian/Ubuntu tested)
|
|
- tmux
|
|
- Python 3 (for notification server)
|
|
- [ttyd](https://github.com/tsl0922/ttyd) (installed automatically)
|
|
- Caddy, nginx, or another reverse proxy (for HTTPS and auth)
|
|
|
|
## License
|
|
|
|
MIT
|