Skip to content

Runner & Agent Runtime Environment — Internal Documentation

Purpose

This document explains how Appcircle Runner and Agent environments are designed and prepared (primarily the macOS/Android runner infrastructure), and how key changes are managed (adding a new Xcode version and upgrading the runner macOS version).

Scope

This document covers:

  • Common terminology
  • Environment setup and components
  • Adding a new Xcode to the Runner image
  • Upgrading the Runner OS version

Terminology

  • Host: The physical machine or primary operating system that provides virtualization resources and runs one or more virtual machines (VMs).

  • Guest: A virtual machine (VM) running on the Host, with its own operating system and lifecycle.

  • Agent: Appcircle-developed program(s) running on the Host that handle operational automation and management tasks.

  • Runner: A program running inside the Guest (VM) whose primary purpose is to execute build workflow steps.

  • Self-Hosted Runner: A customer-managed installation type where the Runner runs on the customer’s own macOS environment (either on their VM or physical Mac).

Appcircle Runner Overview

In Appcircle, Runners are hosted in two main environments:

  • macOS Runner: Teknotel datacenter environment
  • Android Runner: OWH cloud provider environment

Runner topology

What you need to create a Runner environment

A Runner runtime requires two main building blocks:

  1. Runner application (the .NET project that runs builds)

  2. ac-agent-build: https://github.com/appcircleio/ac-agent-build

  3. Toolchain used during workflows

  4. Packages and dependencies (brew / ruby / gem / JDK, etc.)

  5. Xcode and related components

Runner Components and Responsibilities

The Runner ecosystem is built around two repositories:

1) ac-agent-build

2) ac-runner-setup

  • Bash/script automation that prepares the Runner environment for the target infrastructure

  • Core responsibilities:

  • Running/configuring the Runner as a service

  • Installing system dependencies (Homebrew, Ruby, gem, JDK, etc.)
  • Installing and selecting Xcode
  • Repo: https://github.com/appcircleio/ac-runner-setup

Runner Delivery Options (Customer Perspective)

Customers can obtain a Runner in two ways:

  1. Self-hosted installation

  2. The customer installs and runs the Runner on their own macOS system.

  3. VM image-based usage

  4. The customer downloads and runs a prebuilt/standard VM image that contains the Runner environment.

Note: Customers generally prefer the VM-image approach. The main reason is that self-hosted setups require downloading packages from many different sources (Homebrew, Ruby, JDK, etc.), which often introduces heavy approval/allowlist processes in corporate networks.

Note: The current self-hosted runner approach does not support Xcode 15.3+ at this time.

Self-Hosted Runner Setup

Requirements (high-level)

  • Runner application: ac-agent-build
  • Environment provisioning: ac-runner-setup

Installation flow (high-level)

  1. Prepare the Runner binary/service using ac-agent-build
  2. Provision the target machine (toolchain + Xcode + note-worthy service requirements) using ac-runner-setup
  3. Run a smoke test / sample workflow

Operational note: On the self-hosted side, package sources and version pinning can create additional approval/allowlist requirements. This is another reason why the VM method is commonly preferred.

VM Runner Image Build

The VM approach is semi-automated. The build scripts can be found in:

High-level approach

  • A Guest image is produced on a Host machine.
  • Required packages and Xcode are added inside the Guest in layered steps.
  • tart is used to create snapshots and progress layer-by-layer.

Layer model

Order Layer
1 OS
2 Server configuration
3 Tools & packages
4..6 Xcode

References for OS Upgrades

Note: When switching to a new OS version, all layers must be rebuilt, and the pipeline must be re-tested end-to-end.

Adding a New Xcode Version

When introducing a new Xcode version, apply the following checks.

Pre-checks

  • Review Xcode release notes
  • Research stability (known bugs / toolchain compatibility)
  • Evaluate impact across providers/environments (macOS runner infrastructure and dependencies/interactions with the Android side)

Process note: For a new Xcode version, we first install and validate it on a VM using ac-runner-setup. If the results are acceptable, we then carry it into the main Runner image flow.

Upgrading the Runner OS Version

OS upgrades must be controlled because they affect Xcode compatibility, toolchain behavior, and pipeline stability.

Suggested checklist

  • Select the target OS version (IPSW availability + hardware compatibility)
  • Verify the Xcode compatibility matrix (xcodereleases)
  • Rebuild all layers
  • Validate toolchain (brew/ruby/gem/JDK, etc.)
  • Execute runner smoke tests + critical workflow tests

Homebrew Version Pinning

Due to tart licensing constraints and environment stability requirements, Homebrew is pinned to the highest supported stable version. This also requires pinning Homebrew components on the Host machine that are used during provisioning.

For a stable Runner environment, Homebrew and other tools should be pinned.

If a customer needs a newer package version, they must adjust their own repo/version preferences accordingly (this is a deviation from Appcircle’s default “stable image” approach).

Source / Reference

These notes were compiled based on the following internal recording: