How to Use Teleport: The Beginner's Guide (First Cluster, the tsh Lesson, First Node, and the Certificate Arc)

CodexFuse Team · 2026-11-02T04:49:10.267Z · 14 min read min read

Search Google for "teleport" and you get magic tricks, Minecraft commands, and sci-fi tropes — not infrastructure software. This guide is about the other Teleport: Teleport, the open-source infrastructure access platform (goteleport.com) from Gravitational, Inc. in Oakland, California, which replaces static SSH keys and bastion hosts with short-lived certificates. If you manage even a handful of Linux servers and are tired of copying keys into authorized_keys by hand, learning how to use Teleport is the single biggest upgrade you can make to your SSH setup. You will need a VPS to run your first cluster on — our VPS hosting guide explains what to look for if you do not have one yet.

This beginner's guide walks you from a fresh server to a working cluster: the mental model, your first install, your first admin user, the tsh login lesson, your first node, and your first RBAC role. Then the extensions — Kubernetes, databases, and session recordings — each in one section. If you searched for "teleport for beginners", you are in the right place: no prior Teleport knowledge is assumed.

What Is Teleport, Exactly?

Teleport is a certificate authority and identity-aware access proxy that implements protocols such as SSH, Kubernetes API, RDP, HTTPS, and a variety of SQL and NoSQL database protocols — that is the vendor's own one-line description on goteleport.com/how-it-works. In plain terms: instead of copying long-lived SSH keys onto every server and every laptop, Teleport issues short-lived certificates that expire automatically, usually after 12 hours. No key ever sits on a server waiting to be stolen.

The project lives at github.com/gravitational/teleport, which holds about 21,059 stars and was created in March 2015; it is licensed GNU AGPL-3.0 (older references to Apache 2.0 are stale). The latest generally available release is v18.10.0, published July 9, 2026. The company behind it raised a $110M Series C in May 2022 led by Bessemer at a $1.1B valuation, and Cisco became its largest strategic investor in August 2026 — Teleport is not a weekend project.

Here is the complete arc this guide follows — the teleport tsh lesson included — so you know where each section takes you:

1. Install the single binary and generate your cluster configuration.
2. Create your first admin user with an invite link.
3. Log in with tsh and receive your first short-lived certificate.
4. Join your first server to the cluster with a token.
5. SSH into that server — key-free.
6. Add an RBAC role so a teammate gets exactly the access they need.

What Do You Need Before You Install?

You need a Linux host with port 443 open, a registered domain name with a valid TLS certificate, and roughly 15 minutes. Port 443 matters because Teleport multiplexes all of its traffic through TLS routing on that single port — no separate ports to open per service.

The official quickstart enforces multi-factor authentication from the first login, and it asks that your tsh/tctl clients stay within one major version of the cluster. If you do not have a server yet, see our VPS hosting guide — any entry-level VPS with the specs above is enough for a test cluster.

How Do You Install Your First Teleport Cluster?

The "teleport install" question has a short answer: you install a single binary, generate a configuration file, and start the service — three steps, all from the official Community quickstart. This is the Teleport self-hosted path; a managed cloud offering exists, but beginners learn the machinery fastest by self-hosting their first cluster.

curl https://cdn.teleport.dev/install.sh | bash -s 18.11.8
sudo teleport configure -o file --acme [email protected] --cluster-name=teleport.example.com
sudo systemctl enable teleport
sudo systemctl start teleport

The --acme flag gets you a free Let's Encrypt certificate automatically; if you prefer your own certificate or a self-signed one for a lab, the docs cover those paths too. In a local container you can simply run sudo teleport start, and the Web UI lands at https://localhost:3080.

Next, create your first admin user. This command assigns the three preset roles and the logins you will use, then prints an invite URL that is valid for one hour, where you set a password and enroll MFA:

sudo tctl users add teleport-admin --roles=editor,access,auditor --logins=root,ubuntu,ec2-user

That is the whole cluster install. Prefer containers? Our Docker beginner guide walks through images and volumes — Teleport ships official images, but the binary path above is the documented beginner route.

What Is the Mental Model? (The Three Services)

Teleport is three services working together: Auth is the certificate authority for your cluster — it issues certificates and runs authentication challenges; Proxy is the cluster frontend — the single entry point that handles user requests and forwards credentials to Auth; Node services (Teleport Agents) run inside your resource networks as smart sidecars that speak each resource's native protocol, enforce access controls, record sessions, and log audit events. Nodes open reverse tunnels out to the Proxy, so they need no inbound ports at all.

