tbot CLI Reference — Teleport Machine Identity Agent

tbot is the Machine Identity agent for Teleport’s Machine ID feature. It programmatically issues and continuously renews short-lived certificates for services, workloads, and CI/CD pipelines — eliminating the need for long-lived secrets. tbot supports SPIFFE-compatible X.509 and JWT SVIDs, Kubernetes credentials, database credentials, and SSH identities.

tbot [<flags>] <command> [<args> ...]

tbot requires a bot identity registered with the cluster via tctl bots add. The bot uses a join token (or a bound keypair) to authenticate and then continuously renews its credentials.

Global Flags

These flags apply to every tbot subcommand.

Flag	Default	Description
`-c`, `--config`	no default	Path to a configuration file.
`-d`, `--[no-]debug`	`false`	Enable verbose logging to stdout.
`--log-format`	`text`	Log output format: `json` or `text`.
`--[no-]fips`	`false`	Enable FIPS compliance mode. Requires a FIPS-compliant binary.
`--[no-]insecure`	`false`	Trust the Auth Server or Proxy certificate on first connect without verification. Do not use in production.

Global Environment Variables

Variable	Default	Description
`TBOT_CONFIG_PATH`	no default	Path to a configuration file (same as `--config`).
`TBOT_DEBUG`	`false`	Enable verbose logging to stdout.

`tbot start`

Start tbot in daemon mode to continuously issue and renew credentials. The start command accepts a sub-service type that determines what kind of output credentials are produced.

`tbot start legacy`

Start tbot with a configuration file or a legacy output (certificates written to a directory).

tbot start legacy [<flags>]

Flag	Default	Description
`--proxy-server`	no default	Address of the Teleport Proxy Server.
`-a`, `--auth-server`	no default	Address of the Teleport Auth Server.
`--token`	no default	Bot join token or path to a file with a token value.
`--join-method`	no default	Join method: `token`, `iam`, `ec2`, `gcp`, `github`, `gitlab`, `kubernetes`, `azure`, `azure_devops`, `bitbucket`, `circleci`, `spacelift`, `tpm`, `terraform_cloud`, `oracle`, `bound_keypair`, `env0`.
`--ca-pin`	no default	CA pin to validate the Auth Server on first connect.
`--destination-dir`	no default	Directory to write short-lived machine certificates.
`--data-dir`	no default	Directory for internal bot state. Access should be restricted.
`--certificate-ttl`	no default	TTL of short-lived machine certificates.
`--renewal-interval`	no default	How often to renew certificates (must be less than the certificate TTL).
`--storage`	no default	A destination URI for tbot’s internal storage, e.g. `file:///foo/bar`.
`--[no-]oneshot`	`false`	Quit after the first credential renewal.
`--[no-]scoped`	`false`	Indicates whether tbot should run in scoped mode. Required when authenticating as a scoped Bot.
`--pid-file`	no default	Full path to the PID file.
`--diag-addr`	no default	If set in debug mode, a diagnostics service will listen on this address.

Example:

tbot start legacy \
  --proxy-server=teleport.example.com:443 \
  --token=/var/lib/teleport/bot-token \
  --destination-dir=/opt/machine-id \
  --data-dir=/var/lib/teleport/bot

`tbot start identity`

Start tbot and produce an identity output for SSH and Teleport API access.

tbot start identity --destination=DESTINATION [<flags>]

Flag	Default	Description
`--destination`	no default	Destination URI, e.g. `file:///opt/machine-id`.
`--proxy-server`	no default	Address of the Teleport Proxy Server.
`-a`, `--auth-server`	no default	Address of the Teleport Auth Server.
`--token`	no default	Bot join token.
`--join-method`	no default	Method to use to join the cluster.
`--join-uri`	no default	An optional URI with joining and authentication parameters.
`--ca-pin`	no default	CA pin to validate the Auth Server on first connect.
`--certificate-ttl`	no default	TTL of short-lived certificates.
`--renewal-interval`	no default	Renewal interval.
`--cluster`	no default	Specific leaf cluster for which to issue an identity.
`--[no-]allow-reissue`	`false`	Allow reissue of the credentials output by this command.
`--storage`	no default	Destination URI for `tbot`’s internal storage.
`--reader-user`	no default	Additional Linux user allowed by ACLs to read the destination.
`--reader-group`	no default	Additional Linux group allowed by ACLs to read the destination.
`--registration-secret`	no default	For bound keypair joining, specifies a registration secret for use at first join.
`--registration-secret-path`	no default	For bound keypair joining, specifies a file containing a registration secret.
`--static-key-path`	no default	For bound keypair joining, specifies a path to a static key.
`--[no-]oneshot`	`false`	Quit after the first credential renewal.
`--[no-]scoped`	`false`	Indicates whether tbot should run in scoped mode.
`--pid-file`	no default	Full path to the PID file.
`--diag-addr`	no default	If set in debug mode, a diagnostics service will listen on this address.

