macOS hosted agents

Sizes

Buildkite offers a selection of macOS instance types (each based on a different size combination of virtual CPU power and memory capacity, known as an instance shape), allowing you to tailor your hosted agents' resources to the demands of your jobs.

Note: Shapes MACOS_M2_4X7, MACOS_M2_6X14, MACOS_M2_12X28, MACOS_M4_12X56 were deprecated and removed on July 1, 2025.

Also note the following about macOS hosted agent instances.

• Only Apple silicon architectures are supported.

• To accommodate different workloads, instances are capable of running up to 4 hours.

If you have specific needs for longer running hosted agents (over 4 hours), please contact Support at support@buildkite.com.

Versioned queues

New Buildkite organizations are pre-provisioned with the following macOS hosted queues, in addition to macos-medium and macos-large:

Each of these queues uses the MACOS_ARM64_M4_6X28 (Medium) instance shape and pins its base image to the listed macOS version. This is different from queues without an explicit version, such as macos-medium, which use a default image. See the image explorer for the software included in each version. GitHub Actions-style macos-<version> runner labels map to these queues. Route a job to the macOS version it expects by targeting the matching queue in your pipeline.

New macOS hosted queues without an explicitly selected macOS or Xcode version default to macOS Tahoe (26.6) with Xcode 26.6. This includes queues you create and the macos-medium and macos-large queues created automatically for new Buildkite organizations. You can change this default at any time in the queue's Base image settings.

Concurrency

macOS hosted agents can operate concurrently when running your Buildkite pipeline jobs.

This concurrency is measured by the number of hosted agent machines that are allocated for your jobs at any given time. A machine is counted from the moment it starts booting to acquire a job, since that's when the machine starts consuming capacity. As a result, concurrency may not always match the exact number of running jobs, particularly with short-lived workloads.

The number of macOS hosted agents (of a Buildkite hosted queue) that can process your pipeline jobs concurrently is calculated by your Buildkite plan's maximum combined vCPU value divided by your instance shape's vCPU value. See the Buildkite pricing page for details on the Mac M4 Concurrency that applies to your plan.

For example, if your Buildkite plan provides you with a maximum combined vCPU value is up to 24, and you've configured a Buildkite hosted queue with the MACOS_ARM64_M4_6X28 (Medium) instance shape, whose vCPU value is 6, then the number of concurrent hosted agents that can run jobs on this queue is 4 (that is, 24 / 6 = 4).

When concurrency limits are exceeded, additional jobs will be queued until sufficient capacity becomes available.

macOS instance software support

Each macOS base image includes a set of Xcode versions, simulator runtimes (for iOS, tvOS, visionOS, and watchOS), and Homebrew packages. The software available varies by macOS version. For the current list of macOS base images and the software included in each one, see the Mac hosted agent image explorer. If you have specific requirements for software that is not included, please contact Buildkite Support at support@buildkite.com.

While you currently cannot provide custom base images for macOS hosted agents (as is possible using agent images for Linux hosted agents), you do have significant control over these virtual machines during job execution—including the ability to install software using Homebrew, use git mirroring for performance, and use persistent cache volumes.

Updated Xcode versions will be available one week after Apple offers them for download. This includes Beta, Release Candidate (RC), and official release versions.

Older Xcode versions are removed from base images over time. Some older Xcode versions are only available on earlier macOS point releases. They are incompatible with newer base images. Use the image explorer to find the macOS base image that includes the Xcode version you need.

If your queue has an Xcode version pinned that is no longer available, a warning is displayed on the queue list and queue settings pages: "Xcode {version} is no longer available for this macOS version. Your agents may fail to start until you update the base image of your queue." To resolve the warning, navigate to the queue's Base image settings and select an available Xcode version.

Docker support

macOS hosted agents include the Docker CLI (through the docker and docker-buildx Homebrew packages), but do not include a running Docker daemon. Commands that require a Docker daemon, such as docker build or docker run, fail with an error like Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running? unless the job connects to a Docker daemon that you provide.

To build Docker images, run these jobs on Linux hosted agents, which support Docker image builds (including remote Docker builders on the Enterprise plan), or on self-hosted agents, where you control the Docker installation.

Homebrew packages