The key insight is the certificate arc: you authenticate once (password + MFA, or SSO), the Auth service hands your client a certificate valid for 12 hours by default (default_session_ttl: 12h in the Auth config reference), and every resource trusts certificates signed by your cluster — so no static keys exist anywhere to rotate, leak, or forget.

How Does tsh Login Work?

tsh is the Teleport client: one login command fetches your short-lived certificate, and after that everything is normal SSH. This command is the heart of the tool — worth learning cold.

tsh login --proxy=teleport.example.com [email protected]

Run it and your default browser opens for the login/SSO callback (you can add --browser=none to skip that, --auth=<connector> to pick an SSO connector, or --ttl to shorten the session). Your certificate lands under ~/.tsh/keys/<proxy>/<user>, and tsh loads it into your SSH agent — so plain ssh, scp, and rsync all work without any extra setup. These are the tsh commands a beginner uses every day:

For single sign-on, the Community Edition supports GitHub SSO; OIDC and SAML connectors (Okta, Google Workspace, Microsoft Entra ID) are Enterprise-only. If GitHub is your identity provider, our GitHub beginner guide covers the account side of the setup.

How Do You Add Your First Server to the Cluster?

You generate a short-lived join token, install the Teleport binary on the server, and start it with the token — the server then dials out to your Proxy through its reverse tunnel. Create the token first; it expires after 30 minutes by default, so do not generate it an hour before you need it:

tctl tokens add --type=node --format=text
sudo teleport configure --roles=node --token=<token> --proxy=teleport.example.com -o file
sudo systemctl enable --now teleport

Run tsh ls from your laptop and the new node appears in the list. The ECMWF weather institute's internal wiki — the most-cited real-world deployment note for this pattern — describes exactly this flow for its own gateway, which is a good sign the token-join model holds up at institutional scale.

How Do You SSH Into Your First Node?

This is the "teleport ssh tutorial" payoff: you SSH the way you always have — tsh ssh ubuntu@node1 — except there was never a key exchange. Because your certificate is already in the SSH agent, plain OpenSSH works too: run tsh config to see the config snippet Teleport writes, and any standard ssh client connects using your short-lived cert. When the 12 hours are up, you run tsh login again; there is nothing to rotate.

How Do Roles (RBAC) Work?

Nothing is allowed by default, and deny rules are evaluated before allow rules — that is the whole security posture in one sentence. A role is a YAML resource (kind: role, current version v7) with allow and deny blocks, and the official docs' RBAC example grants logins like ubuntu plus node labels like env: test, with wildcards and regexes supported. The cluster ships three preset roles: editor performs administrative tasks, access connects to any Teleport-protected resource, and auditor views audit events and session recordings.

Here is a beginner-sized role that lets developers log into staging servers only:

kind: role
version: v7
metadata:
  name: developer
spec:
  allow:
    logins: ['ubuntu']
    node_labels:
      'env': 'staging'

Save it as role.yaml and apply it with tctl create -f role.yaml. Assigning that role to a user replaces the old ritual of editing authorized_keys on every staging box.

Teleport vs a Bastion Host: Why Switch?

The "teleport vs bastion" question comes up in every infra team: a bastion host moves the key problem to one server instead of solving it; Teleport removes the keys entirely. Here is the practical difference for a small team:

One clarifying line: Tailscale is a mesh VPN — a different lane entirely (network connectivity vs certificate-based access), so it is never a rival in this comparison. HashiCorp Boundary and StrongDM live in the same zero-trust access lane as Teleport and may get their own write-ups later.

How Do You Access Kubernetes Through Teleport?

You stop distributing kubeconfig files: the Teleport Kubernetes Service issues short-lived credentials on demand, and every kubectl call flows through Teleport's RBAC and audit. Two commands do the whole job:

tsh kube ls
tsh kube login mycluster

tsh kube login writes a kubeconfig context (something like teleport.example.com-minikube) that routes traffic through the proxy to the API server. Your role must allow at least one Kubernetes user or group — e.g. kubernetes_groups: [editor] in the role's allow block. New to clusters themselves? Our Kubernetes beginner guide covers the concepts before you connect them through Teleport.

How Do You Access Databases Through Teleport?

The Database service proxies native database wire protocols and authenticates clients with short-lived Teleport database certificates, so database passwords stop living in chat messages. List and connect like this:

tsh db ls
tsh db connect --db-user=alice --db-name=mysql example-mysql

The supported protocols include postgres, mysql, mongodb, redis, snowflake, sqlserver, cassandra, elasticsearch, opensearch, dynamodb, and clickhouse — one tsh db connect pattern covers all of them.

What Is Recorded, and Where Does It Go?

