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

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-connect-13.0.3-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.
A silent installation can be performed by running the installer with the /S
flag. This will hide
the progress bar and skip the launch of the app after the installation is complete.
"Teleport Connect Setup-13.0.3.exe" /S
User interface

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 search bar (in the middle), which allows you to search for resources across clusters.
- The cluster selector (to the left of the search 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. Also, the "Open new terminal" action will bind new terminal tabs to the selected cluster.
- The additional actions menu (to the left of the profile selector), containing options such as opening a config file or creating an access request in an Enterprise cluster.
The status bar at the bottom displays cluster breadcrumbs in the bottom left, indicating which cluster the current tab is bound to, and the Share Feedback button in the bottom right.
Connecting to an SSH server
- 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. - Look for the SSH server you want to connect to and click the Connect button to the right.
- Select or enter the SSH user you wish to log in as and press
Enter
. - A new tab will open with a shell session on the chosen server.
Alternatively, you can look for the server in the search bar and press Enter
to connect to it.
Opening a local terminal
To open a terminal with a local shell session, either select "Open new terminal" from the additional
actions menu or press Ctrl/Cmd + Shift + T
.
Any tsh command executed within the tab targets the current cluster. Teleport Connect accomplishes
this by setting the environment variables TELEPORT_PROXY
and TELEPORT_CLUSTER
for the session.
Additionally, Teleport Connect prepends the PATH
/Path
environment variable in the session with the
directory containing the tsh binary, even if tsh is not globally available.
When using Trusted Clusters, the cluster selector allows you to determine which cluster the shell session will be bound to. The selected cluster will be reflected in both the tab title and the status bar.
Connecting to a Kubernetes cluster
- 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. - Select the Kubes section.
- Look for the cluster you wish to connect to and click the Connect button to the right.
- A new local terminal tab will open which is preconfigured with the
$KUBECONFIG
environment variable pointing to a configuration for the specified cluster. Any tools that you have installed that respect the$KUBECONFIG
environment variable (kubectl
,helm
, etc.) will work without additional configuration. To identify the path to this config for use in other tools, runecho $KUBECONFIG
.
Alternatively, you can look for the cluster in the search bar and press Enter
to connect to it.
Connecting to a database
- 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. - Select the Databases section.
- Look for the database server you wish to connect to and click the Connect button to the right.
- Select or enter the database user you with to use and press
Enter
. - A new tab will open with a new connection established between your device and the database server.
Alternatively, you can look for the database in the search bar and press Enter
to connect to it.
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.
Using tsh outside of Teleport Connect
Teleport Connect ships with its own bundled version of tsh. Teleport Connect will always use this version of tsh for any actions performed within the app.
Teleport Connect makes tsh available to use in your terminal of choice as well. Please note that at
the moment tsh and Teleport Connect operate on different sets of profiles, as Teleport Connect sets
a custom home location through the TELEPORT_HOME
environment
variable. For example, logging in to a new cluster
through tsh will not make that cluster show up in Teleport Connect.
To add tsh to PATH
, open the additional actions menu and select "Install tsh in PATH". This will
symlink tsh to /usr/local/bin
. You can remove the symlink by selecting "Remove tsh from PATH".
If you used the tsh macOS .pkg installer before, this will overwrite the symlink made by that installer.
During installation, Teleport Connect automatically adds a symlink to tsh under
/usr/local/bin/tsh
, unless you have already installed the teleport
package, which also creates
that symlink.
During installation, Teleport Connect automatically adds the resources\bin
folder from the
installation directory to the Path
user environment variable.
Configuration
Teleport Connect can be configured by editing the app_config.json
file, which it creates on first launch.
To open the config file, select "Open config file" from the additional actions menu.
The file will open in your default editor.
Any changes to the config file will take effect at the next launch.
Below is the list of the supported config properties.
Property | Default | Description |
---|---|---|
usageReporting.enabled | false | Enables collecting anonymous usage data (see Telemetry). |
keymap.tab1 - keymap.tab9 | Command+1 - Command+9 on macOS Ctrl+1 - Ctrl+9 on WindowsAlt+1 - Alt+9 on Linux | Shortcut to open tab 1–9. |
keymap.closeTab | Command+W on macOSCtrl+W on Windows/Linux | Shortcut to close a tab. |
keymap.newTab | Command+T on macOSCtrl+T on Windows/Linux | Shortcut to open a new tab. |
keymap.newTerminalTab | Shift+Command+T on macOSCtrl+Shift+T on Windows/Linux | Shortcut to open a new terminal tab. |
keymap.previousTab | Shift+Command+Tab on macOSCtrl+Shift+Tab on Windows/Linux | Shortcut to go to the previous tab. |
keymap.nextTab | Command+Tab on macOSCtrl+Tab on Windows/Linux | Shortcut to go to the next tab. |
keymap.openConnections | Command+P on macOSCtrl+P on Windows/Linux | Shortcut to open the connection list. |
keymap.openClusters | Command+E on macOSCtrl+E on Windows/Linux | Shortcut to open the cluster selector. |
keymap.openProfiles | Command+I on macOSCtrl+I on Windows/Linux | Shortcut to open the profile selector. |
keymap.openSearchBar | Command+K on macOSCtrl+K on Windows/Linux | Shortcut to open the search bar. |
terminal.fontFamily | Menlo, Monaco, monospace on macOSConsolas, monospace on Windows'Droid Sans Mono', monospace on Linux | Font family for the terminal. |
terminal.fontSize | 15 | Font size for the terminal. |
The additional $schema
property present in the config file allows text editors to provide autocompletion.
It should not be modified.
Configuring keyboard shortcuts
A valid shortcut contains at least one modifier and a single key code, for example Shift+Tab
.
Function keys such as F1
do not require a modifier.
Modifiers and a key code must be combined by the +
character.
Available modifiers:
Control
,Option
,Shift
,Command
on macOS.Ctrl
,Alt
,Shift
on Windows and Linux.
Available key codes:
0
to9
A
toZ
F1
toF24
,
,.
,/
,\
,`
,-
,=
,;
,'
,[
,]
Space
,Tab
,CapsLock
,NumLock
,ScrollLock
,Backspace
,Delete
,Insert
,Enter
,Up
,Down
,Left
,Right
,Home
,End
,PageUp
,PageDown
,Escape
,IntlBackslash
Telemetry
When you first start the app, Teleport Connect asks for permission to collect and send telemetry data. This includes tracking events such as:
- Logging in to a cluster
- Starting an SSH, database, or Kubernetes session
- File transfer during an SSH session
- Creating an Access Request
- Reviewing an Access Request
- Assuming an Access Request
On login, we also collect some device-related data:
- Operating system and its version
- App version
- Processor architecture
Additionally, we ask for a job role (answer is optional).
The full list of events and collected data is defined as protocol buffer messages in the Teleport source. We do not track the details of those events but merely that the given event took place. Each event includes the cluster name and user name anonymized with HMAC using the cluster's internal random UUID as the key. It is infeasible to associate this back to a specific cluster or user without access to the cluster's internal datastore.
Disabling telemetry
If you initially agreed to share telemetry data, but now want to opt out, you need to set usageReporting.enabled
in the config to false
(see Configuration):
"usageReporting.enabled": false
The changes will take effect at the next launch.
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.
Skipping TLS certificate verification
You can open Teleport Connect in insecure mode, which skips TLS certificate verification when talking to a Teleport Proxy Service. This is useful in test environments with self-signed certificates 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 --insecurePassing 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
Uninstalling Teleport Connect
Remove Teleport Connect for MacOS from the Applications directory with this command:
sudo rm -f /Applications/Teleport\ Connect.app
To remove the local user data directory:
rm -rf ~/Library/Application\ Support/Teleport\ Connect
You can uninstall Teleport Connect from the "Apps and Features" section of the Control Panel.
For reference, Teleport Connect binaries are installed to %LOCALAPPDATA%\Programs\teleport-connect
.
To remove the local user data directory:
$ rmdir /s /q "%APPDATA%\Teleport Connect"
For DEB installations uninstall Teleport Connect using APT:
sudo apt remove teleport-connect
For RPM installations uninstall Teleport Connect using YUM:
sudo yum remove teleport-connect
Installs based on a tarball should remove the
teleport-connect
directory and any copied/linked executables.