Self-Hosted Mac Runner for CircleCI Pipelines

Recommendation: if your CircleCI macOS usage is above roughly 13 hours a month on m4pro.medium, move the iOS job to a self-hosted Figment M-series Mac from $95/month and route it there with a namespaced resource class. The break-even worksheet is at the bottom. Exact chip, RAM, and disk for the M-series plan are confirmed in the quote and physical units ship as capacity confirms, so request a configuration before you plan a hard cutover. Teams that want the runner installed, kept up, and backed up can start with the Managed Build Mac at $249/month, which includes CI setup, backups, monitoring, and 30 minutes of monthly support.

CircleCI bills cloud macOS jobs by the credit. For an active iOS team that cost compounds quickly. A self-hosted runner on a flat-rate Mac pays once a month and runs as many builds as the hardware can handle. This page sticks to one scenario: moving a single macos.m4pro.medium job to a Figment Mac runner and confirming the same build passes.

CircleCI Credit Pricing vs a Flat-Rate Mac

Per CircleCI's own changelog for the Free plan default change on November 10 and the current CircleCI pricing page, macos.m4pro.medium consumes 200 credits per minute. The standard credit rate CircleCI publishes elsewhere on that pricing page works out to $0.0006 per credit, so each minute of m4pro.medium costs about $0.12. Confirm the live rate on circleci.com/pricing before you commit; CircleCI changes resource-class pricing.

CircleCI's self-hosted runner overview states that runner compute itself does not consume credits; storage and networking associated with jobs can still accrue credits. Self-hosted runners are available on all plans, including Free, with concurrency caps per plan.

Hardware note. CircleCI advertises m4pro.medium as an M4 Pro class resource. Figment's M-series from $95/month is an entry M-series tier whose generation, RAM, and disk are set in the quote; it is not asserted to be equivalent hardware. The worksheet below is an entry-price comparison, not a performance claim.

Install Machine Runner 3 on the Figment Mac

Access the Figment Mac through its browser console and open Terminal. Follow CircleCI's machine runner 3 manual installation guide for the current steps; the Homebrew route is the recommended path on macOS:

# Tap and install the runner package
brew tap circleci-public/circleci
brew install circleci-runner

# Confirm Gatekeeper is happy with the signed binary
spctl -a -vvv -t install "$(brew --prefix)/bin/circleci-runner"

Only one machine runner is supported per macOS instance.

Create a Namespace and Resource Class

A resource class is how CircleCI routes a job to your runner. You need a namespace first (one per org). Use your CircleCI organization ID from the Organization Settings page:

# One-time: create a namespace for your org
circleci namespace create myorg --org-id "${CIRCLECI_ORG_ID:?Set your CircleCI organization ID}"

# Create a resource class and generate the runner token
circleci runner resource-class create \
  myorg/figment-mac \
  "Figment M-series Mac CI runner" \
  --generate-token

The token is printed once. Paste it into the runner config immediately; CircleCI will not show it again. Store a backup in your team secret manager by name reference only — do not dump the Mac's shell environment to a file, because that file will carry anything else you have exported.

Edit the config that Homebrew installed:

# Default config location for the Homebrew install
$EDITOR "$HOME/Library/Preferences/com.circleci.runner/config.yaml"

Minimum contents:

runner:
  name: figment-mac-01
  mode: continuous
  auth_token: "PASTE_GENERATED_TOKEN_HERE"
  idle_timeout: 10m
  max_run_time: 2h
  working_directory: /tmp/circleci-runner-workdir

Enable and start the Homebrew-provided service:

launchctl enable gui/$(id -u)/com.circleci.runner
launchctl kickstart -k gui/$(id -u)/com.circleci.runner

The runner should appear under Self-Hosted Runners in the CircleCI web app within a minute.

Swap Two Lines in config.yml

The only pipeline edit is the executor block and the resource class. Everything else — checkout, cache, xcodebuild — stays the same.

Before — cloud macOS executor:

jobs:
  build-ios:
    macos:
      xcode: "16.3.0"
    resource_class: macos.m4pro.medium
    steps:
      - checkout
      - run: pod install
      - run:
          name: Build and test
          command: |
            xcodebuild test \
              -workspace MyApp.xcworkspace \
              -scheme "$APP_SCHEME" \
              -destination 'platform=iOS Simulator,OS=latest,name=iPhone 16' \
              CODE_SIGN_STYLE=Manual

After — self-hosted Figment Mac runner:

jobs:
  build-ios:
    machine: true
    resource_class: myorg/figment-mac
    steps:
      - checkout
      - run: pod install
      - run:
          name: Build and test
          command: |
            xcodebuild test \
              -workspace MyApp.xcworkspace \
              -scheme "$APP_SCHEME" \
              -destination 'platform=iOS Simulator,OS=latest,name=iPhone 16' \
              CODE_SIGN_STYLE=Manual

Two changes: the macos: block becomes machine: true, and the resource class becomes your namespaced value. Set APP_SCHEME in the CircleCI project's environment to your real shared scheme — do not commit a scheme name you have not opened in Xcode, because xcodebuild will fail fast on a missing scheme and that failure is a configuration bug, not a benchmark.

Record the Xcode version actually installed on the Mac (xcodebuild -version) in the job's first step so a mismatch with the project's required version is obvious in the log. Intel Macs must stay on Xcode 26 or earlier — Apple documents the Intel ceiling in its porting-to-Apple-silicon notes. If you need ARM-only toolchains, visionOS, or iOS 27-era simulators that require Apple silicon, choose the M-series tier rather than the $29 virtual Intel macOS VM.

Signing, Secrets, and Allowlists Done Correctly

• Secrets. Keep API keys, App Store Connect keys, and match passphrases in CircleCI's project or context environment variables. On the Mac, do not persist them to shell rc files.
• Signing certificates. Export the signing identity from a developer machine as an encrypted .p12 (private key included), store it in CircleCI as a file-type context variable, and import it into a dedicated keychain on the runner at job start — do not check the .p12 into the repo.
• Provisioning profiles. These are files, not keychain entries. Drop them into ~/Library/MobileDevice/Provisioning Profiles/ on the runner or fetch them per build from your profile store.
• Allowlists. If your artifact store, internal API, or VPN restricts source IPs, add the Figment Mac's outbound IP (shown in the Figment console) to those allowlists that you control. There is no public, stable App Store Connect or TestFlight inbound IP list to add; outbound calls from the runner to Apple use HTTPS over normal egress.

Break-Even Worksheet

At $0.12 per minute for m4pro.medium, a Figment M-series Mac at $95/month breaks even at:

$95 ÷ $0.12/min = 791.67 minutes ≈ 13.19 hours per month

For the Managed Build Mac at $249/month, break-even is $249 ÷ $0.12 = 2,075 minutes ≈ 34.6 hours of monthly macOS build time. That plan includes one M-series Mac, CI setup, backups, monitoring, and 30 minutes of included monthly support. The Managed Mac Team at $999/month covers two M-series Macs, two CI runners, team setup, backups, monitoring, and one hour of included monthly support — useful when a second concurrent runner removes a queueing bottleneck in itself.

Numbers assume on-demand CircleCI credit pricing; annual CircleCI commitments and overage credit bundles can change the cloud side. Tax and fees are whatever your actual CircleCI invoice and Figment quote show.

Start a runner at /mac-hosting/start or review plan details on /mac-hosting.

Related guides

• Register a GitLab CI Runner on a Hosted Mac
• Xcode Cloud vs Self-Hosted Cost
• Xcode on Windows: Remote Mac Setup