tbot: Configuring the Machine Identity Agent for Teleport

tbot is the agent that powers Teleport Machine Identity. It runs on your infrastructure — on a Linux host, inside a Kubernetes pod, or within a CI/CD job — and is responsible for authenticating to the Teleport cluster and writing short-lived certificates to a configured destination. Tools like ssh, kubectl, psql, and custom applications then use those certificates to access Teleport-protected resources without ever holding a long-lived credential. tbot is designed to be both simple and flexible. For CI/CD workloads it runs in one-shot mode, joining the cluster once, issuing credentials, and exiting immediately. For long-running processes it runs as a daemon, continuously renewing credentials before they expire.

Installation

tbot is distributed as part of the Teleport client tools package and is available for Linux, macOS, and Windows. On Linux, it is most commonly installed via the system package manager alongside the rest of the Teleport binaries. Verify the installation:

tbot version

Running tbot

Daemon mode (long-running)

In daemon mode tbot continuously renews credentials in the background. This is the recommended mode for production deployments on Linux servers or Kubernetes clusters.

tbot start -c /etc/tbot.yaml

On Linux, use the tbot install systemd command to generate and install a systemd unit file:

tbot install systemd \
  --write \
  --user teleport \
  --group teleport

One-shot mode (CI/CD)

In one-shot mode tbot authenticates, issues credentials once, and exits. Use the --oneshot flag:

tbot start --oneshot -c ./tbot.yaml

This is the correct mode for ephemeral CI/CD environments where the job finishes after the credentials have been used.

The configure subcommand

The tbot configure subcommand generates a tbot.yaml configuration file from command-line flags and writes it to stdout or a file:

# Generate a config for SSH access and write it to a file
tbot configure identity \
  --destination=file:///opt/machine-id \
  --proxy-server=example.teleport.sh:443 \
  --token=my-bot-token \
  --join-method=github \
  > /etc/tbot.yaml

The init subcommand

tbot init initializes a destination directory with the correct ownership and POSIX ACLs so that a separate process (different user) can read the credentials tbot writes:

tbot init \
  --destination-dir=/opt/machine-id \
  --bot-user=teleport \
  --reader-user=jenkins

This is useful when tbot runs as the teleport user but the consuming process (e.g. Jenkins) runs as a different user.

tbot.yaml configuration

tbot is fully driven by a YAML configuration file. The file has five top-level sections: version, cluster address, onboarding (authentication), storage, and services (what credentials to produce).

Minimal example

version: v2
proxy_server: example.teleport.sh:443
onboarding:
  join_method: github
  token: my-github-bot-token
storage:
  type: memory
services:
  - type: identity
    destination:
      type: directory
      path: /opt/machine-id

Full example: SSH and Kubernetes outputs

This configuration runs tbot as a daemon, issues SSH credentials to one directory, and issues a Kubernetes kubeconfig to another — all from a single tbot process.

version: v2

# Address of the Teleport Proxy
proxy_server: example.teleport.sh:443

# How tbot authenticates to the cluster on first run.
# Use the join method appropriate for your platform.
onboarding:
  join_method: iam          # AWS IAM join; change to github, gitlab, etc.
  token: my-bot-token

# How long the issued certificates should be valid.
# tbot will renew them automatically before they expire.
credential_ttl: 1h

# How often tbot renews certificates. Must be less than credential_ttl.
renewal_interval: 20m

# Where tbot stores its own internal renewable credentials.
# Use "memory" for ephemeral environments, "directory" for persistent deployments.
storage:
  type: directory
  path: /var/lib/teleport/bot

# Services define what credentials tbot produces and where it writes them.
services:
  # SSH identity output — writes ssh_config and certificates for OpenSSH
  - type: identity
    destination:
      type: directory
      path: /opt/machine-id/ssh

  # Kubernetes output — writes a kubeconfig for a specific cluster
  - type: kubernetes/v2
    selectors:
      - name: my-k8s-cluster
    destination:
      type: directory
      path: /opt/machine-id/k8s

  # Workload Identity API — exposes a SPIFFE Workload API socket
  - type: workload-identity-api
    listen: unix:///opt/machine-id/workload.sock
    selector:
      name: my-workload-identity

Configuration reference

Top-level fields

