Skip to content

How to Set Up a CircleCI Self-Hosted Runner on Mac Mini M4

Complete step-by-step guide to installing and configuring a CircleCI self-hosted machine runner on a dedicated Mac mini M4. Native Apple Silicon performance, persistent caching, and up to 90% cheaper than CircleCI cloud macOS resources.

CI/CD 35 min read Updated October 2026

Why Use a Self-Hosted CircleCI Runner on Mac?

CircleCI offers cloud-based macOS execution environments, but they come with significant costs and limitations. CircleCI bills macOS jobs in credits: the m4pro.medium resource class uses 200 credits per minute (about $0.12) and m4pro.large uses 400 (about $0.24), as of October 2026. For teams running frequent iOS builds, this can quickly add up to $300-$500 per month or more.

A self-hosted runner on a dedicated Mac Mini M4 from MyRemoteMac eliminates per-minute billing entirely. You get a dedicated Apple Silicon machine with persistent storage, warm caches, and full root access for a flat monthly fee starting at $85/month. Here is a detailed comparison:

Why Use a Self-Hosted CircleCI Runner on Mac?
MyRemoteMac Self-Hosted CircleCI Cloud macOS
Cost Model $85/mo flat (unlimited minutes) 200 credits/min on m4pro.medium (~$0.12/min)
Architecture Physical Apple M4 Mac, allocated 1:1 M4 Pro virtual machine (6 vCPU, 28 GB)
Build Speed ~5 min (same project) ~14 min (medium iOS project)
Cache Persistence Persistent on disk (instant) Ephemeral (must restore each job)
Queue Wait Time 0s (dedicated hardware) 30s - 5min (varies by plan)
Privacy / Data Control Dedicated machine, full control Shared infrastructure
Custom Software Full root access, any software Pre-installed image only

My Remote Mac prices in USD, excluding tax.

Key Benefit: With a persistent self-hosted runner, DerivedData, Swift Package Manager caches, and CocoaPods are preserved between builds. This alone can cut build times by 50-70% compared to CircleCI's ephemeral cloud macOS environments that start from scratch every time. Combined with the M4 chip's superior single-threaded performance, your iOS builds will be dramatically faster.

Prerequisites

Before you begin, make sure you have the following:

  • A dedicated Mac mini M4 build server from My Remote Mac (from $85/mo, USD, excl. tax)
  • A CircleCI organization where you are an admin (self-hosted runners are available on every plan, including Free, which allows 5 concurrent self-hosted tasks as of October 2026)
  • SSH access to your Mac Mini (provided with your MyRemoteMac subscription)
  • An Apple Developer account (for code signing and provisioning profiles)
  • Basic familiarity with YAML, CircleCI configuration, and terminal commands

Step 1: Check Xcode and Install Dependencies

First, connect to your Mac Mini M4 via SSH with the credentials you received when you set up your MyRemoteMac server. Xcode, its Command Line Tools and Homebrew are already installed, so you only add the build tools your iOS pipeline needs before setting up the CircleCI runner.

Connect via SSH

# Connect to your Mac mini M4
ssh admin@your-server-ip

# Verify you're on Apple Silicon
uname -m
# Expected output: arm64

# Show the macOS version
sw_vers

Check Homebrew and the Xcode Command Line Tools

# Homebrew comes preinstalled: put it on your PATH for your zsh sessions
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
brew --version

# Add Homebrew to PATH for CircleCI job steps
# (CircleCI runs macOS steps in a bash login shell)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.bash_profile

# Xcode and its Command Line Tools come preinstalled
xcode-select -p
# /Applications/Xcode.app/Contents/Developer

# Accept the Xcode license if it asks
sudo xcodebuild -license accept

Check Xcode and Add Other Versions

For iOS builds, you need the full Xcode application. Since April 28, 2026, App Store Connect only accepts builds made with Xcode 26 or later, and the Xcode preinstalled on your server meets that rule. Install another release side by side with xcodes only if your project needs it:

# Check the preinstalled Xcode
xcodebuild -version
# Xcode 27.2

# Optional: add other Xcode releases side by side with the xcodes CLI
brew install xcodes
xcodes list

# Install an older release next to the preinstalled one (asks for your Apple Account)
xcodes install 26.6

# Show the installed versions and their paths
xcodes installed
# e.g. /Applications/Xcode.app and /Applications/Xcode-26.6.0.app

# Set the default Xcode (sudo asks for your password)
# preinstalled Xcode; for another version, use the path from xcodes installed
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

Install iOS Simulators and Build Tools

# Install the current iOS simulator runtime
xcodebuild -downloadPlatform iOS

# Verify simulator availability
xcrun simctl list runtimes

# Install additional build tools
brew install xcbeautify fastlane swiftlint

Step 2: Install the CircleCI Runner Agent

CircleCI's machine runner 3 connects your Mac mini to CircleCI: it receives jobs and runs them directly on your macOS host. On macOS, CircleCI recommends installing it with its Homebrew package. This is different from the container runner (which only works on Linux).

Choose the User That Runs Your Jobs

Machine runner 3 runs every job as the macOS user that starts it, with that user's Homebrew, keychain and Xcode. Install and start it as your admin user, the one that owns Homebrew, not as root: Homebrew refuses to run as root.

# Run the steps below as the user that will run CI jobs, not with sudo
whoami

# Homebrew must work for this user (prints /opt/homebrew)
brew --prefix

Install Machine Runner 3 with Homebrew

# Add CircleCI's Homebrew tap and install machine runner 3
brew tap circleci-public/circleci
brew install circleci-runner

# Check that macOS accepts the binary notarized by CircleCI
spctl -a -vvv -t install "$(brew --prefix)/bin/circleci-runner"
# Expected: accepted, source=Notarized Developer ID,
# origin=Developer ID Application: Circle Internet Services Inc.

# Remove the quarantine attribute (asks for your macOS password)
sudo xattr -r -d com.apple.quarantine "$(brew --prefix)/bin/circleci-runner"

Configure the Runner Agent

The Homebrew package creates the configuration file. You will need your runner authentication token from the CircleCI web app (covered in Step 3). For now, set the runner name and keep a placeholder for the token:

# Open the configuration file created by the Homebrew package
nano "$HOME/Library/Preferences/com.circleci.runner/config.yaml"

# Contents (the token comes in Step 3):
runner:
  name: "mac-mini-m4-runner"
  working_directory: "/Users/$USER/Library/com.circleci.runner/workdir"
  cleanup_working_directory: true
api:
  auth_token: "YOUR_RUNNER_TOKEN_HERE"

# The file will hold a secret: make it readable by you only
chmod 600 "$HOME/Library/Preferences/com.circleci.runner/config.yaml"

Prepare the launchd Service for a Headless Mac

The Homebrew package also installs a launchd agent, com.circleci.runner. An agent normally starts when your user logs in; on a Mac you reach only over SSH, CircleCI's headless setup moves it to /Library/LaunchAgents so it loads after a reboot. Start it in Step 3, once the token is in place:

# The launchd agent installed by the Homebrew package
ls ~/Library/LaunchAgents/com.circleci.runner.plist

# Headless Mac reached over SSH only: move it to the per-user agents
# folder so it loads after a reboot (CircleCI's headless setup)
sudo mv ~/Library/LaunchAgents/com.circleci.runner.plist /Library/LaunchAgents/

Important: The runner will not connect until config.yaml holds a valid authentication token. Generate it in Step 3, add it to the file, then start the service.

Step 3: Configure the Runner in CircleCI Dashboard

Now you need to register your runner in the CircleCI web interface and generate an authentication token. This connects your Mac Mini to your CircleCI organization.

Create a Resource Class

In CircleCI, self-hosted runners are organized by resource classes. A resource class is a label that maps your .circleci/config.yml to a specific set of runners.

  1. In the CircleCI web app, open Runners in the sidebar (you must be an organization admin)
  2. Click "Create Resource Class"
  3. Set the Namespace to your organization name (e.g., your-org)
  4. Set the Resource Class name to something descriptive (e.g., mac-runner)
  5. This creates a resource class identifier: your-org/mac-runner

Generate a Runner Authentication Token

  1. Click "Save and continue": CircleCI creates the resource class and shows its authentication token
  2. Copy the token immediately and store it safely: it is only displayed once
  3. Lost it? Create a new one with the CircleCI CLI: circleci runner token create your-org/mac-runner mac-mini-m4

Add Your Token and Start the Runner

# SSH back into your Mac mini
ssh admin@your-server-ip

# Replace YOUR_RUNNER_TOKEN_HERE with the resource class token
nano "$HOME/Library/Preferences/com.circleci.runner/config.yaml"

# Start the service. Headless Mac (plist moved to /Library/LaunchAgents):
launchctl bootstrap user/$(id -u) /Library/LaunchAgents/com.circleci.runner.plist
launchctl enable user/$(id -u)/com.circleci.runner
launchctl kickstart -k user/$(id -u)/com.circleci.runner

# Or, from a desktop session (VNC), with the plist left in ~/Library/LaunchAgents:
# launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.circleci.runner.plist
# launchctl enable gui/$(id -u)/com.circleci.runner
# launchctl kickstart -k gui/$(id -u)/com.circleci.runner

# Verify the service, then read the runner log
launchctl print user/$(id -u)/com.circleci.runner
tail -20 "$HOME/Library/Logs/com.circleci.runner/runner.log"

Once connected, the runner is listed under Runners in the CircleCI web app, and circleci runner instance list your-org/mac-runner shows it too. If it does not appear within 60 seconds, check the log file for error messages.

Using the CircleCI CLI (Alternative)

You can also manage runners via the CircleCI CLI:

# Install the CircleCI CLI
brew install circleci

# Authenticate with CircleCI
circleci setup

# Create the namespace (once per organization)
circleci namespace create your-org --org-id YOUR_ORGANIZATION_ID

# Create the resource class and print its token
circleci runner resource-class create your-org/mac-runner \
  "Mac mini M4 runner" --generate-token

# List the runners connected to this resource class
circleci runner instance list your-org/mac-runner

Step 4: Create Your .circleci/config.yml for iOS Builds

Create a .circleci/config.yml file in the root of your repository. The key difference from a standard CircleCI config is using machine: true with your custom resource_class to target your self-hosted runner.

version: 2.1

jobs:
  build-and-test:
    machine: true
    resource_class: your-org/mac-runner

    environment:
      # Xcode for this job, without sudo
      # (preinstalled Xcode; for another version, use the path from `xcodes installed`)
      DEVELOPER_DIR: "/Applications/Xcode.app/Contents/Developer"
      SCHEME: "MyApp"
      # Any device listed by: xcrun simctl list devices available
      DESTINATION: "platform=iOS Simulator,name=iPhone 17,OS=latest"

    steps:
      - checkout

      - run:
          name: Show the Xcode version
          command: xcodebuild -version

      # Caches live in $HOME, outside the job's working directory,
      # so they survive cleanup_working_directory between jobs
      - run:
          name: Resolve Swift Package Dependencies
          command: |
            xcodebuild -resolvePackageDependencies \
              -scheme "$SCHEME" \
              -clonedSourcePackagesDirPath "$HOME/spm-cache"

      - run:
          name: Build the app
          command: |
            xcodebuild build \
              -scheme "$SCHEME" \
              -destination "generic/platform=iOS Simulator" \
              -clonedSourcePackagesDirPath "$HOME/spm-cache" \
              -derivedDataPath "$HOME/DerivedData/$SCHEME" \
              | xcbeautify

      # store_test_results needs JUnit XML: xcbeautify writes test-results/junit.xml
      - run:
          name: Run unit tests
          command: |
            xcodebuild test \
              -scheme "$SCHEME" \
              -destination "$DESTINATION" \
              -clonedSourcePackagesDirPath "$HOME/spm-cache" \
              -derivedDataPath "$HOME/DerivedData/$SCHEME" \
              -resultBundlePath TestResults.xcresult \
              | xcbeautify --report junit --report-path test-results

      - store_test_results:
          path: test-results

      - store_artifacts:
          path: TestResults.xcresult
          destination: test-results

workflows:
  ios-pipeline:
    jobs:
      - build-and-test:
          filters:
            branches:
              only:
                - main
                - develop

Note: The resource_class: your-org/mac-runner value must exactly match the resource class you created in the CircleCI dashboard. If it does not match, jobs will remain queued indefinitely.

Step 5: Optimize with Caching and Parallelism

