Skip to main content
Version: 19.x (unreleased)

Run Teleport as a launchd Service on macOS

Report an Issue

This guide explains how to configure Teleport to run as a persistent launchd service on macOS. It is intended for administrators who are running a macOS machine as a Teleport node and want the Teleport daemon to start automatically at boot and remain continuously connected to the cluster.

This page focuses specifically on macOS service management and assumes that node enrollment is complete and a valid /etc/teleport.yaml configuration file is already in place. See the configuration reference page for more information.

How it works​

A launchd service ensures that the Teleport daemon starts automatically when your Mac boots and restarts if it ever exits unexpectedly. This keeps the node continuously connected to your Teleport cluster without requiring manual intervention.

After the first successful join, Teleport stores its host identity in the configured data_dir (by default /var/lib/teleport). On subsequent starts, including automatic restarts by launchd, Teleport uses this stored identity to reconnect to the cluster without requiring a join token.

Prerequisites​

  • The teleport binary is installed on your Mac. See Installing Teleport on macOS for instructions.
  • A valid /etc/teleport.yaml configuration file is in place and the node has successfully joined the cluster.
  • You have confirmed that Teleport runs successfully with:
sudo teleport start --config=/etc/teleport.yaml

After confirming Teleport starts correctly, you can configure it to run automatically at system startup using launchd. This ensures that Teleport starts at boot, restarts automatically if it exits, and the node remains continuously connected to the cluster.

Step 1/4. Confirm the Teleport binary path​

Confirm the location of the teleport binary installed using an official Teleport distribution (for example, the macOS .pkg installer or official tarball):

which teleport
/usr/local/bin/teleport
Important

Use the exact path returned by which teleport in the LaunchDaemon configuration below. An incorrect path will prevent the service from loading.

Step 2/4. Create a LaunchDaemon​

Teleport must run as root. Configure it as a LaunchDaemon, not a LaunchAgent. LaunchAgents run in the user session and do not have the permissions required by Teleport services.

Create the file /Library/LaunchDaemons/com.teleport.node.plist with the following content. Replace the binary path if your installation differs:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>com.goteleport.node</string>

    <key>UserName</key>
    <string>root</string>

    <key>ProgramArguments</key>
    <array>
      <string>/usr/local/bin/teleport</string>
      <string>start</string>
      <string>--config=/etc/teleport.yaml</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <true/>

    <key>StandardOutPath</key>
    <string>/var/log/teleport.out.log</string>

    <key>StandardErrorPath</key>
    <string>/var/log/teleport.err.log</string>
  </dict>
</plist>

The StandardOutPath and StandardErrorPath keys direct Teleport output to log files on disk. This is important because Teleport logs to stderr by default, and without these keys the log output would be inaccessible when the service runs in the background under launchd.

important

If the teleport binary path changes after reinstalling from an official distribution, update the ProgramArguments path in the plist and reload the service.

Step 3/4. Set required permissions​

LaunchDaemons must be owned by root:wheel with mode 644. Set the permissions and validate the plist:

sudo chown root:wheel /Library/LaunchDaemons/com.teleport.node.plist
sudo chmod 644 /Library/LaunchDaemons/com.teleport.node.plist
sudo plutil -lint /Library/LaunchDaemons/com.teleport.node.plist

Step 4/4. Load the service​

On macOS 12 (Monterey) and later, use bootstrap to load the service:

sudo launchctl bootstrap system /Library/LaunchDaemons/com.teleport.node.plist
sudo launchctl enable system/com.teleport.node
sudo launchctl kickstart -k system/com.teleport.node

macOS displays a “Background Items Added” notification when the LaunchDaemon is first registered. No action is required. You can manage this behavior at any time in System Settings -> General -> Login Items if you prefer to disable it at startup.

To reload after changes to the plist:

sudo launchctl bootout system /Library/LaunchDaemons/com.teleport.node.plist
sudo launchctl bootstrap system /Library/LaunchDaemons/com.teleport.node.plist

Checkpoint: Verify the service is running

Confirm that Teleport is running as a launchd service and the node is connected to the cluster.

Configure logging​

Teleport logs to stderr by default. The plist configuration above captures this output in /var/log/teleport.err.log via the StandardErrorPath key.

To consolidate all Teleport logs into a single file instead of relying on plist redirection, add the following to /etc/teleport.yaml:

teleport:
  log:
    output: /var/log/teleport.log
    severity: INFO

Restart the service after making changes:

sudo launchctl kickstart -k system/com.teleport.node
note

If you configure log.output in teleport.yaml, Teleport writes directly to that file. The plist StandardErrorPath file will still exist but will only capture output that bypasses Teleport's logger, such as early startup errors.

Troubleshooting​

Checkpoint: Service fails to load

Verify the launchd service is loading correctly.