Example:

tbot start identity \
  --destination=file:///opt/machine-id \
  --proxy-server=teleport.example.com:443 \
  --token=my-bot-token

`tbot start database`

Start tbot and produce database credentials as output.

tbot start database --destination=DESTINATION --service=SERVICE \
  --username=USERNAME --database=DATABASE [<flags>]

Flag	Default	Description
`--destination`	no default	Destination URI.
`--service`	no default	The database service name.
`--username`	no default	The database user name.
`--database`	no default	The name of the database.
`--format`	no default	Credential format: `tls`, `mongo`, `cockroach`.
`--proxy-server`	no default	Address of the Teleport Proxy Server.
`--token`	no default	Bot join token.
`--certificate-ttl`	no default	TTL of short-lived certificates.
`--renewal-interval`	no default	Renewal interval.
`--storage`	no default	Destination URI for `tbot`’s internal storage.
`--reader-user`	no default	Additional Linux user allowed by ACLs to read the destination.
`--reader-group`	no default	Additional Linux group allowed by ACLs to read the destination.

Example:

tbot start database \
  --destination=file:///opt/machine-id/db \
  --service=my-postgres-db \
  --username=app_user \
  --database=production \
  --proxy-server=teleport.example.com:443 \
  --token=my-bot-token

`tbot start kubernetes`

Start tbot and produce Kubernetes credentials.

tbot start kubernetes --destination=DESTINATION \
  --kubernetes-cluster=KUBERNETES-CLUSTER [<flags>]

Flag	Default	Description
`--destination`	no default	Destination URI.
`--kubernetes-cluster`	no default	Name of the Kubernetes cluster in Teleport.
`--proxy-server`	no default	Address of the Teleport Proxy Server.
`--token`	no default	Bot join token.
`--certificate-ttl`	no default	TTL of short-lived certificates.
`--renewal-interval`	no default	Renewal interval.
`--storage`	no default	Destination URI for `tbot`’s internal storage.
`--reader-user`	no default	Additional Linux user allowed by ACLs to read the destination.
`--reader-group`	no default	Additional Linux group allowed by ACLs to read the destination.
`--[no-]disable-exec-plugin`	`false`	Disable the exec plugin (allows credentials to be used without the `tbot` binary).
`--[no-]oneshot`	`false`	Quit after the first credential renewal.
`--[no-]scoped`	`false`	Indicates whether tbot should run in scoped mode.

Example:

tbot start kubernetes \
  --destination=file:///opt/machine-id/kube \
  --kubernetes-cluster=my-cluster \
  --proxy-server=teleport.example.com:443 \
  --token=my-bot-token

`tbot start workload-identity-x509`

Start tbot and produce a SPIFFE-compatible X.509 SVID output.

tbot start workload-identity-x509 --destination=DESTINATION [<flags>]

Flag	Default	Description
`--destination`	no default	Destination URI, e.g. `file:///opt/svid`.
`--name-selector`	no default	The name of the workload identity to issue. Mutually exclusive with `--label-selector`.
`--label-selector`	no default	A label-based selector for which workload identities to issue. Mutually exclusive with `--name-selector`.
`--[no-]include-federated-trust-bundles`	`false`	If set, include federated trust bundles in the output.
`--proxy-server`	no default	Address of the Teleport Proxy Server.
`--token`	no default	Bot join token.
`--join-method`	no default	Method to use to join the cluster.
`--join-uri`	no default	An optional URI with joining and authentication parameters.
`--ca-pin`	no default	CA pin to validate the Auth Server on first connect.
`--certificate-ttl`	no default	TTL of short-lived certificates.
`--renewal-interval`	no default	Renewal interval.
`--storage`	no default	Destination URI for `tbot`’s internal storage.
`--reader-user`	no default	Additional Linux user allowed by ACLs to read the destination.
`--reader-group`	no default	Additional Linux group allowed by ACLs to read the destination.
`--registration-secret`	no default	For bound keypair joining, specifies a registration secret for use at first join.
`--registration-secret-path`	no default	For bound keypair joining, specifies a file containing a registration secret.
`--static-key-path`	no default	For bound keypair joining, specifies a path to a static key.
`--[no-]oneshot`	`false`	Quit after the first credential renewal.
`--[no-]scoped`	`false`	Indicates whether tbot should run in scoped mode.
`--pid-file`	no default	Full path to the PID file.
`--diag-addr`	no default	If set in debug mode, a diagnostics service will listen on this address.