One of the biggest advantages of a self-hosted runner is persistent caching. Because the runner's filesystem is persistent, you do not need to upload and download caches like you do with CircleCI cloud resources. However, there are additional optimizations to maximize your build speed.

Leverage Persistent DerivedData

Since the runner disk persists between builds, DerivedData is already cached automatically. Use a consistent path:

# In your config.yml steps, always use a consistent DerivedData path:
- run:
    name: Build with persistent cache
    command: |
      xcodebuild build \
        -scheme "$SCHEME" \
        -destination "$DESTINATION" \
        -derivedDataPath ~/DerivedData/"$SCHEME" \
        -clonedSourcePackagesDirPath ~/spm-cache \
        | xcbeautify

# Periodically clean old DerivedData on the runner (cron job):
# 0 3 * * 0 find ~/DerivedData -mindepth 1 -maxdepth 1 -mtime +7 -exec rm -rf {} +

Workspace Persistence Between Jobs

Use CircleCI workspaces to pass the built products to a test job, which may run on another Mac of the same resource class:

jobs:
  build:
    machine: true
    resource_class: your-org/mac-runner
    steps:
      - checkout
      - run:
          name: Build for testing
          command: |
            xcodebuild build-for-testing \
              -scheme "MyApp" \
              -destination "generic/platform=iOS Simulator" \
              -derivedDataPath DerivedData \
              | xcbeautify
      # Pass only the built products, not the whole DerivedData
      - persist_to_workspace:
          root: .
          paths:
            - DerivedData/Build/Products

  test:
    machine: true
    resource_class: your-org/mac-runner
    steps:
      - attach_workspace:
          at: .
      - run:
          name: Run the tests built by the previous job
          command: |
            xcodebuild test-without-building \
              -xctestrun "$(ls DerivedData/Build/Products/*.xctestrun | head -n 1)" \
              -destination "platform=iOS Simulator,name=iPhone 17,OS=latest" \
              | xcbeautify --report junit --report-path test-results
      - store_test_results:
          path: test-results

workflows:
  build-test:
    jobs:
      - build
      - test:
          requires:
            - build

Parallel Test Execution

- run:
    name: Run tests in parallel
    command: |
      # Xcode clones the simulator and runs test classes on up to 4 clones
      xcodebuild test \
        -scheme "MyApp" \
        -destination "platform=iOS Simulator,name=iPhone 17,OS=latest" \
        -parallel-testing-enabled YES \
        -maximum-parallel-testing-workers 4 \
        -derivedDataPath ~/DerivedData/MyApp \
        | xcbeautify

CircleCI Test Splitting

For large test suites, CircleCI's test splitting spreads test classes across parallel tasks. Each task needs its own runner, so parallelism: 3 needs three Macs in the resource class; on a single Mac, the tasks run one after another:

jobs:
  test:
    machine: true
    resource_class: your-org/mac-runner
    # One task per runner: 3 tasks need 3 Macs in this resource class
    parallelism: 3
    steps:
      - checkout
      - run:
          name: Split test classes and run this task's share
          command: |
            # One XCTest class per file, named like the file (LoginTests.swift)
            CLASSES=$(circleci tests glob "MyAppTests/**/*Tests.swift" \
              | xargs -n1 basename | sed 's/\.swift$//' \
              | circleci tests split)

            # -only-testing takes Target/Class identifiers, not file paths
            ONLY_TESTING=""
            for CLASS in $CLASSES; do
              ONLY_TESTING="$ONLY_TESTING -only-testing:MyAppTests/$CLASS"
            done

            xcodebuild test \
              -scheme "MyApp" \
              -destination "platform=iOS Simulator,name=iPhone 17,OS=latest" \
              $ONLY_TESTING \
              | xcbeautify --report junit --report-path test-results
      - store_test_results:
          path: test-results

Workflow Examples

Here are complete, production-ready workflow examples for common iOS CI/CD scenarios.

Full iOS Build, Test, and Deploy Pipeline

version: 2.1

