GoTTY - Share your terminal as a web application

Prerequisites

Go Language: GoTTY requires Go 1.9 or later for development builds
Terminal: Any standard terminal that supports the commands you want to share
Web Browser: Modern web browser to access the shared terminal

Installation

Binary Installation (Recommended)

Download the latest stable binary from the Releases page. For production use, download a release marked "Latest release" rather than "Pre-release" which may contain unstable changes.

For Mac OS X users: Download files named with darwin_amd64.

Homebrew Installation

You can install GoTTY using Homebrew:

$ brew install yudai/gotty/gotty

Development Installation

If you have Go installed and want to build from source:

$ go get github.com/yudai/gotty

Configuration

GoTTY can be configured using command-line options or a configuration file.

Command Line Options

Key options include:

--address, -a: IP address to listen (default: "0.0.0.0")
--port, -p: Port number to listen (default: "8080")
--permit-write, -w: Permit clients to write to the TTY (use with caution)
--credential, -c: Basic authentication (format: user:pass)
--tls, -t: Enable TLS/SSL
--random-url, -r: Add random string to URL for security

Configuration File

Create a ~/.gotty file for default settings:

// Listen at port 9000 by default
port = "9000"

// Enable TLS/SSL by default
enable_tls = true

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

Build & Run

Running Locally

Simply run GoTTY with your command:

$ gotty <command> [<arguments...>]

For example, to share the top command:

$ gotty top

By default, GoTTY starts a web server at port 8080. Open http://localhost:8080 in your browser to see the running command.

Common Use Cases

With write permissions (use with caution):

$ gotty -w bash

With authentication:

$ gotty -c user:pass bash

With random URL for security:

$ gotty -r bash

With TLS/SSL:

$ gotty -t bash

Deployment

GoTTY is a single binary application that can be deployed to various platforms:

Docker Deployment

Create a Dockerfile:

FROM alpine:latest
RUN apk add --no-cache gotty
EXPOSE 8080
CMD ["gotty", "bash"]

Build and run:

$ docker build -t gotty .
$ docker run -p 8080:8080 gotty

Cloud Platforms

Heroku: Deploy as a simple web application. Create a Procfile and push to Heroku.

DigitalOcean: Deploy the binary directly to a droplet and run as a service.

AWS EC2: Deploy the binary and configure security groups to allow web access.

Google Cloud Run: Package as a container and deploy for serverless execution.

Security Considerations

Use --random-url for added security in production
Enable TLS/SSL with --tls for encrypted connections
Use --credential for basic authentication
Consider using --once to accept only one client
For sensitive commands, use tmux or screen sessions

Troubleshooting

Common Issues

Port already in use:

$ gotty -p 9000 <command>

Permission denied: Ensure you have execute permissions on the binary or use sudo if needed.

Connection refused: Check firewall settings and ensure the port is open.

TLS certificate issues: Generate certificates or use --tls-crt and --tls-key options to specify paths.

WebSocket connection problems: Check browser console for errors and ensure the server is running.

Debug Mode

Run with verbose output to diagnose issues:

$ gotty -v <command>

Configuration Validation

Test your configuration file syntax:

$ gotty --config ~/.gotty <command>

If the configuration is invalid, GoTTY will display an error message.

Network Issues

If clients cannot connect:

Verify the server is running: ps aux | grep gotty
Check network connectivity: curl http://localhost:8080
Verify firewall rules allow the port
Check if SELinux/AppArmor is blocking connections

Browser Compatibility

GoTTY works with modern browsers. If you experience issues:

Try a different browser
Clear browser cache
Disable browser extensions that might interfere with WebSockets

How to Deploy & Use yudai/gotty