Fork me on GitHub

Teleport

Using Teleport Connect

Improve

Teleport Connect provides easy and secure access to SSH servers and databases, with support for other resources such as Kubernetes clusters and applications coming in the future.

resources tab in Teleport Connect

Installation & upgrade

Head over to the Downloads page to download the most recent version. Teleport Connect supports macOS, Linux, and Windows.

Double-click the downloaded .dmg file and drag the Teleport Connect icon to the Applications folder.

To upgrade Teleport Connect to a newer version, drag the new version to the Applications folder.

Download the DEB (Debian-based distros) or RPM (RHEL-based distros) package and install it using your package manager. Repeat the process for in-place upgrades.

You can also download the project as a tar.gz file to extract and run it in place:

tar -xf teleport-10.3.1-linux-*.tar.gz

Download and run the installer .exe file. It will install and open Teleport Connect without further user input.

Repeat the process with newer versions to upgrade.

User interface

user interface of Teleport Connect

The top bar of Teleport Connect consists of:

  • The profile selector (the top right), which allows you to switch between profiles on different Teleport clusters as well as log in or out of the clusters.
  • The connection list (the top left) showing recent connections, allowing you to seamlessly switch between them.
  • The command bar (in the middle), which launches any command you input in a new terminal tab.
  • The cluster selector (to the left of the command bar), which shows up only if you have set up Trusted Clusters and there are leaf clusters connected to the root cluster. It lets you browse leaf cluster resources. It also changes which cluster the commands in the command bar are going to target.

Connecting to an SSH server

  1. Open a tab with cluster resources by clicking on the plus symbol at the right end of the tab bar. You can also press Ctrl/Cmd + T to achieve the same result.
  2. Look for the SSH server you want to connect to and click the Connect button to the right.
  3. Select or enter the SSH user you wish to log in as and press Enter.
  4. A new tab will open with a shell session on the chosen server.

Alternatively, you can type tsh ssh into the command bar in the Teleport Connect window, and the autocompletion will help you connect to a server.

Connecting to a database

  1. Open a tab with cluster resources by clicking on the plus symbol at the end of the tab bar. You can also press Ctrl/Cmd + T to achieve the same result.
  2. Select the Databases section.
  3. Look for the database server you wish to connect to and click the Connect button to the right.
  4. Select or enter the database user you with to use and press Enter.
  5. A new tab will open with a new connection established between your device and the database server.

This connection will remain active until you click the Close Connection button or close Teleport Connect. The port number will persist between app restarts—you can set up your favorite client without worrying about the port suddenly changing.

With a GUI client

To connect with a GUI client, follow the instructions in the database connection tab under the Connect with GUI section.

With a CLI client

The database connection tab shows the command that can be used to connect to the database. You can modify the database name of the connection and then click the Run button to open a new terminal tab with that command executed.

Connecting to multiple clusters

Teleport Connect allows you to log in to multiple clusters at the same time. After logging in to your first cluster, open the profile selector at the top right and click the +Add another cluster button. You can switch between active profiles in multiple ways:

  • Click at the profile selector button at the top right.
  • Open the profile selector with a shortcut (Ctrl/Cmd + I).
  • Using the connection list at the top left to select a connection will automatically switch you to the right profile.

At the moment Teleport Connect supports only one user per cluster. To log in as a different user, log out of the cluster first.

Restarting and reconnecting

Before closing, Teleport Connect will remember the tabs that you had open at the end of the session. Next time you open the app, Connect will ask you if you want to reopen those tabs. If you agree, Connect will restore connections to all resources that were active before you closed the app.

When restoring terminal tabs, Teleport Connect doesn't attempt to re-execute commands that were in progress when the app was closed. It will only restore the working directory for those tabs.

Troubleshooting

Logging out of a cluster, closing the app and logging in again resets all app state related to that cluster. This can help if you encounter a bug which renders the user interface partially unusable. It might also help if you have issues with connecting to an active cluster that don't happen in the Web UI.

To force the app to log you out of all clusters, close the app and remove the ~/Library/Application Support/Teleport Connect/tsh folder. Removing the file ~/Library/Application Support/Teleport Connect/app_state.json will clear all remembered tabs and connections.

To force the app to log you out of all clusters, close the app and remove the ~/.config/Teleport Connect/tsh folder. Removing the file /.config/Teleport Connect/app_state.json will clear all remembered tabs and connections.

To force the app to log you out of all clusters, close the app and remove the C:\Users\%UserName%\AppData\Roaming\Teleport Connect\tsh folder. Removing the file C:\Users\%UserName%\AppData\Roaming\Teleport Connect\app_state.json will clear all remembered tabs and connections.

Submitting an issue

To submit an issue, click the Submit Feedback button at the bottom right (the speech bubble symbol) and follow the Submit a Bug link.

Be sure to attach logs, which can be found under ~/Library/Application Support/Teleport Connect/logs. The version of the app can be found in the app menu under the About Teleport Connect menu item.

Be sure to attach logs, which can be found under ~/.config/Teleport Connect/logs. The app version can be found by pressing Alt to access the app menu, then -> Help -> About Teleport Connect.

Be sure to attach logs, which can be found under C:\Users\%UserName%\AppData\Roaming\Teleport Connect\logs. You may need to adjust File Explorer to view hidden files and folders. The app version can be found by pressing Alt to access the app menu -> Help -> About Teleport Connect.

Updating local shell environment

Teleport Connect updates and caches the local shell environment on app restart and not when starting a new shell session. If you add new environment variables to your shell startup files, Connect will see them only after you restart the app.

Insecure mode

You can open Teleport Connect in insecure mode, which skips HTTPS certificate verification when talking to a Teleport Proxy Service. This is useful in test environments or for demo purposes. We do not recommend using this mode in production.

To launch the app in insecure mode, open a terminal first. From there you can launch the app in one of two ways:

Using macOS open utility:

open -a "Teleport Connect" --args --insecure

Passing the flag to the executable directly:

/Applications/Teleport\ Connect.app/Contents/MacOS/Teleport\ Connect --insecure

From a terminal, open Teleport Connect with the --insecure flag:

teleport-connect --insecure

From the Command Prompt, open Teleport Connect with the --insecure flag:

"%LocalAppData%\Programs\teleport-connect\Teleport Connect.exe" --insecure