# 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