Session recording is enabled by default: SSH, Kubernetes shell, and desktop sessions get full terminal recordings you can replay later, while the audit log stores structured events — logins, RBAC changes, session starts — with identity, remote IP, timestamp, and session ID. Replay a session from the CLI with tsh play <session-id> or join a live one with tsh join <session-id>, choosing the observer, moderator, or peer mode.

Recordings are stored in a local directory, Amazon S3 (and S3-compatible stores), Google Cloud Storage, or Azure Blob Storage; audit events can additionally go to PostgreSQL, CockroachDB, DynamoDB, or Firestore. Recordings can be encrypted at rest, and since Teleport 18.11 you can export desktop recordings to MP4 with tsh recordings export.

How Much Does Teleport Cost?

The Community Edition is free to self-host — one line, since that is the beginner path in this guide. Teleport Enterprise is quote-based and bills on two usage metrics, quoted here from the vendor's pricing guide: a Monthly Active User (any unique interactive local or SSO user active at least once in the month) and a Teleport Protected Resource (any unique resource — SSH server, Kubernetes cluster, database instance, desktop — registered at least once in the month, hourly-averaged). The vendor publishes no dollar figures; third-party estimates exist (Vendr publishes per-resource ranges), but treat those as estimates, not prices, and expect them to move.

7 Beginner Mistakes With Teleport

Sources

1. Teleport GitHub repository — stars, license, tagline (github.com/gravitational/teleport)
2. Teleport "How it works" — certificate authority and identity-aware access proxy definition (goteleport.com/how-it-works)
3. Teleport Community quickstart — install one-liner, configure, services, preset roles, MFA default (goteleport.com/docs/get-started/deploy-community)
4. Teleport Auth config reference — default_session_ttl: 12h (goteleport.com/docs/reference/deployment/config)
5. tsh CLI reference — login, ls, ssh, config, logout, kube, db, join commands (goteleport.com/docs/ver/19.x/reference/cli/tsh)
6. tctl CLI reference — users add, tokens add defaults (goteleport.com/docs/ver/19.x/reference/cli/tctl)
7. Join Services with a Secure Token — node join flow (goteleport.com/docs/enroll-resources/agents/join-token)
8. Deploy Teleport agent — configure --roles=node flow (goteleport.com/download/deploy-teleport-agent)
9. Server access RBAC — role examples and wildcard labels (goteleport.com/docs/enroll-resources/server-access/rbac)
10. Audit guide — session recordings and playback (goteleport.com/docs/ver/19.x/get-started/audit)
11. Kubernetes access — tsh kube login mechanics (goteleport.com/docs/enroll-resources/kubernetes-access/manage-access)
12. Database access — MySQL self-hosted example (goteleport.com/docs/enroll-resources/database-access/enrollment/self-hosted/mysql-self-hosted)
13. Integrate an identity provider — GitHub on Community, OIDC/SAML Enterprise (goteleport.com/docs/ver/19.x/zero-trust-access/sso/integrate-idp)
14. Teleport pricing and pricing guide — MAU/TPR metrics, quote-based Enterprise (goteleport.com/pricing and goteleport.com/pricing/guide)
15. ECMWF internal wiki — institutional jump-host pattern evidence (confluence.ecmwf.int)
16. Complete Teleport Tutorial for Beginners 2026 — independent walkthrough, tsh ssh forms (coursedrill.com/teleport-tutorial-for-beginners)

Frequently Asked Questions

Is Teleport free?

Yes — the Community Edition is free to self-host, which covers everything in this guide. Teleport Enterprise is a separate, quote-based product that bills on monthly active users and protected resources; the vendor publishes no list prices.

Do I need a domain name to run Teleport?

Yes. The Proxy is the single TLS-routed entry point on port 443, so it needs a registered domain and a valid certificate. The quickstart's --acme flag gets you a free Let's Encrypt certificate automatically during configuration.

Can I keep using plain OpenSSH clients with Teleport?

Yes. After tsh login, your short-lived certificate lives under ~/.tsh/keys/ and is loaded into your SSH agent, so ssh, scp, and rsync work normally. Run tsh config to see the OpenSSH snippet Teleport writes for you.

How long do Teleport certificates last?

User certificates last 12 hours by default (default_session_ttl), node join tokens last 30 minutes, and admin invite URLs last 1 hour. When a certificate expires you simply log in again — there are no keys to rotate.

Is Teleport the same as a VPN like Tailscale?

No. A mesh VPN gives your devices network connectivity; Teleport gives identities short-lived, RBAC-checked, fully audited access to specific resources over their native protocols. They solve different problems and can even be used together.