Installing the Agent on your own AWS EC2 Mac instances

Setting up a macOS AMI that starts a Buildkite Agent on launch is a multi step process. You can start with one of the macOS AMIs from AWS, or with an AMI you've already installed Xcode or other software on.

To use Xcode and the iOS Simulator, you must configure auto-login of a GUI session, and launch the Buildkite Agent in an aqua session as a Launchd Agent:

1. Reserve an EC2 Mac Dedicated Host.
2. Boot a macOS instance using your desired AMI on the Dedicated Host.
3. Configure instance VPC subnets, security groups, and key pairs so that you can access the instance.
4. Using an SSH or AWS SSM session:
   • Set a password for the ec2-user using sudo passwd ec2-user
   • Enable screen sharing using sudo /System/Library/CoreServices/RemoteManagement/ARDAgent.app/Contents/Resources/kickstart -activate -configure -access -on -restart -agent -privs -all
   • Grow the AFPS container to use all the available space in your EBS root disk if needed, see the AWS user guide
5. Using a VNC session (run SSH port forwarding ssh -L 5900:localhost:5900 ec2-user@<ip-address> if direct access is not available):
   1. Sign in as the ec2-user.
   2. Enable Automatic login for the ec2-user in System Preferences > Users & Accounts > Login Options.
   3. Disable Require password in System Preferences > Security & Privacy > General.
   4. Set system sleep in System Preferences > Energy Saver > Turn display off after to Never.
   5. Disable the screen saver in System Preferences > Desktop & Screen Saver > Show screen saver after.
6. Follow the macOS installation guide instructions to install the Buildkite agent using Homebrew and configure starting on login.
7. Verify that the Buildkite agent has connected to buildkite.com with your desired agent tags.
8. Create an AMI from your instance.

Your saved AMI can now be used to boot as many macOS instances as you require.

To make this process repeatable, save your instance configuration in a launch template. To automate instance replacement, use an Auto Scaling group to boot instances and a host resource group to reserve Dedicated Hosts.

While the use of an Auto Scaling group and host resource group to automatically maintain capacity in the face of hardware failures is recommended, load based dynamic auto-scaling of macOS instances is not recommended. The instances are currently slow to boot and slow to terminate. Use of load based auto-scaling is likely to result in an over-provision of agents which carries a high minimum charge per Dedicated Host.

There is an excellent blog post on running iOS agents in the cloud that goes into more detail on preparing macOS AMIs using Packer.