ttyd: share a terminal in your browser without handing out a shell

Install ttyd

The current release is ttyd 1.7.7, from March 30, 2024. On macOS run brew install ttyd; on Windows, winget install tsl0922.ttyd or scoop install ttyd.

On Ubuntu, sudo apt install ttyd installs it from universe: Ubuntu 26.04 ships 1.7.7 and 24.04 ships 1.7.4. Debian 13 stable has no ttyd package (testing and unstable do), so use sudo snap install ttyd --classic or a static binary from the GitHub releases page, then check it with ttyd --version.

Share a terminal in the browser

ttyd bash serves bash at http://SERVER:7681, and every browser connection gets a fresh bash of its own: in our test, two tabs got two different process IDs. Port 7681 is the default; -p 8080 picks another and -p 0 a random free one, which ttyd prints at startup.

Since ttyd 1.7.4 (October 2023) the page is read-only by default. Visitors see the output but cannot type, and ttyd logs The --writable option is not set, will start in readonly mode; add -W (--writable) to let them type.

ttyd bash          # read-only, http://SERVER:7681
ttyd -W bash       # visitors can type
ttyd -p 0 htop     # random free port

ttyd keeps running until you stop it. -o makes it exit after one client disconnects, and -q when the last client leaves.

Lock it down: address, password and TLS

ttyd 1.7.7 listens on all interfaces (0.0.0.0) with no password, so anyone who can reach the port can open the page. ttyd -W bash on a public address hands a shell as your user to whoever finds it, and even read-only mode shows every secret printed to the screen.

Bind it to localhost with -i 127.0.0.1 (or -i lo, or a UNIX socket path) and reach it through an SSH tunnel. -c user:password adds HTTP basic auth and the page returns 401 without it, but basic auth is only base64 encoding, so add TLS with -S, -C and -K.

ttyd -i 127.0.0.1 bash
ssh -L 7681:127.0.0.1:7681 user@server    # then open http://localhost:7681
ttyd -c alice:s3cret -S -C cert.pem -K key.pem bash

With TLS on, plain HTTP requests got a redirect to HTTPS in our test, and only the right credentials got a 200. -A with a CA file requires client certificates, and -O rejects WebSocket connections from other origins.

Put ttyd behind a reverse proxy

With nginx or another proxy in front, keep ttyd on 127.0.0.1 and let the proxy handle TLS. This is the ttyd wiki's nginx example; the Upgrade and Connection headers carry the WebSocket the terminal runs over.

location / {
    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;
}

If the proxy serves ttyd under a path such as /ttyd/ and passes that path through, start ttyd with -b /ttyd. If the proxy already logs users in, -H X-Auth-User (or whichever header it sets) makes ttyd require that header: in our test requests without it got 407. Anyone who reaches ttyd directly can send the header too, so keep it on 127.0.0.1.

Watch a long job without giving anyone a shell

Because each browser tab gets its own process, ttyd bash cannot show a job you already started. Run the job in tmux and serve a read-only tmux client instead.

tmux new -d -s train
tmux send-keys -t train 'python3 -u train.py' Enter
ttyd -i 127.0.0.1 tmux attach -r -t train

In our test the browser showed the job's output live, typed input never reached it, and the session kept running after the tab closed. The wiki's ttyd tmux new -A -s ttyd vim shares one session between every tab and your own terminal instead. The tmux detach and attach guide covers the session side, and tmate alternatives compares other ways to share a terminal.

Skip the port, the proxy and the shell

A browser terminal means an open port, a password and a certificate to look after, even when all you want is to see how one job is doing.