Example Usage

Table of Contents

• Basic Usage
• Docker image
• Systemd service (on linux)
• Let's Encrypt certificates
• Nginx reverse proxy

Basic Usage

ttyd starts web server at port 7681 by default, you can use the -p option to change it, the command will be started with arguments as options. For example, run:

ttyd -p 8080 bash

Then open http://localhost:8080 with a browser, you will get a bash shell with debug mode enabled.

More Examples:

• If you want to login with your system accounts on the web browser, run ttyd login.
• You can even run a none shell command like vim, try: ttyd vim, the web browser will show you a vim editor.
• Sharing single process with multiple clients: ttyd tmux new -A -s ttyd vim, run tmux new -A -s ttyd to connect to the tmux session from terminal.
• Turn off leave alert message

ttyd -p 8080 -t disableLeaveAlert=true bash

• Change font size

ttyd -p 8080 -t fontSize=16 bash

• Access it only on localhost

ttyd -p 8080 -i 127.0.0.1 bash

Docker image

• Sharing single docker container with multiple clients: docker run -it --rm -p 7681:7681 tsl0922/ttyd.
• Creating new docker container for each client: ttyd docker run -it --rm ubuntu.

Systemd service (on linux)

In order to have ttyd launch on startup and restart automatically on error, you can create and enable a service file running its binary. Say we've downloaded a binary from the releases page and moved it to /opt (so its full path is now /opt/ttyd). paste the following content into /etc/systemd/system/ttyd.service:

[Unit]
Description=TTYD
After=syslog.target
After=network.target

[Service]
ExecStart=/opt/ttyd login
Type=simple
Restart=always
User=root
Group=root

[Install]
WantedBy=multi-user.target

Now, to start the service and make sure it starts on boot:

sudo systemctl start ttyd && sudo systemctl enable ttyd

MAKE SURE YOU DON'T RUN ANY COMMAND OTHER THAN login AS ROOT, AND THAT YOUR ROOT ACCOUNT HAS NO PASSWORD. IF YOU CHOOSE TO RUN A DIFFERENT COMMAND, USE ANY NON-ROOT USER.

Let's Encrypt certificates

Let's Encrypt is a Certificate Authority that grants SSL certificates for free, and automatically (via a CLI). First, install their CLI - certbot, then you can request a certificate for your domain:

certbot certonly -d <your domain>

You'll now be able to run ttyd on HTTPS:

ttyd --ssl --ssl-cert /etc/letsencrypt/live/<your domain>/fullchain.pem --ssl-key /etc/letsencrypt/live/<your domain>/privkey.pem <command>

Nginx reverse proxy

If you're interested in running multiple web services on the same machine, a reverse proxy server such as Nginx might be useful! After installing and activating the nginx service, paste the following into /etc/nginx/sites-available/ttyd:

server {
    server_name <your domain>;

    # the following section is relevant if you've generated SSL certificates via Let's Encrypt - which you should have >:(
    listen 443 ssl;
    ssl_certificate           /etc/letsencrypt/live/<your domain>/fullchain.pem;
    ssl_certificate_key       /etc/letsencrypt/live/<your domain>/privkey.pem;
    ssl_trusted_certificate   /etc/letsencrypt/live/<your domain>/chain.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    location / {
        proxy_pass https://localhost:7681/;  # default ttyd port, notice the https prefix
        proxy_http_version 1.1;
        proxy_set_header X-Real-IP  $remote_addr;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        # needed for websocket
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}

# redirect http requests to https
server {
    if ($host = <your domain>) {
        return 301 https://$host$request_uri;
    }

    listen 80;
    server_name <your domain>;
    return 404;
}