Example:

tbot start workload-identity-x509 \
  --destination=file:///opt/svid \
  --name-selector=my-workload-identity \
  --proxy-server=teleport.example.com:443 \
  --token=my-bot-token

`tbot start workload-identity-api`

Start tbot with a workload identity API listener. Compatible with the SPIFFE Workload API and Envoy SDS.

tbot start workload-identity-api --listen=LISTEN [<flags>]

Flag	Default	Description
`--listen`	no default	The address on which the workload identity API should listen. Prefixed with `unix://` or `tcp://`.
`--name-selector`	no default	The name of the workload identity to issue. Mutually exclusive with `--label-selector`.
`--label-selector`	no default	A label-based selector for which workload identities to issue. Mutually exclusive with `--name-selector`.
`--proxy-server`	no default	Address of the Teleport Proxy Server.
`-a`, `--auth-server`	no default	Address of the Teleport Auth Server.
`--token`	no default	Bot join token.
`--join-method`	no default	Method to use to join the cluster.
`--join-uri`	no default	An optional URI with joining and authentication parameters.
`--ca-pin`	no default	CA pin to validate the Auth Server on first connect.
`--certificate-ttl`	no default	TTL of short-lived certificates.
`--renewal-interval`	no default	Renewal interval.
`--storage`	no default	Destination URI for `tbot`’s internal storage.
`--registration-secret`	no default	For bound keypair joining, specifies a registration secret for use at first join.
`--registration-secret-path`	no default	For bound keypair joining, specifies a file containing a registration secret.
`--static-key-path`	no default	For bound keypair joining, specifies a path to a static key.
`--[no-]oneshot`	`false`	Quit after the first credential renewal.
`--[no-]scoped`	`false`	Indicates whether tbot should run in scoped mode.
`--pid-file`	no default	Full path to the PID file.
`--diag-addr`	no default	If set in debug mode, a diagnostics service will listen on this address.

Example:

tbot start workload-identity-api \
  --listen=unix:///run/spiffe.sock \
  --name-selector=my-workload \
  --proxy-server=teleport.example.com:443 \
  --token=my-bot-token

`tbot configure`

Generate tbot configuration output as YAML — useful for creating a tbot.yaml file without manually writing it. The configure subcommands mirror the start subcommands but print configuration YAML instead of starting the agent.

tbot configure <service-type> [<flags>]

Available service types: legacy, identity, database, database-tunnel, kubernetes, kubernetes/v2, application, application-proxy, application-tunnel, workload-identity-x509, workload-identity-jwt, workload-identity-api, workload-identity-aws-roles-anywhere, ssh-multiplexer, noop Example — generate identity config:

tbot configure identity \
  --destination=file:///opt/machine-id \
  --proxy-server=teleport.example.com:443 \
  --token=my-bot-token

Example — write to a config file:

tbot configure legacy \
  --proxy-server=teleport.example.com:443 \
  --token=my-bot-token \
  --destination-dir=/opt/machine-id \
  --data-dir=/var/lib/teleport/bot \
  > /etc/tbot.yaml

`tbot init`

Initialize a destination directory for writes from a separate bot user. This sets up POSIX ACLs so that the bot can write certificates but another process (your workload) can only read them.

tbot init [<flags>]

Flag	Default	Description
`--destination-dir`	no default	Directory to write short-lived machine certificates.
`--init-dir`	no default	If using a config file with multiple destinations, controls which destination dir to configure.
`--bot-user`	no default	Enables POSIX ACLs and defines Linux user that can read/write short-lived certificates.
`--reader-user`	no default	Enables POSIX ACLs and defines Linux user that will read short-lived certificates.
`--owner`	no default	Linux `user:group` owner of the destination directory. Defaults to the Linux user running tbot if unspecified.
`--[no-]clean`	`false`	If set, removes unexpected files and directories from the destination.
`-a`, `--auth-server`	no default	Address of the Teleport Auth Server.
`--proxy-server`	no default	Address of the Teleport Proxy Server.

Example:

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

`tbot proxy`

