kitty-web

Mobile-first web terminal powered by ttyd + 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

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)

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:

# 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 (installed automatically)
Caddy, nginx, or another reverse proxy (for HTTPS and auth)

License

MIT

4.8 KiB Raw Blame History