jobs:
  lint:
    machine: true
    resource_class: your-org/mac-runner
    steps:
      - checkout
      - run:
          name: Run SwiftLint
          command: swiftlint lint --reporter json > swiftlint-results.json || true
      - store_artifacts:
          path: swiftlint-results.json

  build-and-test:
    machine: true
    resource_class: your-org/mac-runner
    environment:
      # Xcode for this job, without sudo
      # (preinstalled Xcode; for another version, use the path from `xcodes installed`)
      DEVELOPER_DIR: "/Applications/Xcode.app/Contents/Developer"
    steps:
      - checkout
      - run:
          name: Resolve dependencies
          command: |
            xcodebuild -resolvePackageDependencies \
              -scheme "MyApp" \
              -clonedSourcePackagesDirPath ~/spm-cache
      - run:
          name: Build and test
          command: |
            xcodebuild test \
              -scheme "MyApp" \
              -destination "platform=iOS Simulator,name=iPhone 17,OS=latest" \
              -clonedSourcePackagesDirPath ~/spm-cache \
              -derivedDataPath ~/DerivedData/MyApp \
              -resultBundlePath TestResults.xcresult \
              -parallel-testing-enabled YES \
              | xcbeautify --report junit --report-path test-results
      - store_test_results:
          path: test-results
      - store_artifacts:
          path: TestResults.xcresult

  deploy-testflight:
    machine: true
    resource_class: your-org/mac-runner
    environment:
      DEVELOPER_DIR: "/Applications/Xcode.app/Contents/Developer"
    steps:
      - checkout
      - run:
          name: Install dependencies
          command: bundle install
      # MATCH_PASSWORD and the App Store Connect API key variables
      # (ASC_KEY_ID, ASC_ISSUER_ID, ASC_KEY_CONTENT) come from a CircleCI
      # context or the project's environment variables
      - run:
          name: Build and upload to TestFlight
          command: bundle exec fastlane beta

workflows:
  ios-pipeline:
    jobs:
      - lint
      - build-and-test:
          requires:
            - lint
      - deploy-testflight:
          requires:
            - build-and-test
          filters:
            branches:
              only: main

Fastlane Integration Example

If you use Fastlane for your build automation, here is how to integrate it with your CircleCI self-hosted runner:

# Fastfile (fastlane/Fastfile)
default_platform(:ios)

platform :ios do
  desc "Run tests"
  lane :test do
    scan(
      scheme: "MyApp",
      device: "iPhone 17",
      derived_data_path: File.expand_path("~/DerivedData/MyApp"),
      result_bundle: true,
      output_directory: "./test_output",
      # store_test_results reads JUnit XML
      output_types: "junit",
      output_files: "junit.xml"
    )
  end

  desc "Build and push to TestFlight"
  lane :beta do
    # App Store Connect API key: no Apple ID password or 2FA on the runner
    app_store_connect_api_key(
      key_id: ENV["ASC_KEY_ID"],
      issuer_id: ENV["ASC_ISSUER_ID"],
      key_content: ENV["ASC_KEY_CONTENT"]
    )
    match(type: "appstore", readonly: true)
    increment_build_number(
      build_number: ENV["CIRCLE_BUILD_NUM"]
    )
    gym(
      scheme: "MyApp",
      export_method: "app-store",
      derived_data_path: File.expand_path("~/DerivedData/MyApp")
    )
    pilot(skip_waiting_for_build_processing: true)
  end
end
# .circleci/config.yml using Fastlane
version: 2.1

jobs:
  fastlane-test:
    machine: true
    resource_class: your-org/mac-runner
    steps:
      - checkout
      - run:
          name: Install dependencies
          command: bundle install
      - run:
          name: Run Fastlane tests
          command: bundle exec fastlane test
      - store_test_results:
          path: ./test_output
      - store_artifacts:
          path: ./test_output

  fastlane-deploy:
    machine: true
    resource_class: your-org/mac-runner
    steps:
      - checkout
      - run:
          name: Install dependencies
          command: bundle install
      - run:
          name: Deploy to TestFlight
          command: bundle exec fastlane beta

workflows:
  ios-workflow:
    jobs:
      - fastlane-test
      - fastlane-deploy:
          requires:
            - fastlane-test
          filters:
            branches:
              only: main

Performance Comparison

Here is a detailed performance and cost comparison between CircleCI cloud macOS resources and a self-hosted Mac Mini M4 from MyRemoteMac:

Build Time Benchmarks

