dotlinux blog

GoTTY: Share Your Linux Terminal (TTY) as a Web Application

In today's collaborative and remote-centric world, the ability to share your work seamlessly is more important than ever. For system administrators, DevOps engineers, and developers, a significant portion of work happens within the terminal. What if you could share your terminal session with a colleague for debugging, a student for teaching, or a team member for collaboration, without the complexity of traditional screen-sharing software or SSH key exchanges?

Enter GoTTY – a powerful, open-source command-line tool written in Go that transforms your Linux Terminal (TTY) into a web application. With just one command, you can host your terminal in a browser, allowing anyone with the URL to view or even interact with it in real-time. It's like giving a live, streamed demo of your command-line work, directly from your machine.

This blog post will serve as a comprehensive guide to GoTTY, from the basic concepts to advanced configurations, ensuring you can leverage this fantastic tool safely and effectively.

2026-05

Table of Contents#

  1. What is GoTTY?
  2. Key Features and Use Cases
  3. Installation Guide
  4. Getting Started: Your First GoTTY Session
  5. Basic Usage and Common Options
  6. Advanced Configuration and Security
  7. Important Security Considerations
  8. Conclusion
  9. References

What is GoTTY?#

At its core, GoTTY is a simple command-line tool that takes any CLI application and serves it as a web application. While it can host any application, its most common and powerful use case is sharing the terminal itself (/bin/bash, zsh, etc.).

It works by creating an HTTP server that serves a HTML/JavaScript-based terminal emulator (using xterm.js). When you connect to the server via a web browser, a WebSocket connection is established. This WebSocket acts as a bridge, relaying the input from your browser to the underlying TTY (terminal) and sending the output from the TTY back to the browser. This creates a real-time, bidirectional terminal session over the web.

Key Features and Use Cases#

  • Live Demos & Presentations: Perfect for presenting command-line workflows during meetings or conferences without fiddling with screen sharing.
  • Remote Assistance: Help a colleague troubleshoot a server issue by allowing them to see your terminal or even by giving them controlled access.
  • Education & Training: Teachers can demonstrate complex command-line operations to students in real-time.
  • Limited Access Sharing: Provide temporary, browser-based access to a terminal for users who shouldn't have full SSH credentials.
  • Container & CI/CD Debugging: Temporarily expose a terminal session from within a container or a CI/CD pipeline for debugging purposes.

Installation Guide#

Getting GoTTY up and running is straightforward. Here are the most common methods.

Method 1: Using a Package Manager (easiest)#

If you are on a system with brew (macOS or Linuxbrew), this is the simplest method.

# On macOS or Linux with Homebrew installed
brew install gotty

For Arch Linux users, it's available in the AUR.

Method 2: Downloading the Binary#

Visit the GoTTY GitHub Releases page. Download the appropriate archive for your architecture (e.g., gotty_2.0.0-alpha.3_linux_amd64.tar.gz), extract it, and move the binary to your PATH.

# Example for Linux AMD64
wget https://github.com/sorenisanerd/gotty/releases/download/v2.0.0-alpha.3/gotty_2.0.0-alpha.3_linux_amd64.tar.gz
tar -xzf gotty_2.0.0-alpha.3_linux_amd64.tar.gz
sudo mv gotty /usr/local/bin/

Method 3: Building from Source#

Ensure you have Go (1.19+) installed.

go install github.com/sorenisanerd/gotty@latest

The binary will be placed in your $GOPATH/bin directory (typically ~/go/bin/).

Getting Started: Your First GoTTY Session#

Let's start with the most basic command. This will share your current terminal session.

  1. Open your terminal.

  2. Run the following command:

    gotty bash

    This starts a GoTTY server hosting a bash shell.

  3. By default, GoTTY listens on port 8080. Open your web browser and navigate to http://your-server-ip:8080.

You should now see a terminal interface in your browser that is a mirror of the bash session you started on the server. Anything you type in the browser will be executed on the server.

Warning: This basic setup is highly insecure as it is accessible to anyone on the network without a password. The following sections will show you how to secure it.

Basic Usage and Common Options#

GoTTY is highly configurable. Here are the most essential options.

Authentication#

The single most important option. Always use it to password-protect your session.

gotty -c 'username:password' bash

Now, when you access the page, you will be prompted for the credentials.

Port Binding#

Change the default port (8080) to something else using the -p flag.

gotty -p 9090 -c 'admin:secret123' bash
# Now access via http://your-server-ip:9090

Whitelisting IPs#

To restrict access to a specific IP address (e.g., your own), use the -i (interface) flag.

gotty -i 192.168.1.100 -c 'user:pass' bash
# The server will only listen on the interface with IP 192.168.1.100

Running a Specific Command#

Instead of sharing an interactive shell, you can share a single, long-running command. For example, to share the output of top:

gotty -c 'user:pass' -- top

This is great for monitoring purposes. The command will run, and users can see its live output but cannot send input.

Advanced Configuration and Security#

For production or internet-facing use, basic authentication is not enough. You should use encryption and additional layers of security.

Using TLS/SSL (--tls)#

If you have an SSL certificate, you can serve GoTTY over HTTPS.

gotty -p 443 --tls --tls-cert fullchain.pem --tls-key privkey.pem -c 'user:pass' bash

Using a Reverse Proxy (nginx)#

A more robust setup is to place GoTTY behind a reverse proxy like nginx. This allows you to:

  • Use a domain name.
  • Handle SSL termination with Let's Encrypt (e.g., using Certbot).
  • Add additional security headers.
  • Use a path-based route (e.g., example.com/gotty).

Example nginx configuration:

# Inside your server block
location /gotty/ {
    proxy_pass http://127.0.0.1:8080/; # Proxy to GoTTY running locally
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 86400; # WebSocket timeout
}

You would then run GoTTY locally on port 8080: gotty -p 8080 -c 'user:pass' bash and access it securely at https://yourdomain.com/gotty.

Read-Only Mode#

For scenarios where you only want to share your screen without allowing others to type (e.g., for a demo), use the read-only flag.

gotty -r -c 'user:pass' bash

Important Security Considerations#

GoTTY is a powerful tool, and with great power comes great responsibility. Misconfiguration can lead to severe security risks.

  1. NEVER RUN GoTTY WITHOUT AUTHENTICATION ON A PUBLIC NETWORK. This is equivalent to leaving an unlocked terminal open for anyone to use.
  2. Prefer HTTPS over HTTP. Transmitting passwords over HTTP is insecure. Always use --tls or a reverse proxy with SSL.
  3. Use Strong Credentials. Don't use simple or default usernames and passwords.
  4. Limit Access with Firewalls. Use your server's firewall (e.g., ufw) to restrict access to the GoTTY port only from trusted IP ranges.
  5. Consider it a Temporary Tool. GoTTY is ideal for short-term sharing. Do not leave it running indefinitely.
  6. Understand the Risks of Interactive Sessions. Anyone with access can run any command that the user running the gotty process has permission to run. It's often safer to run GoTTY as a non-root user.

Conclusion#

GoTTY is an incredibly useful utility that bridges the gap between the traditional command line and modern web-based collaboration. It simplifies tasks like remote debugging, teaching, and demystifying command-line operations. While its setup is simple, a secure deployment requires careful attention to authentication, encryption, and access controls.

By following the practices outlined in this guide, you can safely unlock the power of sharing your terminal as a web application, making your workflow more collaborative and efficient.

References#

  1. Official GoTTY GitHub Repository: https://github.com/sorenisanerd/gotty - The definitive source for documentation, issue tracking, and the latest releases.
  2. xterm.js: https://xtermjs.org/ - The powerful terminal frontend component used by GoTTY.
  3. nginx Documentation: https://nginx.org/en/docs/ - For detailed information on configuring a reverse proxy.
  4. Let's Encrypt: https://letsencrypt.org/ - For obtaining free SSL/TLS certificates.