Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gravitational/teleport/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through deploying a self-hosted Teleport Community Edition cluster on a single Linux server. The resulting cluster runs the Auth Service, Proxy Service, and SSH Service in a single teleport process — ideal for homelabs, staging environments, or evaluating Teleport before a production deployment. The Teleport Auth Service and Proxy Service together form the control plane of your cluster. The SSH Service is an example of a Teleport agent that manages access to a resource — in this case, the Linux host itself.
If you want to skip infrastructure provisioning and start using Teleport immediately, sign up for a free Teleport Enterprise Cloud trial. The Cloud Quickstart covers that path.

​
Prerequisites

  • A Linux host (physical, VM, or cloud instance such as AWS EC2) with:
    • Port 443 open to inbound traffic from the internet (or your users’ network).
    • The ability to install software and run commands as root or via sudo.
  • A registered domain name with two DNS A records pointing to the host’s public IP:
    RecordPurpose
    teleport.example.comTraffic to the Proxy Service from users and agents
    *.teleport.example.comSubdomains for web apps registered with Teleport
  • A multi-factor authenticator app such as Authy, Google Authenticator, or 1Password.
1

Install Teleport

Choose the installation method that matches your Linux distribution. All methods install the same teleport, tsh, and tctl binaries.
# Installs the latest stable release automatically
curl https://goteleport.com/static/install.sh | bash -s latest
Verify the installation:
teleport version
2

Configure teleport.yaml

Generate a minimal configuration file using the teleport configure command. The command requires a domain name and a TLS certificate.
# Teleport will obtain and renew a certificate from Let's Encrypt automatically.
# Port 443 must be reachable from the internet for the ACME challenge.
sudo teleport configure -o file \
  --acme \
  --acme-email=user@example.com \
  --cluster-name=teleport.example.com
This writes a configuration file to /etc/teleport.yaml. The generated file contains three service stanzas:
# /etc/teleport.yaml (generated — key fields shown)
version: v3
teleport:
  nodename: teleport.example.com
  data_dir: /var/lib/teleport
  log:
    output: stderr
    severity: INFO

auth_service:
  enabled: true
  cluster_name: teleport.example.com
  listen_addr: 0.0.0.0:3025

proxy_service:
  enabled: true
  public_addr: teleport.example.com:443
  https_keypairs: []     # populated automatically when using --acme
  acme:
    enabled: true
    email: user@example.com

ssh_service:
  enabled: true
  listen_addr: 0.0.0.0:3022
  labels:
    env: demo
The SSH Service is enabled by default. This means the host running Teleport will automatically enroll itself as an SSH node in your cluster — you can SSH into it immediately after completing setup.
3

Start the Teleport service

Enable and start the Teleport systemd unit:
sudo systemctl enable teleport
sudo systemctl start teleport
Check that the service started cleanly:
sudo systemctl status teleport
You should see active (running). If Teleport fails to start, check the logs:
sudo journalctl -u teleport --no-pager -n 50
Once running, open your browser at https://teleport.example.com. You should see the Teleport welcome screen. Accept the Community Edition terms to proceed.
If you are using Let’s Encrypt, Teleport must be able to serve the ACME HTTP-01 challenge on port 80 or the TLS-ALPN-01 challenge on port 443. Ensure your firewall allows traffic on port 443 from all sources. Certificate issuance may take up to 60 seconds on the first start.
4

Create the first admin user with tctl

tctl is the Teleport administration CLI. On your Teleport host, run the following command to create a local user named teleport-admin with full administrative privileges:
sudo tctl users add teleport-admin \
  --roles=editor,access,auditor \
  --logins=root,ubuntu,ec2-user
The command prints a one-time invitation URL:
User "teleport-admin" has been created but requires a password. Share this URL
with the user to complete user setup, link is valid for 1h:
https://teleport.example.com:443/web/invite/123abc456def789ghi123abc456def78

NOTE: Make sure teleport.example.com:443 points at a Teleport proxy which users can access.
Open the URL in a browser, set a strong password, and enroll your MFA device (OTP or WebAuthn hardware key).
The --logins flag specifies which OS user accounts on SSH hosts this Teleport user is allowed to use. The accounts listed (root, ubuntu, ec2-user) must already exist on the target Linux host or you will receive an authentication error when you try to connect. Create any missing accounts with sudo adduser <login> before connecting.
Create a second local admin user as a fallback to prevent lockout:
sudo tctl users add teleport-admin-backup \
  --roles=editor,access,auditor \
  --logins=root,ubuntu,ec2-user
5

Log in with tsh

Install tsh on your local workstation (the machine you use day-to-day, not the Teleport server):
brew install teleport
Authenticate against your self-hosted cluster:
tsh login --proxy=teleport.example.com --user=teleport-admin
After completing MFA, you receive a short-lived certificate:
> Profile URL:        https://teleport.example.com:443
  Logged in as:       teleport-admin
  Cluster:            teleport.example.com
  Roles:              access, auditor, editor
  Logins:             root, ubuntu, ec2-user
  Kubernetes:         enabled
  Valid until:        2024-06-01 09:00:00 -0000 UTC [valid for 12h0m0s]
  Extensions:         permit-agent-forwarding, permit-port-forwarding, permit-pty
6

Connect to the enrolled node

Because the Teleport SSH Service is running on the same host as your cluster, that host is already enrolled as an SSH node. List available nodes:
tsh ls

Node Name              Address          Labels
---------------------- ---------------- ----------
teleport.example.com   127.0.0.1:3022   env=demo
Open an SSH session:
tsh ssh root@teleport.example.com
You are now inside an SSH session proxied through Teleport. The session is fully recorded and emits structured audit events. To verify, open the Teleport Web UI, navigate to Audit → Session Recordings, and find the session you just created.
To enroll additional Linux servers, follow the same process from the Web UI: click Enroll New Resource, select your distribution, and run the generated install script on the target host. Each agent connects outbound to your Proxy Service — no firewall changes are needed on the enrolled servers.

​
Next steps

Enroll more servers

Add more Linux servers to your cluster using the Web UI guided workflow or the Teleport install script.

Add Kubernetes access

Deploy the Teleport Kubernetes Service to proxy kubectl traffic with RBAC and full audit logging.

Configure access controls

Create custom roles that enforce least-privilege access and restrict users to the specific resources they need.

Set up SSO

Integrate with Okta, GitHub, Microsoft Entra ID, or another SAML/OIDC provider so your team logs in with existing credentials.

Cluster architecture

Learn how to scale your self-hosted deployment with separate Auth and Proxy Service instances for high availability.

Configuration reference

Explore the full teleport.yaml configuration file reference for all available options and service settings.

Build docs developers (and LLMs) love

Get started for freeTalk to us