{"token_count": 1724}

# Installing Teleport on macOS

This guide explains how to install Teleport on macOS, including client tools for connecting to an existing Teleport cluster and the Teleport service for running agents.

For an overview of Teleport installation methods and supported platforms, see [Installation](https://goteleport.com/docs/installation/single-machine.md).

## Operating system support

Teleport supports macOS 12 (Monterey) and later for both Intel and Apple Silicon Macs.

### Install client tools

Most macOS users install Teleport to connect to an existing cluster. Teleport provides several client tools:

| Tool             | Description                                                                      |
| ---------------- | -------------------------------------------------------------------------------- |
| `tsh`            | Command-line client for SSH, database access, Kubernetes, and application access |
| `tctl`           | Administrative CLI for managing Teleport clusters (cluster administrators only)  |
| Teleport Connect | Desktop application with a graphical interface for accessing resources           |

Choose one of the following methods to install the Teleport client tools.

### Teleport Connect

Teleport Connect is a desktop application that provides a graphical interface for connecting to SSH servers, databases, Kubernetes clusters, and web applications.

Download Teleport Connect from the [Downloads page](https://goteleport.com/download/) or directly:

[Teleport Connect 18.10.0](https://cdn.teleport.dev/Teleport%20Connect-18.10.0.dmg)

Open the `.dmg` file and drag Teleport Connect to your Applications folder.

To install `tsh` from Teleport Connect, click the three-dot menu in the upper-right corner of the Teleport Connect window and select **Install tsh in PATH**.

---

**CHECKPOINT: Verify Teleport Connect installation**

Before proceeding, verify: Confirm that Teleport Connect is installed and can connect to your cluster.

If the check fails, troubleshoot:

1. Open Teleport Connect from your Applications folder.
2. Click **Connect** and enter your Teleport cluster address (e.g., `example.teleport.sh`).
3. Complete the login flow.
4. Verify you can see available resources in the Teleport Connect window.

Here are some troubleshooting tips:

- If macOS blocks the application, go to **System Settings** > **Privacy & Security** and click **Open Anyway**.
- If you cannot connect, verify the cluster address is correct and that you have network access to the cluster.
- For SSO login issues, ensure your browser is set as the default and allows pop-ups from the Teleport cluster domain.

---

### Command-line tools only

If you prefer to use `tsh` and `tctl` without the desktop application, download the PKG installer:

[`teleport-18.10.0.pkg`](https://cdn.teleport.dev/teleport-18.10.0.pkg)

This universal installer works on both Intel and Apple Silicon Macs.

You can also fetch and run the installer via the command line:

```
$ curl -O https://cdn.teleport.dev/teleport-18.10.0.pkg
$ sudo installer -pkg teleport-18.10.0.pkg -target /
installer: Package name is teleport-18.10.0
installer: Upgrading at base path /
installer: The upgrade was successful.
```

---

**CHECKPOINT: Verify tsh installation**

Before proceeding, verify: Confirm that the Teleport client tools are installed and you can log in to your cluster.

If the check fails, troubleshoot:

1. Verify `tsh` is installed:

```
$ tsh version
```

2. Log in to your Teleport cluster:

```
$ tsh login --proxy=example.teleport.sh
```

Replace `example.teleport.sh` with your cluster's address.

3. List available resources:

```
$ tsh ls
```

Here are some troubleshooting tips:

- If `tsh` is not found, check where it's installed:

```
$ which tsh
```

- If you see `installer: must be run as root` when running the installer command, add `sudo` before the `installer` command.
- If login fails with a certificate error, check that your system time is correct.
- For SSO login issues, ensure your default browser allows pop-ups from the Teleport cluster domain.

---

For more information on using `tsh`, see the [tsh reference](https://goteleport.com/docs/connect-your-client/teleport-clients/tsh.md).

For more information on Teleport Connect, see [Using Teleport Connect](https://goteleport.com/docs/connect-your-client/teleport-clients/teleport-connect.md).

## Running Teleport services on macOS

The client tools above (`tsh`, `tctl`, Teleport Connect) are used to *connect to* a Teleport cluster on demand—you run them when you want to access a resource, then they exit when you're done.

Teleport *services* are different: they run continuously as background daemons. The `teleport` daemon can run cluster components (Auth Service, Proxy Service) or agent services that enroll resources like servers, databases, or applications into your cluster. The `tbot` daemon provides machine identity for automated workloads. Most macOS users only need the client tools. You would install Teleport services on macOS primarily for:

- Local development and testing of Teleport configurations
- Running a Teleport Agent to enroll your Mac as a resource in a cluster

| Binary     | Description                                                                                                                                                                 |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `teleport` | The Teleport daemon for running cluster services or agents                                                                                                                  |
| `tbot`     | Teleport Machine & Workload Identity issues and renews short-lived certificates so your machines can access Teleport protected resources in the same way your engineers do. |

### Install Teleport services

If you haven't already, download and run the PKG installer:

[`teleport-18.10.0.pkg`](https://cdn.teleport.dev/teleport-18.10.0.pkg)

```
$ curl -O https://cdn.teleport.dev/teleport-18.10.0.pkg
$ sudo installer -pkg teleport-18.10.0.pkg -target /
Password
installer: Package name is teleport-18.10.0
installer: Upgrading at base path /
installer: The upgrade was successful.
$ which teleport
/usr/local/bin/teleport
```

### Verify Teleport is installed

```
$ teleport version
```

---

NOTE

Running Teleport services in production is typically done on Linux servers. macOS is primarily used for client access and local development. For production deployments, see [Installing Teleport on Linux](https://goteleport.com/docs/installation/single-machine/linux.md).

---

For guidance on configuring and running Teleport, see:

- [Teleport daemon on macOS via launchd](https://goteleport.com/docs/enroll-resources/server-access/macos-launchd.md)
- [Deploy a Cluster](https://goteleport.com/docs/installation/self-hosted.md) for self-hosted deployments
- [Machine ID Getting Started](https://goteleport.com/docs/machine-workload-identity/workload-identity/getting-started.md) for workload identity

---

DANGER

We do not recommend using Homebrew to install Teleport. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

---