upterm

README

Upterm

Upterm is an open-source solution for sharing terminal sessions instantly over the public internet via secure tunnels. Upterm is good for

• Remote pair programming
• Access remote computers behind NATs and firewalls
• Remote debugging
• <insert your creative use cases>

Usage

The host starts a terminal session:

$ upterm host -- bash

The host displays the ssh connection string:

$ upterm session current
=== IQKSFOICLSNNXQZTDKOJ
Command:                bash
Force Command:          n/a
Host:                   ssh://uptermd.upterm.dev:22
SSH Session:            ssh IqKsfoiclsNnxqztDKoj:MTAuMC40OS4xNjY6MjI=@uptermd.upterm.dev

The client opens a terminal and connects to the host's session:

$ ssh IqKsfoiclsNnxqztDKoj:MTAuMC40OS4xNjY6MjI=@uptermd.upterm.dev

Installation

Mac

brew install jingweno/upterm/upterm

Standalone

upterm can be easily installed as an executable. Download the latest compiled binaries and put it in your executable path.

From source

git clone git@github.com:jingweno/upterm.git
cd upterm
go install ./cmd/upterm/...

Upgrade

upterm comes with a command to upgrade

$ upterm upgrade # upgrade to the latest version

$ upterm upgrade VERSION # upgrade to a version

Mac

brew upgrade upterm

Quick Reference

# Host a terminal session that runs $SHELL with
# client's input/output attaching to the host's
$ upterm host

# Display the ssh connection string and share it with
# the client(s)
$ upterm session current
=== SESSION_ID
Command:                /bin/bash
Force Command:          n/a
Host:                   ssh://uptermd.upterm.dev:22
SSH Session:            ssh TOKEN@uptermd.upterm.dev

# A client connects to the host session with ssh
$ ssh TOKEN@uptermd.upterm.dev

# Host a terminal session that only allows specified client public key(s) to connect
$ upterm host --authorized-key PATH_TO_PUBLIC_KEY

# Host a session with a custom command
$ upterm host -- docker run --rm -ti ubuntu bash

# Host a session that runs 'tmux new -t pair-programming' and
# force clients to join with 'tmux attach -t pair-programming'.
# This is similar to what tmate offers.
$ upterm host --force-command 'tmux attach -t pair-programming' -- tmux new -t pair-programming`,

# Connect to uptermd.upterm.dev via WebSocket
$ upterm host --server wss://uptermd.upterm.dev -- bash

# A client connects to the host session via WebSocket
$ ssh -o ProxyCommand='upterm proxy wss://TOKEN@uptermd.upterm.dev' TOKEN@uptermd.upterm.dev:443

More advanced usage is here.

Tips

Why doesn't upterm session current show current session in Tmux?

upterm session current needs the UPTERM_ADMIN_SOCKET environment variable to function. And this env var is set in the specified command. Unfotunately, Tmux doesn't carry over environment variables that are not in its default list to any Tmux session unless you tell it to (Ref). So to get upterm session current to work, add the following line to your ~/.tmux.conf

set-option -ga update-environment " UPTERM_ADMIN_SOCKET"

How to make it obvious that I am in an upterm session?

It can be confusing whether your shell command is running in an upterm session or not, especially if the shell command is bash or zsh. Add the following line to your ~/.bashrc or ~/.zshrc and decorate your prompt to show a sign if the shell command is in a terminal session:

export PS1="$([[ ! -z "${UPTERM_ADMIN_SOCKET}"  ]] && echo -e '\xF0\x9F\x86\x99 ')$PS1" # Add an emoji to the prompt if `UPTERM_ADMIN_SOCKET` exists

Demo

How it works

You run the upterm program by specifying the command for your terminal session. Upterm starts an SSH server (a.k.a. sshd) in the host machine and sets up a reverse SSH tunnel to a Upterm server (a.k.a. uptermd). Clients connect to your terminal session over the public internet via uptermd using ssh using TCP or WebSocket. A community Upterm server is running at uptermd.upterm.dev and upterm points to this server by default.

Deploy Uptermd

Kubernetes

You can deploy uptermd to a Kubernetes cluster. Install it with helm:

$ helm repo add upterm https://upterm.dev
$ helm repo update
$ helm search repo upterm
NAME            CHART VERSION   APP VERSION     DESCRIPTION
upterm/uptermd  0.1.0           0.4.1           Secure Terminal Sharing
$ helm install uptermd upterm/uptermd

Heroku

The cheapest way to deploy a worry-free Upterm server (a.k.a. uptermd) is to use Heroku. Heroku offers free Dyno hours which should be sufficient for most casual uses.

You can deploy with one click of the following button:

You can also automate the deployment with Heroku Terraform. The Heroku Terraform scripts are in the terraform/heroku folder. A util script is provided for your convenience to automate everything:

$ git clone https://github.com/jingweno/upterm
$ cd upterm

# Provinsion uptermd in Heroku Common Runtime.
# Follow instructions
$ bin/heroku-install

# Provinsion uptermd in Heroku Private Spaces.
# Follow instructions
$ TF_VAR_heroku_region=REGION TF_VAR_heroku_space=SPACE_NAME TF_VAR_heroku_team=TEAM_NAME bin/heroku-install

You must use WebScoket as the protocol for a Heroku-deployed Uptermd server because the platform only support HTTP/HTTPS routing. This is how you host a session and join a session:

# Use the Heroku-deployed Uptermd server via WebSocket
$ upterm host --server wss://YOUR_HEROKU_APP_URL -- YOUR_COMMAND

# A client connects to the host session via WebSocket
$ ssh -o ProxyCommand='upterm proxy wss://TOKEN@YOUR_HEROKU_APP_URL' TOKEN@YOUR_HEROKU_APP_URL:443

License

Apache 2.0