Working Remotely? Pair SSH with Teleport.

As companies have started to embrace working remote-first, we’ve quickly reached the limits of tools available. Sure, you can jump into a Slack Huddle or Screen Share over a Zoom Room, or if you’re running Linux – good luck. Sometimes you want to jam with your co-workers using the Terminal. In this post, I’ll show how you can use Teleport Community Edition to set up a Teleport and share an SSH session with a co-worker without them ever having to leave the terminal.


To get started, you’ll need:

  • A spare VM, a domain name and the ability to set DNS records for that host. All of this is needed to host the Teleport Proxy.
  • A server/host you want to connect to
  • A friend to pair with


Step 1: Set up Teleport

To get started, I recommend using our Getting Started Guide. This outlines the steps for installing Teleport, opening ports, setting up DNS and creating the first admin user. Once set up, you’ll get access to a UI and should be able to connect using your terminal once you install the Teleport client locally.

Set up Teleport


Step 2: Install the Teleport client locally

The next step is to install Teleport locally. This is so we can use Teleport from the terminal. Once installed, we’ll mainly be using ‘tsh’, a tool for logging into Teleport and obtaining the correct credentials.

Replace with your Teleport clusters public address

$ tsh login --user=teleport-admin

Once logged in, you’ll be able to see any connected nodes using `tsh ls`.


Step 3: Add a node to Teleport

After setting up the Teleport Proxy, you’ll want to add nodes to Teleport. For the purposes of this walkthrough, I’m just going to fire up a new Ubuntu Cloud box. Once booted, we need to install Teleport and then get it connected back to our Teleport instance.

Generate a short-lived dynamic join token using ‘tctl’:

tctl tokens add --type=node

Bootstrap a new node: Replace auth_servers with the hostname and port of your Teleport cluster, token with the token you generated above.

$ teleport start \
--roles=node \
--auth-server= \
--token=${TOKEN?} \


Step 4: Invite the crew

The next step is to invite the rest of the team. It’s possible to invite new users by creating an invite link using ‘tctl users add joe joe,ubuntu’ but we would recommend using GitHub SSO to achieve this. By using GitHub SSO, it’s possible to provide access to the whole team on Github, and if you remove that person from your GitHub org, they will no longer be able to access Teleport and therefore, your servers.


Step 5: Start & share a session

Sessions can be started using the Teleport Proxy UI, or can be started from the command line. ‘tsh’ is a tool that’ll both log us in, and will be used as our ssh client. You can think of ‘tsh ssh’ as a replacement of ‘ssh’.

tsh login --auth=github
tsh ls
tsh ssh ubuntu@ip-10-0-0-9
root@ip-10-0-0-9:~# teleport status
User ID : benarent, logged in as ubuntu from 63167 52830
Cluster Name:
Host UUID : a6db0e32-90e1-4301-bf40-01746f622157
Session ID : 5cc739d8-27e7-4407-849a-23259c015adf
Session URL : https://<proxyhost>:3080/web/cluster/

‘teleport status’ outputs some key information, such as the session ID and session URL. The session URL can be shared, to provide direct access to the server from a browser. If the other party wants to use a terminal, they can join using:

tsh login --auth=github
tsh join 49032955-dd35-4a00-b8e1-f5d15982d77c

Teleport - Start & share a session

The Teleport number in the top right next to ‘ec2-user’ shows how many people are logged accessing the shared session.

Demo of Teleport shared sessions
Demo of Teleport shared sessions


Tags: , ,


  1. This is actually really helpful. A lot of people who run Linux work remotely and are not able to solve this challenge.

Top ↑