Rebuild Mac Automation Tools from a Brewfile

When a hosted Mac agent drifts or needs rebuilding after a failure, the shortest recovery path is a versioned Brewfile that reinstalls every tool with one command. This guide covers capturing the file from a working machine, detecting drift on a running agent, and restoring the same toolchain on a fresh Figment Mac. The commands below come from the official Homebrew Bundle documentation.

rebuild on the same tier you ran before. If your automation is standard CLI tooling (Homebrew, Python, Node.js, Ruby, Go, curl, jq, git), the Figment virtual Intel macOS environment at $29/month is the cheapest clean slate. If your Brewfile needs to execute ARM-only binaries or Apple-silicon-only casks, request an M-series Mac starting at $95/month; the exact chip, RAM and disk are set in the quote. Physical i3 ($49) and physical M-series plans collect requests until supply is confirmed.

Choose a Mac plan for the rebuild

A Brewfile is an environment-management artifact; the plan you pick is the one that actually runs your workload.

The $29 virtual Intel macOS environment runs real macOS on Linux/KVM. Compatible Intel toolchains work, including supported versions of Xcode 26 or earlier per Apple's Porting your macOS apps to Apple silicon guidance. There is no GPU acceleration and no audio. Access is through the browser console; inbound SSH is not currently implemented, but outbound CI agents connect normally. Choose M-series for ARM execution, Xcode 27, visionOS or GPU work.

Inputs the Brewfile actually captures

brew bundle dump records installed formulae, casks, taps and (if mas is installed) Mac App Store entries. It does not capture:

• Python pip packages, npm global modules, RubyGems, Go modules
• Files placed under /usr/local or /opt/homebrew manually
• macOS system settings, launchd plists, cron entries
• Shell dotfiles or editor config

Pair the Brewfile with a requirements.txt, package.json, or go.mod committed to the same repository for a complete rebuild. Note that brew bundle does not produce a Brewfile.lock.json; Homebrew does not pin to specific upstream versions, so reproducibility comes from the Brewfile text plus your language-level lockfiles, not a Homebrew lockfile.

You will need Homebrew installed on the source machine, terminal access to that machine (the browser console on the $29 VM), and write access to the repository that will own the Brewfile.

Generate and version the Brewfile

On the known-good machine:

brew bundle dump \
  --describe \
  --file="$HOME/dotfiles/Brewfile" \
  --force

--describe writes a comment with each package's description; --force overwrites an existing file. The output is a small, readable Ruby-style manifest:

# Brewfile — automation-agent v1.4.2 — 2026-11-10

tap "homebrew/bundle"

brew "curl"
brew "jq"
brew "python@3.12"
brew "node@20"
brew "git"
brew "gh"
brew "shellcheck"
brew "ffmpeg"
brew "imagemagick"
brew "mas"

Commit it with a dated header so future readers can trace which agent generation the file represents.

Install on a fresh Figment Mac

After installing Homebrew on the new machine (follow the installer at brew.sh), run:

brew bundle install --file="$HOME/dotfiles/Brewfile"

brew bundle install is idempotent; it skips what is already installed. If a line fails, Homebrew continues with the rest and exits non-zero at the end — read the summary and re-run after each fix. For a pre-job gate, combine install with a check:

set -euo pipefail
brew bundle install --file="$HOME/dotfiles/Brewfile"
brew bundle check  --file="$HOME/dotfiles/Brewfile" --verbose

brew bundle check --verbose lists every missing dependency and exits non-zero if the Brewfile is not fully satisfied, without changing the system. Treat a non-zero exit as a hard failure of the job — do not time it as a successful run.

Detect drift

Drift happens when someone upgrades, installs, or removes a package outside the Brewfile. Two commands surface it:

# What is installed that the Brewfile does not list?
brew bundle cleanup --file="$HOME/dotfiles/Brewfile"
# (add --force to actually remove the extras)

# Which installed formulae have newer upstream versions?
brew outdated

A small drift report script writes both to a file for upload as a CI artifact:

#!/usr/bin/env bash
# version-drift-report.sh
set -euo pipefail

STAMP=$(date -u +%Y%m%dT%H%M%SZ)
REPORT="${TMPDIR:-/tmp}/drift-${STAMP}-$$.txt"
BREWFILE="$HOME/dotfiles/Brewfile"

{
  echo "=== Environment inventory: ${STAMP} ==="
  sw_vers
  echo
  echo "--- Brewfile formulae: installed versions ---"
  grep '^brew ' "$BREWFILE" | awk -F'"' '{print $2}' | while IFS= read -r f; do
    v=$(brew list --versions "$f" 2>/dev/null || echo "NOT INSTALLED")
    printf "%-30s %s\n" "$f" "$v"
  done
  echo
  echo "--- Extras not in Brewfile ---"
  brew bundle cleanup --file="$BREWFILE" || true
  echo
  echo "--- Outdated packages ---"
  brew outdated || true
} > "$REPORT"

echo "Drift report: $REPORT"

The output is your reproducible environment inventory: exact installed versions, macOS build, timestamp. Store a copy next to each production build artifact so a specific output can be tied back to the exact toolchain that produced it.

Failure and recovery checks

Cost and operating limits

The $29 virtual Intel macOS plan is billed monthly; a two-week rebuild window still costs one month. Rebuild time depends on package count and Homebrew's download speed from your region — measure it on your own Brewfile rather than relying on a quoted benchmark. If you run two M-series Macs under the $999 Managed Mac Team plan, the same Brewfile rebuilds both machines from one commit; pin a version tag in the file header for each deployment so a rollback is obvious.

For physical i3 ($49) or M-series (from $95) hardware, submit a configuration request before the rebuild so the target machine is ready. The Managed Build Mac ($249) and Managed Mac Team ($999) plans include CI setup, backups and monitoring; a Brewfile fits naturally into that CI setup as the environment definition.

Start the rebuild

Start a hosted Mac at Figment · Browse Mac hosting plans

Related guides:

• Mac agent browser profiles
• Mac agent artifact delivery
• Mac GitHub Actions self-hosted runner