ttyd README

The project's README from github.com/tsl0922/ttyd. As one markdown file: README.md.

GitHub

ttyd is a simple command-line tool for sharing terminal over the web.

screenshot

Features

Built on top of libuv and WebGL2 for speed
Fully-featured terminal with CJK and IME support
ZMODEM (lrzsz) / trzsz file transfer support
Sixel image output support (img2sixel / lsix)
SSL support based on OpenSSL / Mbed TLS
Run any custom command with options
Basic authentication support and many other custom options
Cross platform: macOS, Linux, FreeBSD/OpenBSD, OpenWrt, Windows

Installation

Install on macOS

Install with Homebrew: brew install ttyd
Install with MacPorts: sudo port install ttyd

Install on Linux

Install on Debian/Ubuntu: sudo apt install ttyd
Install the snap: sudo snap install ttyd --classic
Install on OpenWrt: opkg install ttyd
Install on Gentoo: clone the repo and follow the directions here.
Install with Homebrew : brew install ttyd
Precompiled static binaries: download from the releases page

Install on Windows

Binary version (recommended): download from the releases page
Install with WinGet: winget install tsl0922.ttyd
Install with Scoop: scoop install ttyd
Compile on Windows

Usage

Command-line Options

USAGE:
    ttyd [options] <command> [<arguments...>]

OPTIONS:
    -p, --port              Port to listen (default: 7681, use `0` for random port)
    -i, --interface         Network interface to bind (eg: eth0), or UNIX domain socket path (eg: /var/run/ttyd.sock)
    -U, --socket-owner      User owner of the UNIX domain socket file, when enabled (eg: user:group)
    -c, --credential        Credential for basic authentication (format: username:password)
    -H, --auth-header       HTTP Header name for auth proxy, this will configure ttyd to let a HTTP reverse proxy handle authentication
    -u, --uid               User id to run with
    -g, --gid               Group id to run with
    -s, --signal            Signal to send to the command when exit it (default: 1, SIGHUP)
    -w, --cwd               Working directory to be set for the child program
    -a, --url-arg           Allow client to send command line arguments in URL (eg: http://localhost:7681?arg=foo&arg=bar)
    -W, --writable          Allow clients to write to the TTY (readonly by default)
    -t, --client-option     Send option to client (format: key=value), repeat to add more options
    -T, --terminal-type     Terminal type to report, default: xterm-256color
    -O, --check-origin      Do not allow websocket connection from different origin
    -m, --max-clients       Maximum clients to support (default: 0, no limit)
    -o, --once              Accept only one client and exit on disconnection
    -q, --exit-no-conn      Exit on all clients disconnection
    -B, --browser           Open terminal with the default system browser
    -I, --index             Custom index.html path
    -b, --base-path         Expected base path for requests coming from a reverse proxy (eg: /mounted/here, max length: 128)
    -P, --ping-interval     Websocket ping interval(sec) (default: 5)
    -6, --ipv6              Enable IPv6 support
    -S, --ssl               Enable SSL
    -C, --ssl-cert          SSL certificate file path
    -K, --ssl-key           SSL key file path
    -A, --ssl-ca            SSL CA file path for client certificate verification
    -d, --debug             Set log level (default: 7)
    -v, --version           Print the version and exit
    -h, --help              Print this text and exit

Read the example usage on the wiki.

Browser Support

Modern browsers, See Browser Support.

Alternatives

Wetty: Node based web terminal (SSH/login)
GoTTY: Go based web terminal

12.5K ·GitHub

Ttyd

What is this?

ttyd is a command-line tool that shares your terminal over the web, letting you access and interact with a terminal session through a browser.

Is this a GUI app or a CLI tool?

It's a CLI tool: you run the `ttyd` command with your desired shell/program, and it starts a web server that streams that terminal session to connected browsers.

How do I install and run it?

Install via a package manager for your OS (Homebrew/MacPorts on macOS, apt/snap on Linux, WinGet/Scoop on Windows, opkg on OpenWrt) or grab a precompiled static binary from the releases page, then run ttyd with the command you want to expose.

What does it need under the hood to work?

It's built on libuv and WebGL2 for the terminal rendering, with SSL support provided via OpenSSL or Mbed TLS.

Does it work on any browser?

It requires a modern browser; there's a dedicated browser support page listing which ones are compatible.

Does it only run on Linux/macOS?

No, it's cross-platform: macOS, Linux, FreeBSD/OpenBSD, OpenWrt, and Windows are all supported.

Does it support file transfers over the terminal?

Yes, ttyd supports ZMODEM (lrzsz) and trzsz file transfer directly in the terminal session.

Can it show images in the terminal?

Yes, it supports Sixel image output, so tools like img2sixel or lsix can display images in the web terminal.

Does it support non-ASCII input like Chinese or Japanese?

Yes, it's a fully-featured terminal with CJK and IME support built in.

Are there alternatives to ttyd?

The README mentions Wetty (Node-based web terminal with SSH/login) and GoTTY (Go-based web terminal) as alternatives.

What are similar projects?

websocketd, xterm.js, WindTerm, upterm, gotty, tailcat, xpra, smartdns

Which topics is it in?

xterm, tty, openwrt, ssl, terminal-emulators, websockets, remote-access, websocket, c, command-line, networking, command-line-tool

Creator: tsl0922
Size: 20.1 MB
Stars: 12.5K
Updated: CommitAug 12 Release1.7.7Mar 30
Age: 10y
Commits · 90 Days