Start a local TLS proxy via tsh to connect to Teleport in single-port mode. Used when the workload needs to connect through the proxy.

tbot proxy [<flags>] [<args>...]

Flag	Default	Description
`--destination-dir`	no default	The destination directory to provide `tsh` for authentication.
`--proxy-server`	no default	Address of the Teleport Proxy Server in `host:port` form.
`--cluster`	no default	The cluster name. Extracted from the certificate if unset.

Example:

tbot proxy \
  --destination-dir=/opt/machine-id \
  --proxy-server=teleport.example.com:443 \
  -- ssh --proxy my-node

`tbot version`

Print the version of the tbot binary.

tbot version

`tbot.yaml` Configuration

While tbot can be started entirely from flags, using a YAML configuration file is recommended for production deployments. Use tbot configure to generate a config file. Example tbot.yaml:

version: v2
proxy_server: teleport.example.com:443
onboarding:
  join_method: token
  token: /var/lib/teleport/bot-token
storage:
  type: directory
  path: /var/lib/teleport/bot
outputs:
  - type: identity
    destination:
      type: directory
      path: /opt/machine-id

Key configuration fields:

Field	Description
`version`	Configuration schema version (use `v2`).
`proxy_server`	Address of the Teleport Proxy Service.
`auth_server`	Address of the Teleport Auth Service (prefer `proxy_server`).
`onboarding.join_method`	How to join the cluster: `token`, `iam`, `ec2`, `gcp`, `github`, `gitlab`, `kubernetes`, `tpm`, etc.
`onboarding.token`	Token value or path to a file containing the token.
`storage.type`	Internal state storage type. Use `directory` for filesystem storage.
`storage.path`	Path to the internal state directory (restrict access to the bot user).
`outputs`	List of credential output configurations.
`certificate_ttl`	Default TTL for issued certificates.
`renewal_interval`	How often to renew certificates (must be less than `certificate_ttl`).
`oneshot`	If `true`, quit after the first renewal.
`debug`	Enable verbose debug logging.
`fips`	Enable FIPS 140 compliance mode.
`diag_addr`	Address for the diagnostics/healthz endpoint.

The storage.path directory contains the bot’s private key material. Restrict access to this directory to the tbot process user only. If an attacker gains access to this directory, they can impersonate the bot.

`tbot install systemd`

Generate and install a systemd unit file for tbot.

tbot install systemd [<flags>]

Flag	Default	Description
`--name`	`tbot`	Name for the systemd unit.
`--user`	`teleport`	User the service runs as.
`--group`	`teleport`	Group the service runs as.
`--systemd-directory`	`/etc/systemd/system`	Directory where the unit file is written.
`--pid-file`	no default	Overrides the PID file path set in the systemd unit file.
`--[no-]write`	`false`	Write the unit file. If not set, outputs to stdout (dry-run).
`--[no-]force`	`false`	Overwrite existing unit file if present.
`--[no-]anonymous-telemetry`	`false`	Enable anonymous telemetry.

Example:

# Preview the unit file
tbot install systemd

# Write the unit file
tbot install systemd --write

Use tbot wait --diag-addr=127.0.0.1:3040 to block until a running tbot instance reports all services healthy — useful in initialization scripts that must wait for credentials to be available before starting a workload.

CLI Reference

Configuration & API

tbot CLI Reference — Teleport Machine Identity Agent

Global Flags

Global Environment Variables

`tbot start`

`tbot start legacy`

`tbot start identity`

`tbot start database`

`tbot start kubernetes`

`tbot start workload-identity-x509`

`tbot start workload-identity-api`

`tbot configure`

`tbot init`

`tbot proxy`

`tbot version`

`tbot.yaml` Configuration

`tbot install systemd`

Build docs developers (and LLMs) love

CLI Reference

Configuration & API

Documentation Index

​Global Flags

​Global Environment Variables

​tbot start

​tbot start legacy

​tbot start identity

​tbot start database

​tbot start kubernetes

​tbot start workload-identity-x509

​tbot start workload-identity-api

​tbot configure

​tbot init

​tbot proxy

​tbot version

​tbot.yaml Configuration

​tbot install systemd

Build docs developers (and LLMs) love

Global Flags

Global Environment Variables

`tbot start`

`tbot start legacy`

`tbot start identity`

`tbot start database`

`tbot start kubernetes`

`tbot start workload-identity-x509`

`tbot start workload-identity-api`

`tbot configure`

`tbot init`

`tbot proxy`

`tbot version`

`tbot.yaml` Configuration

`tbot install systemd`