Machine runner installation on macOS
On This Page
- Download the macOS launch-agent script
- Create a CircleCI’s self-hosted runner configuration
- Update the Working Directory Permission
- Install the CircleCI’s self-hosted runner configuration
- Create and install the launchd .plist
- Machine runner configuration example
- Enable the launchd service
- Verify the service is running
- Troubleshooting
Self-hosted runner version 1.0 will sunset on July 27, 2023, and will be temporarily unavailable on June 28, 2023. Update to 1.1. |
This page describes how to install CircleCI’s machine runner on macOS.
This page is a continuation of installing self-hosted runners. You will need to have an existing CircleCI 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. |
Download the macOS launch-agent script
Save the launch-agent.sh script file to an easily accessible location. From that location, install the launch-agent
binary for your target platform, either x86_64, or M1 (Apple silicon):
# For macOS x86_64:
export platform=darwin/amd64 && sh ./download-launch-agent.sh
# For macOS M1:
export platform=darwin/arm64 && sh ./download-launch-agent.sh
After successful installation, the launch-agent.sh file can be deleted.
Create a CircleCI’s self-hosted runner configuration
You will need to 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
-
Replace
AUTH_TOKEN
with the resource class token created in the set up process. -
Replace
RUNNER_NAME
with the name you would like for your self-hosted runner.RUNNER_NAME
is unique to the machine that is installing the runner.RUNNER_NAME
can be any value you would like, and it does not need to include any part of your namespace or resource class name. However, it is recommended to use the hostname of the machine so that it can be used to identify the agent when viewing statuses and job results in the CircleCI web app. The only special characters accepted in RUNNER_NAME are. () - _
.
Update the Working Directory Permission
The CircleCI agent requires write permission to the directory containing the working directory. Change the ownership of that directory to USERNAME
:
sudo chown USERNAME /var/opt/circleci
Install the CircleCI’s self-hosted runner configuration
Create a directory as root
to hold the CircleCI’s 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 with a path of /Library/LaunchDaemons/com.circleci.runner.plist
, owned by root
, with permissions 644
. Use the following commands:
sudo touch /Library/LaunchDaemons/com.circleci.runner.plist
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>
Machine runner configuration example
The fields you must set for a specific job to run using your self-hosted runners are:
-
machine: true
-
resource_class: <namespace>/<resource-class>
Simple example of how you could set up a job:
version: 2.1
workflows:
build-workflow:
jobs:
- runner
jobs:
runner:
machine: true
resource_class: <namespace>/<resource-class>
steps:
- run: echo "Hi I'm on Runners!"
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'
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.
Troubleshooting
Refer to the Troubleshoot Machine Runner section of the Troubleshoot Self-hosted Runner guide if you encounter issues installing or running machine runner on macOS.
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.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
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.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.