Field	Description
`version`	Configuration version. Always `v2` for current deployments.
`proxy_server`	Address of the Teleport Proxy in `host:port` form.
`auth_server`	Address of the Teleport Auth Server directly (not recommended; use `proxy_server`).
`credential_ttl`	Duration for which issued certificates are valid (e.g. `1h`, `5m`). Maximum is 24 hours.
`renewal_interval`	How often `tbot` renews certificates. Must be less than `credential_ttl`.
`oneshot`	If `true`, `tbot` exits after issuing credentials once.
`debug`	Enables verbose debug logging.
`storage`	Configuration for tbot’s internal state (see Storage).
`onboarding`	Authentication configuration (see Onboarding).
`services`	List of outputs to generate (see Services).

Onboarding

The onboarding block controls how tbot authenticates to the Teleport cluster on first run.

onboarding:
  join_method: github   # github, gitlab, circleci, iam, gcp, azure, kubernetes, token, etc.
  token: my-token       # Name of the join token created in Teleport

Supported join methods include: github, gitlab, circleci, bitbucket, azure_devops, iam (AWS), gcp, azure, kubernetes, spacelift, terraform_cloud, tpm, token, and others.

The token join method uses a one-time shared secret. For production deployments, prefer a delegated join method (GitHub, AWS IAM, GCP, etc.) that relies on platform-provided identity rather than a stored secret.

Storage

The storage block configures where tbot keeps its internal renewable credentials — the bot’s own identity, not the output artifacts.

# In-memory storage (lost on restart; suitable for CI/CD)
storage:
  type: memory

# Directory storage (persists across restarts; recommended for daemons)
storage:
  type: directory
  path: /var/lib/teleport/bot

Never share the storage directory between multiple tbot instances. Each tbot process must have its own storage path. Sharing storage causes certificate generation counter mismatches and will lock the bot.

Services

Services define the credentials tbot outputs. Multiple services can be configured in a single tbot instance.

identity (SSH and Teleport API)

Writes SSH credentials and an ssh_config file for use with OpenSSH or the Teleport API client.

- type: identity
  destination:
    type: directory
    path: /opt/machine-id/ssh

kubernetes/v2

Writes a kubeconfig.yaml file for Kubernetes cluster access. The v2 variant supports multiple clusters and dynamic label selectors.

- type: kubernetes/v2
  selectors:
    - name: my-cluster          # Match by exact name
    - labels:                   # Or match by label
        env: production
  destination:
    type: directory
    path: /opt/machine-id/k8s

workload-identity-api

Exposes a SPIFFE Workload API socket. Workloads connect to this socket to receive SVIDs and trust bundles.

- type: workload-identity-api
  listen: unix:///opt/machine-id/workload.sock
  selector:
    name: my-workload-identity

workload-identity-x509

Writes X.509 SVID files (svid.pem, svid_key.pem, ca.pem) to a directory.

- type: workload-identity-x509
  destination:
    type: directory
    path: /opt/machine-id/svid
  selector:
    name: my-workload-identity

workload-identity-jwt

Writes a JWT SVID to a file.

- type: workload-identity-jwt
  destination:
    type: directory
    path: /opt/machine-id/jwt
  selector:
    name: my-workload-identity
  audiences:
    - https://sts.amazonaws.com

Output destinations

Each service writes to a destination. Three destination types are available:

Kubernetes Secret

Writes credentials into a Kubernetes Secret. Useful when tbot runs as a Kubernetes deployment and other pods need to consume the credentials.

destination:
  type: kubernetes_secret
  name: teleport-bot-credentials
  namespace: default

Memory

Stores credentials in memory only. They are lost when tbot exits. Suitable for short-lived CI/CD jobs.

destination:
  type: memory

Certificate renewal

In daemon mode, tbot renews certificates automatically. The renewal cycle is:

tbot issues credentials with a TTL of credential_ttl (default: 1 hour).
tbot waits for renewal_interval before renewing (default: 20 minutes, or certificate TTL divided by 3 if unset).
Before the renewal interval elapses, tbot contacts the Auth Service and issues fresh certificates, replacing the previous ones in the destination.
Consuming processes that watch the credential files (e.g. SPIFFE SDKs) pick up the new certificates automatically.

The maximum credential_ttl is 24 hours. This limit exists to bound the window of exploitation if a certificate is compromised and to encourage short-lived credential practices.

