Teleport Core Concepts: Clusters, Services, and Clients

Before you deploy Teleport or follow any of the how-to guides, it helps to understand the vocabulary and the roles each component plays. This page explains how the pieces fit together so that configuration decisions make intuitive sense from your first day with the platform.

Teleport cluster

The fundamental unit of a Teleport deployment is a cluster. A cluster is the combination of a Teleport Auth Service and a Teleport Proxy Service, plus any number of Teleport services (also called agents) that proxy access to resources in your infrastructure.

                         ┌──────────────────────────────┐
                         │        Teleport Cluster        │
                         │                              │
  User / tsh / browser ──►  Proxy Service (port 443)   │
                         │         │                    │
                         │         ▼                    │
                         │  Auth Service (internal)     │
                         │   • Certificate Authority    │
                         │   • Audit Log                │
                         │   • RBAC Engine              │
                         └──────────┬───────────────────┘
                                    │  reverse tunnel
                    ┌───────────────┼───────────────┐
                    ▼               ▼               ▼
             SSH Agent        K8s Agent       DB Agent
           (Linux server)  (k8s cluster)   (PostgreSQL)

In a minimal setup — such as a demo or homelab — all three services can run in a single teleport process on one Linux host. For production, the Auth Service and Proxy Service form the control plane and can be scaled independently, while agents run alongside the resources they protect.

Teleport Auth Service

The Auth Service is the heart of every Teleport cluster. It acts as:

A certificate authority (CA) that issues short-lived X.509 and SSH certificates to users, services, and agents.
An access control engine that evaluates roles and attributes before issuing certificates.
An audit log sink that stores structured events for every session and admin action.
A backend API (gRPC) that all Teleport agents and client tools communicate with.

The Auth Service is the only Teleport component that must be connected to a persistent storage backend (such as etcd, DynamoDB, or a local file system for single-node setups). All other services — agents, the Proxy Service, and client tools — are stateless and interact with the Auth Service over the gRPC API.

If you are a Teleport Enterprise Cloud customer, the Auth Service is fully managed by Teleport’s team. You never touch it directly.

Teleport Proxy Service

The Proxy Service is the public-facing component of a Teleport cluster. It:

Listens on a single port (typically 443) and terminates TLS for all incoming connections from users, browsers, and tsh.
Forwards authenticated requests to the appropriate agent via a reverse tunnel, so agents never need to open inbound firewall ports.
Terminates and records sessions for SSH, Kubernetes, RDP, and database protocols.
Serves the Teleport Web UI — a browser-based console for accessing resources and reviewing audit logs.

Because agents connect outbound to the Proxy Service and not the other way around, you can protect resources behind NAT or inside private networks without any VPN or bastion host. The only publicly reachable port is 443 on the Proxy Service.

Teleport services

A Teleport service (often called an agent) manages access to a specific category of infrastructure resource. Each teleport process can run one or more services simultaneously. Here is a summary of all available services:

SSH Service

An OpenSSH-compatible server that enforces Teleport access controls, records sessions, and emits structured audit events. The SSH Service is enabled by default when you start teleport without specifying otherwise. When a user runs tsh ssh user@host, the request flows through the Proxy Service to the SSH Service, which validates the user’s certificate and enforces role-based login restrictions before opening the session. Read more: Server Access

Kubernetes Service

Proxies HTTP traffic to a Kubernetes API server. It intercepts kubectl and Helm requests, enforces RBAC, and emits audit events for every API call — including exec and port-forward that bypass normal Kubernetes audit logs. Read more: Kubernetes Access

Database Service

Proxies TCP connections in the native wire protocols of popular databases: PostgreSQL, MySQL, MongoDB, CockroachDB, Redis, and others. It enforces database-level RBAC and records every query in the audit log. Read more: Database Access

Application Service

Proxies HTTP and TCP traffic to internal web applications and cloud provider APIs such as the AWS Console, GCP Console, and Azure Portal. Applications appear in the Teleport Web UI and are accessible through a browser or with tsh apps login. Read more: Application Access

Desktop Service

Proxies Remote Desktop Protocol (RDP) traffic to Windows desktops. Users access Windows machines through the Teleport Web UI (a browser-based RDP client) with full session recording, clipboard controls, and role-based restrictions — no RDP client software needed. Read more: Desktop Access

Discovery Service

Continuously scans cloud environments (AWS, GCP, Azure) for new resources — EC2 instances, RDS databases, EKS clusters, and more — and automatically enrolls them into your Teleport cluster based on configured discovery rules. This eliminates manual agent deployment for dynamic cloud infrastructure.

`tbot` (Machine & Workload Identity)

tbot is a lightweight binary (separate from the main teleport binary) that provisions short-lived credentials to workloads, CI/CD pipelines, and AI agents. It continuously renews certificates before they expire, so automation never relies on long-lived static secrets. Read more: Machine & Workload Identity

Certificates and authentication

