Skip to content
Docs
Cancel

CircleCI Self-hosted Runner Installation on macOS

Last updated
Tags Cloud Server v3.x

This page describes how to install CircleCI self-hosted runner on macOS.

This page is a continuation of installing self-hosted runners. You will need to have an existing namespace and resource class to continue below. You can do this on the CircleCI web app by navigating to Self-Hosted Runners (see the documentation for the Web App Installation). You can also use the CLI.

Create a CircleCI self-hosted runner configuration

Choose a user to run the CircleCI agent. These instructions refer to the selected user as USERNAME. The USERNAME refers to the user on the machine that the agent will be installed on, not the CircleCI account username.

Complete the template shown below, with the various capitalized parameters filled in. When complete, save the template as launch-agent-config.yaml.

api:
  auth_token: AUTH_TOKEN
  # On server, set url to the hostname of your server installation. For example,
  # url: https://circleci.example.com

runner:
  name: RUNNER_NAME
  command_prefix : ["sudo", "-niHu", "USERNAME", "--"]
  working_directory: /var/opt/circleci/workdir
  cleanup_working_directory: true

logging:
  file: /Library/Logs/com.circleci.runner.log

Install the CircleCI self-hosted runner configuration

Create a directory as root to hold the CircleCI self-hosted runner configuration:

sudo mkdir -p '/Library/Preferences/com.circleci.runner'

Copy the previously created launch-agent-config.yaml into the directory and change its permissions to 600:

sudo cp "launch-agent-config.yaml" "/Library/Preferences/com.circleci.runner/launch-agent-config.yaml"
sudo chmod 600 "/Library/Preferences/com.circleci.runner/launch-agent-config.yaml"

Create and install the launchd .plist

Create a com.circleci.runner.plist file. Please note that if you choose to create the file with Vim, you will likely need to prefix sudo to the command. The path to the file should be the following: /Library/LaunchDaemons/com.circleci.runner.plist, owned by root, with permissions 644.

sudo chown root: /Library/LaunchDaemons/com.circleci.runner.plist
sudo chmod 644 /Library/LaunchDaemons/com.circleci.runner.plist

Copy the following to the new /Library/LaunchDaemons/com.circleci.runner.plist file:

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

        <key>Program</key>
        <string>/opt/circleci/circleci-launch-agent</string>

        <key>ProgramArguments</key>
        <array>
            <string>circleci-launch-agent</string>
            <string>--config</string>
            <string>/Library/Preferences/com.circleci.runner/launch-agent-config.yaml</string>
        </array>

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

        <!-- The agent needs to run at all times -->
        <key>KeepAlive</key>
        <true/>

        <!-- This prevents macOS from limiting the resource usage of the agent -->
        <key>ProcessType</key>
        <string>Interactive</string>

        <!-- Increase the frequency of restarting the agent on failure, or post-update -->
        <key>ThrottleInterval</key>
        <integer>3</integer>

        <!-- Wait for 10 minutes for the agent to shut down (the agent itself waits for tasks to complete) -->
        <key>ExitTimeOut</key>
        <integer>600</integer>

        <!-- The agent uses its own logging and rotation to file -->
        <key>StandardOutPath</key>
        <string>/dev/null</string>
        <key>StandardErrorPath</key>
        <string>/dev/null</string>
    </dict>
</plist>

Enable the launchd service

Now you can load the service:

sudo launchctl load '/Library/LaunchDaemons/com.circleci.runner.plist'
If you are following these instructions for a second time, use the command below to unload the existing service. Once the existing service is unloaded, you can load the new service with the command above. 
sudo launchctl unload '/Library/LaunchDaemons/com.circleci.runner.plist'

Referencing your self-hosted runner on a job

After setting up your self-hosted runner, you will need to reference it on a job by setting some fields in your .circleci/config.yml file. The fields you must set for a specific job to run using your self-hosted runners are:

  • machine: true

  • resource_class: your-namespace/your-resource

Here is a simple example of how you could set up a job:

version: 2.1
workflows:
  testing:
    jobs:
      - runner
jobs:
  runner:
    machine: true
    resource_class: your-namespace/your-resource
    steps:
      - run: echo "Hi I'm on Runners!"

The job will then execute using your self-hosted runner when you push the config to your VCS provider.

Verify the service is running

Open the pre-installed macOS application Console. In this application, you can view the logs for the CircleCI agent under Log Reports. Look for the logs called com.circleci.runner.log in the list. You can also find this file by navigating to Library > Logs.


Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.

Creative Commons License
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

6,000 Minutes Free

CircleCI, now with more build minutes
than anyone else for FREE 🎉

Sign up for Free

These teams get it

CCI customer teams