If tbot fails to renew (e.g. due to a network partition), it keeps the existing certificates active until they expire. Once renewed, it resumes normal operation.

Key commands

tbot start

Starts tbot with a configuration file:

tbot start -c /etc/tbot.yaml

Flags:

Flag	Description
`-c`, `--config`	Path to the configuration file
`--oneshot`	Exit after issuing credentials once
`--debug`	Enable verbose logging
`--proxy-server`	Override the proxy address from the config file
`--token`	Override the join token from the config file
`--join-method`	Override the join method from the config file
`--diag-addr`	Address to expose diagnostics endpoint

tbot configure

Generates a tbot.yaml from flags:

tbot configure identity \
  --proxy-server=example.teleport.sh:443 \
  --token=my-bot-token \
  --join-method=iam \
  --destination=file:///opt/machine-id \
  > /etc/tbot.yaml

Available subcommands match the service types: identity, kubernetes, kubernetes/v2, database, application, workload-identity-api, workload-identity-x509, workload-identity-jwt, and others.

tbot init

Initializes a destination directory:

tbot init \
  --destination-dir=/opt/machine-id \
  --bot-user=teleport \
  --reader-user=myapp

tbot spiffe-inspect

Tests the SPIFFE Workload API by requesting SVIDs from the socket:

tbot spiffe-inspect --path unix:///opt/machine-id/workload.sock

tbot install systemd

Generates and installs a systemd unit file:

tbot install systemd \
  --write \
  --user teleport \
  --group teleport \
  --name tbot

Global flags

These flags apply to all tbot commands:

Flag	Default	Description
`-c`, `--config`	—	Path to the configuration file
`-d`, `--debug`	`false`	Enable verbose logging to stdout
`--log-format`	`text`	Log output format: `text` or `json`
`--fips`	`false`	Enable FIPS compliance mode
`--insecure`	`false`	Trust the cluster certificate on first connect without verification (do not use in production)

Environment variables

Variable	Description
`TBOT_CONFIG_PATH`	Path to the configuration file (equivalent to `--config`)
`TBOT_DEBUG`	Enable verbose logging (equivalent to `--debug`)
`TELEPORT_PROXY`	Teleport Proxy address
`TELEPORT_BOT_TOKEN`	Join token value or path to a file containing the token
`TELEPORT_AUTH_SERVER`	Teleport Auth Server address (prefer `TELEPORT_PROXY`)

Next steps

Getting Started

Follow a complete walkthrough: create a bot, issue certificates, and access a server from GitHub Actions.

Workload Identity

Configure tbot to expose a SPIFFE Workload API for service-to-service authentication.

Introduction

Learn the core concepts: bots, join tokens, bot instances, and artifacts.

tctl Reference

Manage bots, tokens, roles, and bot instances from the command line with tctl.

Get Started

Enroll Resources

Access Controls

Machine & Workload Identity

Deployment & Operations

Documentation Index

​Installation

​Running tbot

​Daemon mode (long-running)

​One-shot mode (CI/CD)

​The configure subcommand

​The init subcommand

​tbot.yaml configuration

​Minimal example

​Full example: SSH and Kubernetes outputs

​Configuration reference

​Top-level fields

​Onboarding

​Storage

​Services

​identity (SSH and Teleport API)

​kubernetes/v2

​workload-identity-api

​workload-identity-x509

​workload-identity-jwt

​Output destinations

​Directory

​Kubernetes Secret

​Memory

​Certificate renewal

​Key commands

​tbot start

​tbot configure

​tbot init

​tbot spiffe-inspect

​tbot install systemd

​Global flags

​Environment variables

​Next steps

Getting Started

Workload Identity

Introduction

tctl Reference

Build docs developers (and LLMs) love

Installation

Running tbot

Daemon mode (long-running)

One-shot mode (CI/CD)

The configure subcommand

The init subcommand

tbot.yaml configuration

Minimal example

Full example: SSH and Kubernetes outputs

Configuration reference

Top-level fields

Onboarding

Storage

Services

identity (SSH and Teleport API)

kubernetes/v2

workload-identity-api

workload-identity-x509

workload-identity-jwt

Output destinations

Directory

Kubernetes Secret

Memory

Certificate renewal

Key commands

tbot start

tbot configure

tbot init

tbot spiffe-inspect

tbot install systemd

Global flags

Environment variables

Next steps