Installing Buildkite Agent on macOS

This page references the out-of-date Buildkite Agent v2.

For docs referencing the Buildkite Agent v3, see the latest version of this document.

The Buildkite Agent can be installed on macOS 10.9 or higher using Homebrew or our installer script, and supports pre-release versions of both OS X and Xcode.

Installation

If you have Homebrew installed you can use our Buildkite formula repository to install the agent:

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' home directory (for example, /Users/alice/.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 "build@myorg.com"

See the Agent SSH keys documentation for more details.

File locations

Homebrew install file locations:

  • Configuration: /usr/local/etc/buildkite-agent/buildkite-agent.cfg
  • Agent Hooks: /usr/local/etc/buildkite-agent/hooks
  • Builds: /usr/local/var/buildkite-agent/builds
  • Log: /usr/local/var/log/buildkite-agent.log

Linux installer script file locations:

  • Configuration: ~/.buildkite-agent/buildkite-agent.cfg
  • Agent Hooks: ~/.buildkite-agent/hooks
  • Builds: ~/.buildkite-agent/builds

Configuration

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/LaunchDaemons/
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 using 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

Upgrading

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.