ttyd(1)

✨ ttyd — the manual, but make it cute ✨

okay bestie, welcome to the ttyd(1) manual page 💖 this is the User Manual energy, and we're about to make your terminal famous on the internet. no cap.

---

🌸 NAME 🌸

ttyd — share your terminal over the web 💅

---

🦋 SYNOPSIS 🦋

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

---

✨ DESCRIPTION ✨

so like, ttyd is a command-line tool for sharing your terminal over the web, and it runs on nix and windows systems. she's flexible like that 🫶 and here's the feature list, because she is *stacked:

• Built on top of Libwebsockets with libuv for speed ⚡
• Fully-featured terminal based on Xterm.js with CJK (Chinese, Japanese, Korean) and IME support 🌏
• Graphical ZMODEM integration with lrzsz support
• Sixel image output support 🖼️
• SSL support based on OpenSSL 🔒
• Run any custom command with options 👑
• Basic authentication support and many other custom options 🔥
• Cross platform: macOS, Linux, FreeBSD/OpenBSD, OpenWrt/LEDE, Windows 🌈

---

💅 OPTIONS 💅

every single one, bestie. no skipping. periodt.

• -p, --port — port to listen on (default: 7681, use 0 for a random port) 🎲
• -i, --interface — network interface to bind (eg: eth0), or a 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 USER[:PASSWORD] — credential for Basic Authentication (format: username:password) 🔐
• -H, --auth-header — HTTP Header name for auth proxy; this configures 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 the 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, see CLIENT OPTIONS for details
• -T, --terminal-type — terminal type to report, default: xterm-256color
• -O, --check-origin — do not allow websocket connection from a 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

---

🎀 CLIENT OPTIONS 🎀

so ttyd has a little mechanism where it passes server-side command-line arguments to the browser page, and that's what we call client options 💖

• -t, --client-option — send option to client (format: key=value), repeat to add more options

🌟 Basic usage 🌟

• -t rendererType=canvas — use the canvas renderer for xterm.js (default: webgl) 🎨
• -t disableLeaveAlert=true — disable the leave page alert
• -t disableResizeOverlay=true — disable the terminal resize overlay
• -t disableReconnect=true — prevent the terminal from reconnecting on connection error/close
• -t enableZmodem=true — enable ZMODEM / lrzsz file transfer support 📦
• -t enableTrzsz=true — enable trzsz file transfer support 📦
• -t enableSixel=true — enable Sixel image output support (Usage)
• -t titleFixed=hello — set a fixed title for the browser window
• -t fontSize=20 — change the font size of the terminal 🔍

💫 Advanced usage 💫

you can use the client option to change all the settings of xterm defined in ITerminalOptions, examples:

• -t cursorStyle=bar — set cursor style to bar
• -t lineHeight=1.5 — set line-height to 1.5
• -t 'theme={"background": "green"}' — set background color to green 💚

to try the example options above, run:

ttyd -t cursorStyle=bar -t lineHeight=1.5 -t 'theme={"background": "green"}' bash

---

🔥 EXAMPLES 🔥

ttyd starts a web server at port 7681 by default, and you can use the -p option to change it. the command will be started with arguments as options. for example, run:

ttyd -p 8080 bash -x

then open http://localhost:8080 with a browser, and you will get a bash shell with debug mode enabled. more examples:

• if you want to login with your system accounts on the web browser, run ttyd login.
• you can even run a none shell command like vim, try: ttyd vim, and the web browser will show you a vim editor 👑
• sharing single process with multiple clients: ttyd tmux new -A -s ttyd vim, run tmux new -A -s ttyd to connect to the tmux session from terminal.

🔒 SSL how-to 🔒

generate SSL CA and self signed server/client certificates:

# CA certificate (FQDN must be different from server/client)
openssl genrsa -out ca.key 2048
openssl req -new -x509 -days 365 -key ca.key -subj "/C=CN/ST=GD/L=SZ/O=Acme, Inc./CN=Acme Root CA" -out ca.crt

# server certificate (for multiple domains, change subjectAltName to: DNS:example.com,DNS:www.example.com)
openssl req -newkey rsa:2048 -nodes -keyout server.key -subj "/C=CN/ST=GD/L=SZ/O=Acme, Inc./CN=localhost" -out server.csr
openssl x509 -sha256 -req -extfile <(printf "subjectAltName=DNS:localhost") -days 365 -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt

# client certificate (the p12/pem format may be useful for some clients)
openssl req -newkey rsa:2048 -nodes -keyout client.key -subj "/C=CN/ST=GD/L=SZ/O=Acme, Inc./CN=client" -out client.csr
openssl x509 -req -days 365 -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt
openssl pkcs12 -export -clcerts -in client.crt -inkey client.key -out client.p12
openssl pkcs12 -in client.p12 -out client.pem -clcerts

then start ttyd:

ttyd --ssl --ssl-cert server.crt --ssl-key server.key --ssl-ca ca.crt bash

you may want to test the client certificate verification with curl(1):

curl --insecure --cert client.p12[:password] -v https://localhost:7681

if you don't want to enable client certificate verification, remove the --ssl-ca option.

🐳 Docker and ttyd 🐳

Docker containers are jailed environments which are more secure, and this is useful for protecting the host system. you may use ttyd with docker like this:

• sharing single docker container with multiple clients: docker run -it --rm -p 7681:7681 tsl0922/ttyd.
• creating new docker container for each client: ttyd docker run -it --rm ubuntu.

🌈 Nginx reverse proxy 🌈

sample config to proxy ttyd under the /ttyd path:

location ~ ^/ttyd(.*)$ {
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_pass http://127.0.0.1:7681/$1;
}

---

👑 AUTHOR 👑

Shuanglei Tao <tsl0922@gmail.com> — visit https://github.com/tsl0922/ttyd to get more information and report bugs 🐛

---

and that's the whole manual, bestie 💖 this is ttyd version ttyd(1) from way back in September 2016 — iconic behavior honestly. now go share that terminal, you main character 🫶✨