Build Time Benchmarks
Self-Hosted Mac Mini M4 CircleCI Cloud macOS Improvement
Clean build (medium app) 5 min 14 min 2.8x faster
Incremental build 1.5 min 14 min (no cache) 9.3x faster
SPM dependency resolution 5 sec (cached on disk) 3-5 min (download each time) ~60x faster
Unit test suite (500 tests) 2.5 min 8 min 3.2x faster
Queue wait time 0 sec 30s - 5 min Instant

Monthly Cost Analysis

Monthly Cost Analysis
Team Size MyRemoteMac Cost Builds/Month CircleCI Cloud Cost Monthly Savings
Solo Dev $85/mo 100 builds (10 min avg) $120/mo $35/mo
Small Team (5) $85/mo 500 builds (10 min avg) $600/mo $515/mo
Medium Team (15) $229/mo (M4 Pro) 1500 builds (10 min avg) $1,800/mo $1,571/mo
Enterprise (50+) $458/mo (2x M4 Pro) 5000+ builds $6,000+/mo $5,542+/mo

My Remote Mac prices in USD, excluding tax.

Bottom Line: At CircleCI's rate for the m4pro.medium class (200 credits, about $0.12 per minute, as of October 2026), a 10-minute build costs about $1.20, so a dedicated Mac mini M4 at $85/mo (USD, excl. tax) costs less from about 71 builds a month. Warm caches on a persistent Mac also cut the time your team waits for each build.

Troubleshooting Common Issues

Runner disconnects or shows as "Offline"

The runner can lose its connection after a network issue, a crash or a reboot. Started in the gui domain, it only comes back when its user logs in; the headless setup from Step 2 avoids that. Check the service and its log:

# Check the service (use gui/ instead of user/ if you started it
# from a desktop session)
launchctl print user/$(id -u)/com.circleci.runner

# View the runner log
tail -50 "$HOME/Library/Logs/com.circleci.runner/runner.log"

# Restart the service
launchctl kickstart -k user/$(id -u)/com.circleci.runner

# If the token was revoked, create a new one, put it in
# ~/Library/Preferences/com.circleci.runner/config.yaml and restart
circleci runner token create your-org/mac-runner mac-mini-m4

resource_class not found or jobs stuck in queue

If jobs stay queued with "No matching runner found", the resource class in your config does not match the dashboard:

# Verify the exact resource class name in the CircleCI web app:
# Runners (sidebar) lists your resource classes

# The resource_class in .circleci/config.yml must match exactly:
# resource_class: your-org/mac-runner  (case-sensitive!)

# Check your runner is online:
circleci runner instance list your-org/mac-runner

# Common mistakes:
# - Wrong namespace (org name vs personal namespace)
# - Typo in resource class name
# - Runner is offline or token is invalid
# - Using 'docker' executor instead of 'machine: true'

Xcode code signing errors

Code signing on a CI machine requires careful keychain management. The runner process may not have access to the login keychain:

# Option 1: Use Fastlane Match (recommended)
# In your Fastfile:
match(type: "appstore", readonly: true)

# Option 2: Manual keychain management in your job steps
- run:
    name: Setup code signing
    command: |
      # Decode and import the certificate
      echo "$BUILD_CERTIFICATE_BASE64" | base64 --decode > /tmp/cert.p12

      # Create a temporary keychain
      security create-keychain -p "ci" /tmp/ci.keychain
      security set-keychain-settings -lut 21600 /tmp/ci.keychain
      security unlock-keychain -p "ci" /tmp/ci.keychain

      # Import the certificate
      security import /tmp/cert.p12 -P "$P12_PASSWORD" \
        -A -t cert -f pkcs12 -k /tmp/ci.keychain
      # Let codesign use the key without a GUI prompt
      security set-key-partition-list -S apple-tool:,apple:,codesign: \
        -s -k "ci" /tmp/ci.keychain
      security list-keychain -d user -s /tmp/ci.keychain

      # Install the provisioning profile (Xcode 16 and later location)
      PROFILES=~/Library/Developer/Xcode/UserData/Provisioning\ Profiles
      mkdir -p "$PROFILES"
      echo "$PROVISIONING_PROFILE_BASE64" | base64 --decode \
        > "$PROFILES/profile.mobileprovision"

Simulator fails to boot or times out

