

Installing Teleport: Overview
Length: 03:04
This guide shows you how to install Teleport binaries on your platform, including:
teleport
tsh
tctl
tbot
If you are new to Teleport, we recommend following our getting started guide.
For best results, Teleport clients (tsh
, tctl
, tbot
) should be the same major
version as the cluster they are connecting to. Teleport servers are compatible
with clients that are on the same major version or one major version older.
Teleport servers do not support clients that are on a newer major version.
See our Upgrading guide for more information.
Operating system support
Teleport is officially supported on the platforms listed below. It is worth noting that the open-source community has been successful in building and running Teleport on UNIX variants other than Linux [1].
Operating System | teleport Daemon | tctl Admin Tool | tsh and Teleport Connect User Clients [2] | Web UI (via the browser) | tbot Daemon |
---|---|---|---|---|---|
Linux v2.6.23+ (RHEL/CentOS 7+, Ubuntu 14.04+, and Debian 8+) [3] | yes | yes | yes | yes | yes |
macOS v10.13+ (High Sierra) | yes | yes | yes | yes | yes |
Windows 10+ (rev. 1607) [4] | no | no | yes | yes | no |
[1] Teleport is written in Go and it's possible to build it on any OS supported by the Golang toolchain.
[2] tsh
is a Command Line Client (CLI) and Teleport Connect is a Graphical User Interface (GUI) desktop client. See
Using Teleport Connect for usage and installation.
[3] Enhanced Session Recording requires Linux kernel v5.8+.
[4] Teleport server does not run on Windows yet, but tsh
and Teleport Connect (the Teleport desktop clients)
supports most features on Windows 10 and later.
Linux
All installations include teleport
, tsh
, tctl
, and tbot
.
Feature support
Some Teleport features have additional requirements:
Feature | Requirement | Debian | Ubuntu | CentOS/RHEL | Amazon Linux |
---|---|---|---|---|---|
Enhanced Session Recording | Kernel v5.8+ | 11, or 10 with backports | 20.04.2+ | 9+ | 2 (post 11/2021), 2023 |
Automatic Updates | systemd-based | 8+ | 16.04+ | 7+ | 2, 2023 |
Installation through apt/yum repos | systemd-based | 8+ | 16.04+ | 7+ | 2, 2023 |
apt
and yum
repos don't expose packages for all distribution variants.
When following installation instructions, you might need to replace ID
with
ID_LIKE
to install packages of the closest supported distribution.
Currently supported distributions (and ID
) are:
- RHEL >= 7 (
rhel
) - CentOS >= 7 (
centos
) - Debian >= 8 (
debian
) - Ubuntu >= 16.04 (
ubuntu
) - Amazon Linux 2 and 2023 (
amzn
)
Installation instructions
When running Teleport in production, we recommend that you follow the practices below to avoid security incidents. These practices may differ from the examples used in this guide, which are intended for demo environments:
- Avoid using
sudo
in production environments unless it's necessary. - Create new, non-root, users and use test instances for experimenting with Teleport.
- Run Teleport's services as a non-root user unless required. Only the SSH
Service requires root access. Note that you will need root permissions (or
the
CAP_NET_BIND_SERVICE
capability) to make Teleport listen on a port numbered <1024
(e.g.443
). - Follow the "Principle of Least Privilege" (PoLP). Don't give users
permissive roles when giving them more restrictive roles will do instead.
For example, assign users the built-in
access,editor
roles. - When joining a Teleport resource service (e.g., the Database Service or
Application Service) to a cluster, save the invitation token to a file.
Otherwise, the token will be visible when examining the
teleport
command that started the agent, e.g., via thehistory
command on a compromised system.
Use the appropriate commands for your environment to install your package.
Teleport Edition
Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.ascSource variables about OS version
source /etc/os-releaseAdd the Teleport APT repository for v13. You'll need to update this
file for each major release of Teleport.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v13" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/nullsudo apt-get updatesudo apt-get install teleport
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for v13. You'll need to update this
file for each major release of Teleport.
sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v13/teleport.repo")"sudo yum install teleportTip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for v13. You'll need to update this
file for each major release of Teleport.
Use the dnf config manager plugin to add the teleport RPM repo
sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v13/teleport.repo")"Install teleport
sudo dnf install teleportTip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
In the example commands below, update $SYSTEM_ARCH
with the appropriate
value (amd64
, arm64
, or arm
). All example commands using this variable
will update after one is filled out.
curl https://get.gravitational.com/teleport-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gzshasum -a 256 teleport-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gzcd teleportsudo ./install
Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.ascSource variables about OS version
source /etc/os-releaseAdd the Teleport APT repository for v13. You'll need to update this
file for each major release of Teleport.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v13" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/nullsudo apt-get updatesudo apt-get install teleport-ent
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo apt-get install teleport-ent-fips
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for v13. You'll need to update this
file for each major release of Teleport.
sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v13/teleport.repo")"sudo yum install teleport-entTip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo yum install teleport-ent-fips
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for v13. You'll need to update this
file for each major release of Teleport.
Use the dnf config manager plugin to add the teleport RPM repo
sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v13/teleport.repo")"Install teleport
sudo dnf install teleport-entTip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo dnf install teleport-ent-fips
In the example commands below, update $SYSTEM_ARCH
with the appropriate
value (amd64
, arm64
, or arm
). All example commands using this variable
will update after one is filled out.
curl https://get.gravitational.com/teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gzshasum -a 256 teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gzcd teleport-entsudo ./install
For FedRAMP/FIPS-compliant installations of Teleport Enterprise, package URLs will be slightly different:
curl https://get.gravitational.com/teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-fips-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-fips-bin.tar.gzshasum -a 256 teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-fips-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-fips-bin.tar.gzcd teleport-entsudo ./install
Please use the latest version of Teleport Enterprise documentation.
If you've previously installed Teleport via the APT
repo at https://deb.releases.teleport.dev/
, you can upgrade by
re-running the "Debian/Ubuntu (DEB)" install instructions above.
We will also continue to maintain the legacy APT repo at
https://deb.releases.teleport.dev/
for the foreseeable future.
Check the Downloads page for the most up-to-date information.
Docker
We provide a pre-built multi-arch Docker image for every version of Teleport,
including images for amd64
, arm
, and arm64
architectures. Our images contain only Teleport binaries
and their application dependencies.
These images are hosted on Amazon ECR Public. All tags under public.ecr.aws/gravitational/teleport-distroless
are Teleport Open Source images.
The table below gives an idea of how our image naming scheme works. We offer images that point to a static version of Teleport as well as images that are automatically rebuilt every night. These nightly images point to the latest version of Teleport from the three most recent release branches. They are stable, and we recommend their use to keep your Teleport installation up to date.
Image name | Teleport version | Image automatically updated? | Troubleshooting Tools? | Image base |
---|---|---|---|---|
public.ecr.aws/gravitational/teleport-distroless:13 | The latest version of Teleport Open Source | Yes | No | Distroless Debian 11 |
public.ecr.aws/gravitational/teleport-distroless-debug:13 | The latest version of Teleport Open Source | Yes | Yes | Distroless Debian 11 |
public.ecr.aws/gravitational/teleport-distroless:13.0.3 | The version specified in the image's tag (i.e. 13.0.3) | No | No | Distroless Debian 11 |
public.ecr.aws/gravitational/teleport-distroless-debug:13.0.3 | The version specified in the image's tag (i.e. 13.0.3) | No | Yes | Distroless Debian 11 |
For testing, we always recommend that you use the latest released version of Teleport, which is currently public.ecr.aws/gravitational/teleport-distroless:13.0.3
.
The *-debug
images include a Busybox shell and tool suite in addition to Teleport, and are intended for troubleshooting deployments only. They are not intended for production use.
Ubuntu 20.04-based images are available from our Legacy Amazon ECR Public repository. Their use is considered deprecated, and they may be removed in future releases.
We provide pre-built amd64
, arm
, and arm64
Docker images for every version of Teleport Enterprise.
This table gives an idea of how our image naming scheme works. We offer images which point to a static version of Teleport Enterprise, as well as images which are automatically rebuilt every night. Our images contain only Teleport binaries and their application dependencies.
Nightly images point to the latest version of Teleport Enterprise from the three most recent release branches. They are stable, and we recommend their use to easily keep your Teleport Enterprise installation up to date.
These images are hosted on our Amazon ECR Public repository.
All tags under public.ecr.aws/gravitational/teleport-ent-distroless
are
Teleport Enterprise images. Each tag points to a multi-arch image, containing
Teleport for arm
, arm64
and amd64
.
FIPS images are still posted to our Legacy Amazon ECR Public repository.
You can specify the architecture of a Teleport FIPS Docker image by adding a
postfix to the image tag, e.g., public.ecr.aws/gravitational/teleport:13-arm64
.
Versions without an architecture postfix use the amd64
architecture, e.g.,
public.ecr.aws/gravitational/teleport:13
.
Image name | Open Source or Enterprise? | Teleport version | Image automatically updated? | Includes troubleshooting tools | Image base |
---|---|---|---|---|---|
public.ecr.aws/gravitational/teleport-ent-distroless:13 | Enterprise | The latest version of Teleport Enterprise 13 | Yes | No | Distroless Debian 11 |
public.ecr.aws/gravitational/teleport-ent-distroless-debug:13 | Enterprise | The latest version of Teleport Enterprise 13 | Yes | Yes | Distroless Debian 11 |
public.ecr.aws/gravitational/teleport-ent:13-fips | Enterprise FIPS | The latest version of Teleport Enterprise 13 FIPS | Yes | Yes | Ubuntu 20.04 |
public.ecr.aws/gravitational/teleport-ent-distroless:13.0.3 | Enterprise | The version specified in the image's tag (i.e. 13.0.3) | No | No | Distroless Debian 11 |
public.ecr.aws/gravitational/teleport-ent-distroless-debug:13.0.3 | Enterprise | The version specified in the image's tag (i.e. 13.0.3) | No | Yes | Distroless Debian 11 |
public.ecr.aws/gravitational/teleport-ent-distroless:13.0.3-fips | Enterprise FIPS | The version specified in the image's tag (i.e. 13.0.3) | No | Yes | Ubuntu 20.04 |
For testing, we always recommend that you use the latest release version of
Teleport Enterprise, which is currently public.ecr.aws/gravitational/teleport-ent-distroless:13.0.3
.
Ubuntu 20.04-based images for non-FIPS Teleport are available from our Legacy Amazon ECR Public repository.
The *-debug
images include a Busybox shell and tool suite in addition to Teleport,
and are intended for troubleshooting deployments only. They are not intended for production use.
Helm
To allow Helm to install charts that are hosted in the Teleport Helm repository, use helm repo add
:
helm repo add teleport https://charts.releases.teleport.dev
To update the cache of charts from the remote repository, run helm repo update
:
helm repo update
There are two charts available to install. Please see our guide for using each chart.
Chart | Included Services | Values Reference |
---|---|---|
teleport-cluster | Auth Service Proxy Service Other Teleport services if using a custom configuration | Reference |
teleport-kube-agent | Kubernetes Service Application Service Database Service | Reference |
macOS
Teleport Edition
You can download one of the following .pkg installers for macOS:
Link | Binaries |
---|---|
teleport-13.0.3.pkg | teleport tctl tsh tbot |
tsh-13.0.3.pkg | tsh |
You can also fetch an installer via the command line:
curl -O https://cdn.teleport.dev/teleport-13.0.3.pkgInstalls on Macintosh HD
sudo installer -pkg teleport-13.0.3.pkg -target /Password:
installer: Package name is teleport-13.0.3
installer: Upgrading at base path /
installer: The upgrade was successful.
which teleport/usr/local/bin/teleport
The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.
Warnings
We recommend the use of our official Teleport packages. Binaries provided by Homebrew are not signed by Teleport, so features that require signed and notarized binaries (TouchID, Device Trust) are not available in Homebrew builds.
The tctl
release available on Homebrew is the open source edition, and
cannot manage configuration resources unique to Teleport Enterprise and
Teleport Enterprise Cloud (e.g., OIDC and SAML connectors). For Teleport
Enterprise and Enterprise Cloud, we recommend installing the official Teleport
Enterprise edition of tctl
.
Installing open source Teleport with Homebrew
To install Teleport with Homebrew, run the following command:
brew install teleport
If you choose to use Homebrew, you must verify that the versions of tsh
and tctl
you run on your local machine are compatible with the versions
you run on your infrastructure. Homebrew usually ships the latest release of
Teleport, which may be incompatible with older versions. See our
compatibility policy for details.
To verify versions, log in to your cluster and compare the output of tctl status
against tsh version
and tctl version
.
You can download one of the following .pkg installers for macOS:
Link | Binaries |
---|---|
teleport-ent-13.0.3.pkg | teleport tctl tsh tbot |
tsh-13.0.3.pkg | tsh |
You can also fetch an installer from the command line:
curl -O https://cdn.teleport.dev/teleport-ent-13.0.3.pkgInstall on Macintosh HD
sudo installer -pkg teleport-ent-13.0.3.pkg -target /Password:
installer: Package name is teleport-ent-13.0.3
installer: Upgrading at base path /
installer: The upgrade was successful.
which teleport/usr/local/bin/teleport
Windows (tsh client only)
Starting with Teleport v7.2.0, most tsh
features are supported for Windows 10
1607+. The tsh ssh
command can be run under cmd.exe
, PowerShell, and Windows
Terminal.
To install tsh
on Windows, run the following commands in PowerShell:
Get the expected checksum for the Windows tsh package
$Resp = Invoke-WebRequest https://get.gravitational.com/teleport-v13.0.3-windows-amd64-bin.zip.sha256PowerShell will return the binary representation of the response content
by default, so you need to convert it to a string
[System.Text.Encoding]::UTF8.getstring($Resp.Content)<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-v13.0.3-windows-amd64-bin.zipcertUtil -hashfile teleport-v13.0.3-windows-amd64-bin.zip SHA256SHA256 hash of teleport-v13.0.3-windows-amd64-bin.zip:
<checksum>
CertUtil: -hashfile command completed successfully.
After you have verified that the checksums match, you can extract the archive.
The executable will be available at
teleport-v13.0.3-windows-amd64-bin\teleport\tsh.exe
.
Expand-Archive teleport-v13.0.3-windows-amd64-bin.zipcd teleport-v13.0.3-windows-amd64-bin\teleport.\tsh.exe versionTeleport v13.0.3 git:v13.0.3 go1.20
Make sure to move tsh.exe
into your PATH.
Building from source
Teleport is written in Go, and currently requires go v1.20 or newer. Detailed instructions for building from source are available in the README.
Checksums
If you want to verify the integrity of a Teleport binary, SHA256 checksums are available for all downloads on our downloads page.

If you download Teleport via an automated system, you can programmatically
obtain the checksum by adding .sha256
to the download link. This is the method
shown in the installation examples.
export version=v13.0.3'darwin' 'linux' or 'windows'
export os=linux'386' 'arm' on linux or 'amd64' for all distros
export arch=amd64curl https://get.gravitational.com/teleport-$version-$os-$arch-bin.tar.gz.sha256<checksum> <filename>
Uninstalling Teleport
If you wish to uninstall Teleport at any time, see our documentation on Uninstalling Teleport.
Next steps
Now that you know how to install Teleport, you can enable access to all of your infrastructure. Get started with: