remote working? Pair SSH with Teleport.

As companies start working remote-first, we’ve quickly reached the limit of the tools available. Sure, you can jump into Slack Huddle or Screen Share on the Zoom Rooms, or if you’re running Linux — good luck. Sometimes you want to jam with your coworkers using terminal. In this post, I will show how you can use Teleport Community Edition To set up a teleport and share an ssh session with a peer without them ever having to leave the terminal.


To get started, you will need:

  • An additional VM, a domain name, and the ability to set DNS records for that host. This is all that is needed to host a teleport proxy.
  • a server/host you want to connect to
  • to pair up with a friend

Step 1: Set up Teleport

To begin with, my . recommend using Getting Started Guide, It outlines the steps to set up Teleport, open a port, set up DNS, and create the first admin user. Once set up, you’ll have access to a UI and you should be able to connect using your terminal once the teleport client is installed locally.

set up teleport

Step 2: Install Teleport Client Locally

The next step is to install Teleport locally. This is so that we can use teleport from the terminal. Once installed, we will primarily be using ‘tsh’, a tool to log in to teleport and get the correct credentials.

Replace with the public address of your Teleport cluster

$ tsh login --user=teleport-admin

Once logged in, you will be able to see any connected node using `tsh ls`.

Step 3: Add a Node to Teleport

After setting up a teleport proxy, you’ll want to add nodes to the teleport. For the purposes of this walkthrough, I’m just going to start a new Ubuntu cloud box. Once booted, we need to install Teleport and then connect it back to our Teleport instance.

Generate a short term 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 is 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 get it. Using GitHub SSO, it is possible to grant access to the entire team on Github, and if you remove that person from your GitHub organization, they teleport and therefore will not be able to access your servers.

Step 5: Start and Share a Session

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

tsh login --auth=github
tsh ls
tsh ssh [email protected]
[email protected]:~# 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 : 

‘Teleport Status’ outputs some important information like session ID and session URL. The session URL can be shared to provide direct access from the browser to the server. If the other party wants to use the terminal, they can connect using:

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

Teleport - start and share a session

The teleport number at the top right next to ‘ec2-user’ shows how many people are logging into the shared session.

Demo of Teleport Shared Sessions:

Teleport Shared Sessions Demo

Leave a Comment