Skip to content
Get packs

Guide · Open source

How to use ttyd: share a terminal over the web

Updated · written with AI from the project's own documentation and checked against our catalogue data

ttyd is a command-line tool that runs a program on your machine and serves it as a terminal you can open in a web browser. This guide shows you how to install it, start it, protect it with credentials and SSL, and decide whether it fits your use. Anyone with the address (and credentials, if you set them) can see the terminal, and can type into it if you allow writing.

ttydtsl0922/ttyd · ★ 12.6k · MIT

Quick start

  1. 1Install ttyd. Install it with your package manager, such as brew install ttyd on macOS or sudo apt install ttyd on Debian or Ubuntu.
  2. 2Pick a command. Decide what program the browser should show, such as bash, and place it after ttyd's options.
  3. 3Start ttyd. Run ttyd with a port if you do not want the default 7681, for example ttyd -p 8080 bash.
  4. 4Add authentication. Set a username and password with -c username:password before exposing the port beyond your own machine.
  5. 5Decide on write access. Leave the terminal read-only, or add -W if clients need to type into it.
  6. 6Open it in a browser. Visit the address ttyd shows, using the credentials you set, and use the terminal.

Install ttyd on macOS, Linux or Windows

Use your platform's package manager where one is available. On macOS, install with Homebrew or MacPorts. On Debian or Ubuntu, use apt. On Windows, use WinGet or Scoop.

You can also download precompiled static binaries from the releases page on GitHub. The README also lists a snap package, an OpenWrt package via opkg, and a Gentoo route, and notes that Windows users can compile it themselves.

  • macOS: brew install ttyd (Homebrew) or sudo port install ttyd (MacPorts)
  • Debian/Ubuntu: sudo apt install ttyd
  • Snap: sudo snap install ttyd --classic
  • OpenWrt: opkg install ttyd
  • Windows: winget install tsl0922.ttyd or scoop install ttyd
brew install ttyd sudo apt install ttyd winget install tsl0922.ttyd scoop install ttyd

Start your first web terminal

ttyd takes a command and its arguments after the options. Run it from your shell, then open the address it prints in a browser. By default it listens on port 7681.

The command you give ttyd is what the browser shows. Any custom command with options works, so you can serve a shell or a single program.

  • Default port is 7681; use 0 for a random port
  • Use -p to choose a port
  • Use -B to open the terminal in your default system browser
ttyd bash ttyd -p 8080 bash ttyd -B bash

Control who can see and type into the terminal

The terminal is read-only by default. Add -W (--writable) to let clients type into the TTY. Only do this when you trust everyone who can reach the address.

For basic authentication, pass -c with username:password. The README describes basic auth and SSL options, so set both if the port is reachable from other networks.

  • -W / --writable: allow clients to write to the TTY
  • -c / --credential: basic auth in the format username:password
  • -S / --ssl with -C (certificate) and -K (key): enable SSL
  • -i / --interface: bind to a specific interface, such as eth0
ttyd -c alice:strongpassword -W bash ttyd -S -C cert.pem -K key.pem -c alice:strongpassword bash

Use the useful extra options

Several options control how the session behaves. -m limits the number of clients. -o accepts one client and exits when it disconnects. -q exits when all clients disconnect. -w sets the working directory for the child program.

If ttyd sits behind a reverse proxy, -H lets the proxy handle authentication through an HTTP header, and -b sets the expected base path. -a lets clients pass command-line arguments in the URL.

  • -m / --max-clients: cap concurrent clients (0 means no limit)
  • -o / --once: one client, then exit
  • -q / --exit-no-conn: exit when all clients disconnect
  • -w / --cwd: working directory for the program
  • -H / --auth-header: let a reverse proxy handle auth
  • -b / --base-path: base path for reverse proxy requests
  • -a / --url-arg: allow arguments in the URL, e.g. ?arg=foo&arg=bar
ttyd -o -w /home/user bash ttyd -H X-Forwarded-User -b /terminal bash

Know what ttyd can do beyond plain text

ttyd supports CJK characters and IME input, and it uses WebGL2 for rendering. It also supports ZMODEM file transfer through lrzsz, and trzsz, plus Sixel image output through img2sixel and lsix.

The full list of options and example usage is on the project wiki. The README says modern browsers are supported, with a link to xterm.js browser support for details.

  • CJK and IME input
  • WebGL2 rendering on top of libuv
  • ZMODEM (lrzsz) and trzsz file transfer
  • Sixel image output (img2sixel, lsix)
  • SSL via OpenSSL or Mbed TLS
  • Runs on macOS, Linux, FreeBSD/OpenBSD, OpenWrt and Windows

What people use it for

  • Open a shell on a home server or device from a browser when you have no native terminal client
  • Run tools on an OpenWrt router or other small Linux box and reach them from a browser
  • Give someone on your local network quick browser access to a command-line program
  • Use a browser terminal with ZMODEM file transfer or Sixel image output

Frequently asked questions

Is ttyd free to use?

ttyd is released under the MIT licence, according to the project page and README badge. Check the repository's licence file for the full terms.

How do I install ttyd?

Use brew install ttyd on macOS, sudo apt install ttyd on Debian or Ubuntu, winget install tsl0922.ttyd or scoop install ttyd on Windows, or opkg install ttyd on OpenWrt. You can also download precompiled binaries from the GitHub releases page.

Is ttyd secure enough to expose to the internet?

Not without strong protection. The README describes basic auth and SSL options, but a shared shell carries significant risk. Set credentials, enable SSL, and keep the port off the public internet unless you have a clear reason and a proper setup.

Can I type into the terminal from the browser?

Not by default. The terminal is read-only unless you start ttyd with -W (--writable).

What are the alternatives to ttyd?

The README lists Wetty, a Node-based web terminal that works with SSH and logins, and GoTTY, a Go-based web terminal. Choose Wetty if you specifically want SSH-style login.

Does ttyd support Windows?

Yes. The README lists Windows among supported platforms, with a binary download, WinGet and Scoop installs, and a guide for compiling on Windows.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

ttyd suits developers who want quick browser access to a shell or command-line program on a home server, small Linux device or local network, and it is light to set up. Do not expose it to the internet without strong authentication and SSL. If you need SSH-style login, pick Wetty, and if you need a full multi-user web IDE, look elsewhere.

Install options & downloads