Upterm

Secure Terminal Sharing


Project maintained by jingweno Hosted on GitHub Pages — Theme by mattgraham

Upterm

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

What it’s good for

How it works

You run the upterm program and specify 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 via TCP or WebSocket. A community Upterm server is running at uptermd.upterm.dev and upterm points to this server by default.

upterm flowchart

Demo

asciicast

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/...

Quick Start

# 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 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 tmate.
$ 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.

Deploy Uptermd

The easiest and the cheapest way to deploy a 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:

Deploy

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/uptermd-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/uptermd-install

You must use WebScoket as the protocol for a Heroku-deployed Uptermd server. 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