Teleport uses certificate-based authentication for everything. When a user authenticates (via SSO or local credentials + MFA), the Auth Service issues them a short-lived certificate — typically valid for 8–12 hours — signed by Teleport’s CA. This certificate encodes:

The user’s identity (username).
The roles assigned to the user.
The OS logins the user is allowed to use on SSH hosts.
An expiry time after which the certificate is automatically invalid.

Agents are configured to trust only certificates signed by the cluster’s CA. When a certificate expires, the user must re-authenticate — there is no way to extend a stolen or leaked certificate.

Never share or copy Teleport-issued certificates between users or machines. Each identity should always authenticate independently to receive its own certificate. Teleport’s certificate rotation tooling (tctl auth rotate) can invalidate all existing certificates at once if you suspect a compromise.

Roles

A role is a configuration resource stored on the Auth Service backend that defines a set of permissions. Roles are restrictive by default — a user without an explicit allow rule cannot access anything. Key role attributes include:

logins — OS user accounts the role may use when connecting via SSH.
node_labels — Label selectors that restrict which servers the role can access.
kubernetes_groups / kubernetes_users — Kubernetes RBAC bindings applied when proxying to a cluster.
db_names / db_users — Database names and user accounts allowed for database sessions.
request — Rules controlling which other roles a user may request via Access Requests.

Teleport users

A Teleport user is the identity under which a person, machine, or AI agent authenticates to a cluster. There are two kinds:

Local users — stored directly in the Auth Service backend. Created with tctl users add. Used for administrative fallback accounts and machine identities.
SSO users — authenticated via an external identity provider (Okta, GitHub, Google Workspace, Entra ID). Teleport creates a temporary local user record for the lifetime of the certificate.

Configuration resources

Configuration resources are documents stored on the Auth Service backend that define the behaviour of your cluster. They are managed with tctl or the Teleport Web UI. Examples include:

Resource type	Purpose
`role`	Defines permissions for a set of users
`user`	Represents a local Teleport identity
`auth_connector`	Connects Teleport to an external SSO provider
`trusted_cluster`	Establishes a trust relationship between two Teleport clusters
`token`	A join token that authorises a new agent to register with the cluster

Teleport clients

Teleport ships three client tools that users and administrators use every day:

`tsh`

The primary CLI client for end users. Used to authenticate (tsh login), open SSH sessions (tsh ssh), run kubectl commands (tsh kube login), connect to databases (tsh db login), and manage active sessions. Learn more in the tsh reference.

`tctl`

The administrative CLI for cluster operators. Used to manage users, roles, tokens, trusted clusters, and audit events. Typically run on the Auth Service host or by an authenticated administrator. Learn more in the tctl reference.

Teleport Connect

A graphical desktop application (macOS, Windows, Linux) that provides a point-and-click interface for SSH, database, Kubernetes, and application access — powered by the same certificate-based auth as tsh.

Teleport editions

All Teleport editions share the same open-source core from the gravitational/teleport repository. The editions differ in deployment model, support terms, and the availability of certain enterprise features.

Edition	Deployment model	Notable extras
Enterprise Cloud	Auth + Proxy managed by Teleport	Automatic upgrades, managed certificates, dedicated `.teleport.sh` subdomain
Enterprise (Self-Hosted)	You manage all infrastructure	FIPS 140-2 mode, HSM support, commercial support SLA
Community Edition	Free, self-hosted	Core access features; no FIPS or HSM

Get Started

Enroll Resources

Access Controls

Machine & Workload Identity

Deployment & Operations

Teleport Core Concepts: Clusters, Services, and Clients

Teleport cluster

Teleport Auth Service

Teleport Proxy Service

Teleport services

SSH Service

Kubernetes Service

Database Service

Application Service

Desktop Service

Discovery Service

`tbot` (Machine & Workload Identity)

Certificates and authentication

Roles

Teleport users

Configuration resources

Teleport clients

`tsh`

`tctl`

Teleport Connect

Teleport editions

Build docs developers (and LLMs) love

Get Started

Enroll Resources

Access Controls

Machine & Workload Identity

Deployment & Operations

Documentation Index

​Teleport cluster

​Teleport Auth Service

​Teleport Proxy Service

​Teleport services

​SSH Service

​Kubernetes Service

​Database Service

​Application Service

​Desktop Service

​Discovery Service

​tbot (Machine & Workload Identity)

​Certificates and authentication

​Roles

​Teleport users

​Configuration resources

​Teleport clients

​tsh

​tctl

​Teleport Connect

​Teleport editions

Build docs developers (and LLMs) love

Teleport cluster

Teleport Auth Service

Teleport Proxy Service

Teleport services

SSH Service

Kubernetes Service

Database Service

Application Service

Desktop Service

Discovery Service

`tbot` (Machine & Workload Identity)

Certificates and authentication

Roles

Teleport users

Configuration resources

Teleport clients

`tsh`

`tctl`

Teleport Connect

Teleport editions