Installing Buildkite Agent on macOS
The Buildkite Agent is supported on macOS 10.12 or newer using Homebrew or our installer script, and supports pre-release versions of both macOS and Xcode.
On this page:
brew install buildkite/buildkite/buildkite-agent
Then configure your agent token:
sed -i '' "s/xxx/INSERT-YOUR-AGENT-TOKEN-HERE/g" "$(brew --prefix)"/etc/buildkite-agent/buildkite-agent.cfg
If you don't use Homebrew you should follow the Linux install instructions.
SSH Key Configuration
SSH keys should be copied to (or generated into) the
.ssh directory in the users’s home directory (i.e.
/Users/some-user/.ssh). For example, to generate a new private key which you can add to your source code host:
$ mkdir -p ~/.ssh && cd ~/.ssh $ ssh-keygen -t rsa -b 4096 -C "firstname.lastname@example.org"
See the Agent SSH Keys documentation for more details.
Homebrew install file locations:
- Agent Hooks:
Linux installer script file locations:
- Agent Hooks:
See the configuration documentation for an explanation of each configuration setting.
Starting on Login
If you installed the agent using Homebrew you can run the following command to get instructions on how to install the correct plist and have buildkite-agent start on login:
brew info buildkite-agent
If you installed the buildkite-agent using the Linux install script then you'll need to install the plist yourself using the following commands:
# Download the launchd config to ~/Library/LaunchAgents/ curl -o ~/Library/LaunchAgents/com.buildkite.buildkite-agent.plist https://raw.githubusercontent.com/buildkite/agent/main/templates/launchd_local_with_gui.plist # Set buildkite-agent to be run as the current user (a full user, created via System Prefs) sed -i '' "s/your-build-user/$(whoami)/g" ~/Library/LaunchAgents/com.buildkite.buildkite-agent.plist # Create the agent's log directory with the correct permissions mkdir -p ~/.buildkite-agent/log && sudo chmod 775 ~/.buildkite-agent/log # Start the agent launchctl load ~/Library/LaunchAgents/com.buildkite.buildkite-agent.plist # Check the logs tail -f ~/.buildkite-agent/log/buildkite-agent.log
launchctl fails with "Could not find domain for"
Ensure that you have a user logged in to the macOS host, then re-run:
launchctl load ~/Library/LaunchAgents/com.buildkite.buildkite-agent.plist
Running multiple agents
Launching and managing multiple agents can be done using
If you need the same configuration on each agent, configure a
launchd service to use the
--spawn flag on the
Using the existing agent
plist, add the spawn flag to the
ProgramArguments and change the number to how many agents you want to run.
The below example will start five agents each time the service is started:
<key>ProgramArguments</key> <array> <string>/Users/your-build-user/.buildkite-agent/bin/buildkite-agent</string> <string>start</string> <string>--spawn=5</string> </array>
If your agents each need different configuration, you can create multiple
Find your agent's
plist. If you installed the agent with Homebrew you can find the
plistin your user's
~/Library/LaunchAgentsdirectory. If you installed with the Linux script, you can take a copy of the template plist from the Agent's GitHub repository.
Make as many copies of the plist as you require, one per configuration, ensuring that each has a unique label.
Once you've edited your plist/s with your custom config, make sure that all the referenced paths exist and have the correct permissions. See the Starting on Login section above for an example of how to check directories and permissions.
If you installed the agent using Homebrew you can use the standard brew upgrade command to update the agent:
brew update && brew upgrade buildkite-agent
If you installed the buildkite-agent using the Linux install script then you should run the installer script again and it will update your agent.