Each macOS base image comes with a set of Homebrew packages pre-installed, such as git, jq, fastlane, cocoapods, and xcbeautify. The packages and their versions vary by macOS version. For the full list of packages and versions in each base image, see the Mac hosted agent image explorer.

Identifying Homebrew package versions

To find the Homebrew package version used by your macOS hosted agent:

1. Select Agents in the global navigation > your cluster containing the macOS Buildkite hosted agent queue > your macOS hosted agent.
2. On your macOS hosted agent's page, select Base image and scroll down to Specifications > Homebrew packages to view these packages, along with their respective versions.

Managing Homebrew package versions

Homebrew package versions are periodically updated when macOS hosted agent images are refreshed. If your builds require explicit, repeatable versions, pin the versions you need as part of your pipeline rather than relying on the image defaults.

Inspect currently installed packages

To view installed packages and their versions on the agent:

brew list --versions
brew info <formula>
brew info <formula>@<major>     # when the formula supports versioned installs

For example:

brew list --versions ruby ruby@3.4 rbenv
brew info ruby@3.4
ruby --version
bundler --version

Use a version manager for language runtimes

For languages that have version managers such as Ruby, pin the language version in your jobs using a version manager rather than relying on the image's installed runtime.

Example using Ruby with rbenv, including a cache for installed Ruby versions:

steps:
  - label: "Pin Ruby with rbenv"
    command: |
      eval "$(rbenv init -)"
      rbenv install 3.4.7 --skip-existing
      rbenv global 3.4.7
      ruby -v
      gem install bundler
      bundler -v
    cache:
      paths:
        - "~/.rbenv/versions"
      size: 20g
      name: "rbenv-versions"

Pin dependencies using a Brewfile

Commit a Brewfile to your repository and install from it during the build to make Homebrew dependencies explicit and reduce unexpected version changes.

Example Brewfile:

brew "wget"
brew "jq"
brew "rbenv"
brew "ruby@3.4"

Pipeline step:

steps:
  - label: "Install Homebrew dependencies"
    command: |
      brew update
      brew bundle --file Brewfile
      brew list --versions

When a versioned formula is available (for example, ruby@3.4 or python@3.12), use it to pin to a specific major version.

Pin an exact formula version

Homebrew does not support installing an arbitrary historical version of every formula. Options for stricter version control include:

• Using a versioned formula when available (for example, ruby@3.4 or python@3.12)
• Using a language or tool version manager (recommended for runtimes)
• Downloading an exact version from upstream release binaries with a pinned URL and checksum

Tracking image changes

Buildkite publishes RSS feeds of changes to hosted macOS images, covering updates to the macOS version, Xcode versions, runtimes, Homebrew packages, and other installed software. Follow these feeds in a feed reader to keep track of image changes without checking this page.

The stable feed covers the images used by standard macOS hosted queues. The canary feed covers images in the canary channel, which previews upcoming changes before they reach the stable images.

Each feed entry covers a single changed image and lists only what changed for that image, starting with the macOS version, followed by Xcode versions, runtimes, Homebrew packages, and other installed software.

Both feeds are public and don't require authentication.

Security

Customer security is paramount to Buildkite, where our source code, build artifacts and deployment processes represent some of our most valuable and sensitive assets.

The shift from a self-hosted to a Buildkite hosted architecture for Buildkite agents, introduces the potential for new attack vectors and shared responsibility models, and hence, additional security considerations.

The security model for Buildkite hosted agents has the following characteristics to address these security considerations and to mitigate attack risks.

• Infrastructure and isolation security: Buildkite employs a multi-tenant architecture, where each job runs in a completely isolated virtualized environment. Once a job is complete, regardless of its exit status, the virtualized environment is destroyed, along with all its data (except for cache volumes that persist across jobs). This ephemeral approach ensures that customer workloads remain isolated from each other, even though the underlying hardware is shared across multiple customers.

• Physical and operational security: The Buildkite hosted agent fleet operates from multiple Tier 3+ data centers with restricted physical access controls and regular security monitoring. The platform maintains SOC 2 compliance through regular audits of both hardware and software security controls.

Note that for macOS hosted agents, virtualization is achieved through Apple's Virtualization framework on Apple Silicon, providing lightweight but secure virtual machine isolation. Learn more about How Buildkite hosted agents work.