Simulators can get into a bad state on long-running CI machines. Reset them between builds:

# Add a pre-build step to clean simulators
- run:
    name: Reset simulators
    command: |
      xcrun simctl shutdown all 2>/dev/null || true
      xcrun simctl erase all 2>/dev/null || true

# If a specific runtime is missing, reinstall it:
xcodebuild -downloadPlatform iOS

# List available simulators
xcrun simctl list devices available

Disk space running low

Xcode builds generate significant amounts of data. Set up automatic cleanup on your runner:

# Check available disk space
df -h /

# Clean DerivedData folders unused for a week
find ~/DerivedData ~/Library/Developer/Xcode/DerivedData \
  -mindepth 1 -maxdepth 1 -mtime +7 -exec rm -rf {} +

# Delete simulators the current Xcode no longer supports
xcrun simctl delete unavailable

# List simulator runtimes, then delete the ones you no longer test on
xcrun simctl runtime list
# xcrun simctl runtime delete <runtime-identifier>

# Clean Homebrew cache
brew cleanup --prune=7

# Set up a weekly cron job for automatic cleanup
(crontab -l 2>/dev/null; echo "0 4 * * 0 find ~/DerivedData -mindepth 1 -maxdepth 1 -mtime +7 -exec rm -rf {} + ; /opt/homebrew/bin/brew cleanup --prune=7") | crontab -

Frequently Asked Questions

How much does a CircleCI self-hosted runner on Mac Mini M4 cost?
A dedicated Mac mini M4 from My Remote Mac starts at $85/month (USD, excl. tax) with unlimited build minutes, and CircleCI does not charge per build minute on self-hosted runners. CircleCI's cloud macOS jobs cost about $0.12 per minute on the m4pro.medium class (200 credits at $0.0006 each, as of October 2026), roughly $300-500/month for active teams. With your own runner, costs stay predictable regardless of build volume.
Can I use a CircleCI self-hosted runner for iOS and macOS builds?
Yes. A self-hosted runner on a Mac Mini M4 can run any macOS workload including iOS builds, macOS app builds, Swift package testing, Xcode UI tests, and Fastlane automation. Since it runs natively on Apple Silicon, builds are faster than on emulated or Intel-based cloud runners.
What is the difference between CircleCI machine runner and container runner?
CircleCI machine runner executes jobs directly on the host machine's operating system, which is required for macOS/iOS builds that need Xcode, simulators, and Apple frameworks. Container runner executes jobs inside Docker containers and is only available on Linux. For Mac builds, you must use the machine runner.
How do I keep my CircleCI self-hosted runner updated?
Machine runner 3 does not update itself: with the Homebrew package, you choose when to update by running brew upgrade circleci-runner, then restart the service. Check the runner changelog monthly and keep Xcode and macOS updated as well.
Is a self-hosted runner faster than CircleCI cloud macOS?
Yes, typically 2-3x faster for clean builds and up to 9x faster for incremental builds. CircleCI runs each cloud macOS job in a fresh M4 Pro virtual machine, so DerivedData and package caches must be restored every time. A self-hosted Mac mini M4 is a physical machine dedicated to you, with persistent DerivedData and SPM caches and no wait for a cloud machine to start.
Can I run multiple CircleCI jobs concurrently on one Mac Mini?
Not with one runner. CircleCI supports a single machine runner per machine, and each runner takes one job at a time, so jobs sent to the same resource class wait until the Mac is free. To run jobs in parallel, add one Mac per extra concurrent job and register it in the same resource class: CircleCI sends each queued job to a free runner, within your plan's limit on concurrent self-hosted tasks (5 on Free, 20 on Performance, as of October 2026). Inside a job, Xcode can still run tests in parallel on several simulators. For heavier jobs, the Mac mini M4 Pro (12-core CPU, 24 GB, from $229/mo, USD, excl. tax) gives more headroom.

Start with a Mac Mini M4 for Your CircleCI Pipelines

Deploy a dedicated Mac Mini M4 as your CircleCI self-hosted runner. Unlimited build minutes starting at $85/month.

My Remote Mac prices in USD, excluding tax.

Looking for more detail?

Browse the full documentation for step-by-step setup, configuration references, and troubleshooting.

Open the documentation →