Guide · Open source

How to use gotty: share a terminal command in your browser

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

GoTTY is a command line tool that turns a terminal program into a web application. You start it with a command such as top, then open its address in a browser to see that program running. This guide covers installing it, running your first command, locking it down with a password or TLS, and sharing one session with several people.

GoTTYyudai/gotty · ★ 19.6k · MIT Install options & downloads

Quick start

1Install gotty. Run brew install yudai/gotty/gotty with Homebrew, or use go get github.com/yudai/gotty if you have Go 1.9 or later.
2Start a command. Run gotty followed by the program you want to share, such as gotty top.
3Open the browser address. Visit the address shown, which uses port 8080 by default, to watch the command run.
4Enable TLS. Add -t and create a certificate at ~/.gotty.crt and ~/.gotty.key before sharing anything sensitive.
5Add basic authentication. Use -c user:pass to require a username and password, knowing the credentials travel in plain text without TLS.
6Allow input only if needed. Add -w only when clients must type, and consider tmux for safer shared sessions.

Install gotty with Homebrew or go get

The README describes two install methods. With Homebrew, run the install command below. If you have a Go environment, you can instead use go get, which requires go1.9 or later.

The go get method builds a binary from the latest master branch, which can include unstable or breaking changes. The README also offers prebuilt binaries on its Releases page; it recommends the release marked Latest release for a stable build.

Homebrew is optional and only needed for the brew method.
Go 1.9 or later is needed only for go get or building from source.
Windows is not supported for building, according to the README.

$ brew install yudai/gotty/gotty

Run your first command in the browser

Run gotty followed by the command you want to share. The README's example is top. By default GoTTY starts a web server on port 8080. Open the address in your web browser and you will see the running command as if it were in your terminal.

Clients can only watch by default. They cannot send keystrokes, apart from resizing the terminal window.

Usage: gotty [options] <command> [<arguments...>]
Default listen address is 0.0.0.0 and default port is 8080.
Use -p or --port to change the port, for example to 9000 via the config file.

$ gotty top

Secure your session with a password, random URL or TLS

The README warns that traffic is not encrypted by default. Use -t to enable TLS/SSL. GoTTY loads the certificate and key from ~/.gotty.crt and ~/.gotty.key unless you set --tls-crt and --tls-key. To make a self-signed certificate, the README gives an openssl command.

For basic authentication, use -c with user:pass. The README notes the credentials are sent in plain text, so pair it with TLS. The -r option adds a random string to the URL so only people with the link can reach it. For stricter checks, --tls-ca-crt requires client certificates and needs -t.

-t / --tls: enable TLS/SSL.
-c / --credential: basic authentication, for example user:pass.
-r / --random-url: random URL, length set by --random-url-length (default 8).
--tls-ca-crt: CA certificate for client certificate checks, requires -t.

openssl req -x509 -nodes -days 9999 -newkey rsa:2048 -keyout ~/.gotty.key -out ~/.gotty.crt

Allow typing with -w and understand the risk

By default clients cannot type into the terminal. The -w option lets them write to the TTY. The README says accepting input from remote clients is dangerous for most commands, so use it with care.

If you need interaction, the README suggests running GoTTY with tmux or GNU Screen instead.

-w / --permit-write: lets clients write to the TTY (the option text itself says BE CAREFUL).
--once: accept only one client and exit when it disconnects.
--max-connection: limit the number of connections.

$ gotty -w top

GoTTY starts a new process for each connecting client, so people do not share one terminal by default. To share a single process, the README suggests a terminal multiplexer such as tmux. Start a tmux session named gotty running top through GoTTY, then attach to it from your own terminal. Clients viewing through the browser can see your screen, and you keep control.

The README also shows a tmux shortcut that starts GoTTY in a new window.

This tmux approach lets clients only see the screen, not type.
Add the bind-key line to .tmux.conf to share your current session with a shortcut.

$ gotty tmux new -A -s gotty top

Customise the config file and browser view

You can set default options in a config file. GoTTY loads ~/.gotty by default when it exists, or you can point to another file with --config. The README's example sets the port, enables TLS and sets hterm preferences such as font size and background colour.

Other options control the browser window title (--title-format, default {{ .command }}@{{ .hostname }}), the terminal used in the browser (--term, xterm or hterm) and automatic reconnection (--reconnect).

Settings can also come from environment variables such as GOTTY_PORT and GOTTY_TLS.
See the .gotty file in the repository for the full list of configuration options.

port = "9000"
enable_tls = true

preferences {
    font_size = 5
    background_color = "rgb(16, 16, 32)"
}

What people use it for

Showing a running top or other monitoring command to a colleague in a browser.
Reaching a command-line tool on another machine from a web browser.
Watching a long-running command remotely without opening an SSH session.
Running a command inside a Docker container per client using gotty -w docker run -it --rm busybox, as the README describes.

Frequently asked questions

Is gotty free to use?

GoTTY is released under the MIT licence, according to the README. The licence file is linked in the repository.

How do I install gotty?

The README lists Homebrew with brew install yudai/gotty/gotty and go get github.com/yudai/gotty. You can also download a binary from the Releases page.

Is gotty secure?

Not by default. The README says traffic is not encrypted unless you use -t for TLS/SSL, and basic authentication sends credentials in plain text. Use TLS before sharing secret information.

Can multiple people share one terminal with gotty?

Not by default, because each new client starts a new process. The README suggests running tmux or GNU Screen through GoTTY to share a single process.

What port does gotty use?

By default GoTTY starts a web server at port 8080. You can change it with -p or --port, or set the port in the config file.

What are the alternatives to gotty?

The comparable projects listed here are ttyd, wetty and shellinabox. This guide does not compare their features, so check each project's documentation before choosing.

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

GoTTY suits developers who want to show or reach a command-line tool from a browser, especially with TLS and a password added. Do not use it for sensitive sessions without encryption, for multi-user shared terminals out of the box, or on Windows, where the README says building is not supported.

Install options & downloads