Skip to content

macOS Build Agent Upgrade Guide

This guide explains how to safely upgrade our macOS build host and keep the runner stable.

Overview

During an upgrade we must:

  • Stop the runner (guest vm) safely (do not kill it during an active build).
  • Free enough disk space for the OS update and (optional) Xcode changes.
  • Use VNC to complete UI-required steps.
  • Re-apply security settings (Wi-Fi, auto updates, etc.).
  • Validate tooling (sudo, Homebrew).
  • Restore runner and guest image setup.

1) Prepare the host and stop the runner safely

Why we must stop safely

If you stop the runner directly, the runner (guest vm) can shut down while a build is running. To prevent this, use the safe stop scripts provided on the build image.

Where to find the scripts

On the host, check:

  • /Users/appcircle/upgrade/

  • Example: agent_stop.sh

These scripts handle a graceful shutdown flow (stop taking jobs, wait, then stop).

Newer versions of scripts

Latest versions can also be found in:

  • ac-script-agent repository

  • Path: osx/scripts/host/configuration

Tip: If scripts differ between images, prefer the latest ac-script-agent version.

2) Free disk space before the upgrade

Upgrades require free disk space. If space is low:

Remove unused Tart VMs

List and clean:

  • tart list
  • Remove unnecessary VMs (based on your environment)

If Xcode stack will change

If the upgrade includes Xcode changes, you can remove old images:

  • Remove /agent/images (only if you are sure it is safe for that host)

Warning: Deleting /agent/images may require re-downloading Xcode-related assets later.

3) VNC access and network topology

During the upgrade, you will need UI access (VNC).

Important detail:

  • When you upgrade your host macOS, your local machine does not have direct network access for VNC.

  • Common workflow:

  • Connect via VNC to a build machine that is reachable.

  • From there, VNC into the other target machines.

4) Perform the macOS upgrade (UI required)

Start the upgrade from the UI (VNC session) and follow the normal macOS update flow.

Notes about defaults:

  • Auto updates are disabled by default on these machines.
  • Wi-Fi is usually disabled by default for security reasons.
  • After an upgrade, the OS may re-enable or change some of these settings.

5) Post-upgrade configuration checklist (mandatory)

After the OS upgrade, connect again via VNC and complete the setup.

Ensure the following:

  • Software Update is disabled (automatic behavior must remain off)
  • Apple Intelligence remains disabled
  • FileVault remains disabled (keep consistent with our baseline)
  • Wi-Fi is disabled again (may be re-enabled by the OS update)
  • Auto Update is disabled again (re-check after reboot)
  • Install/update Command Line Tools to the latest compatible version
  • Remove optional Apple apps if they became incompatible or unnecessary (example: iMovie)

6) Validate access and core tools

Sudo check

Verify sudo still works:

sudo echo test

Homebrew check

Brew can break after OS upgrades. Validate:

brew doctor

If Brew is broken, apply fixes or re-run required patch steps.

7) Apply required host patches (if needed)

If required, use the patch script from:

  • ac-script-agent/m1/host/patch.sh

Run it according to the script instructions and your environment needs.

8) Restore / install required runner components

After the host is upgraded and validated:

  • Ensure the required runner is installed and configured.
  • Confirm the runner can start and is able to receive jobs.

9) VM image handling (Tart)

If VM images must be restored:

  • Download the VM image
  • Copy it into Tart VM storage (as used in your environment)

(Exact commands depend on your internal image distribution method.)

10) Update agent configuration for continuous operation

To keep the guest VM running continuously and working with the runner:

  • Update agent-related information/configuration (according to your internal agent setup)

Quick final verification

  • Runner is up and accepts jobs
  • Wi-Fi is disabled
  • Auto updates are disabled
  • sudo works
  • brew doctor is clean (or known issues documented)
  • Required VM images are present in Tart
  • Host has enough free disk space for normal operations