Webinar: Workbrew 2.0: Secure the software your company runs
Register now
Getting Started
Guide

Turn on Homebrew management

Petros Amoiridis

This guide shows how to move Devices from read-only to managed, either for every Device in a Workspace or for a single Mac. Read What changes on a Device when Workbrew manages Homebrew first if you have not decided yet, because the Workspace setting cannot be turned off again.

Before you begin

  • You need the administrator role in the Workspace to change its settings.
  • Each Mac needs the Command Line Tools for Xcode. A Device without them stays read-only until they are installed. You can install them with xcode-select --install, with Apple's .pkg, or through your MDM.
  • Tell the people using the Devices what to expect. Homebrew services they started are stopped at the switch and stay stopped until someone runs brew services start, and Standard Users need brew access granted before brew runs for them again.

If Manage Homebrew on devices is already ticked and cannot be changed, your Workspace manages Homebrew already and there is nothing to do.

Turn it on for every Device

  1. In the Workbrew Console, go to Settings and open the Workspace tab.
  2. Tick Manage Homebrew on devices.
  3. Confirm and save the setting.

Each Device starts switching at its next check-in, which by default happens within 15 minutes. The switch waits for running Commands to finish and for the Mac to be awake, so a sleeping laptop switches when it wakes.

Devices you add later install as managed. One that cannot reach the Console during installation, or lacks the Command Line Tools, installs read-only and switches later.

Turn it on for a single Device

Use this when you want to try Policies or Package Requests on your own Mac while the rest of the Workspace stays read-only.

  1. Go to the Devices page and click manually in the subtitle to open the Manual Setup dialog.
  2. Tick Manage Homebrew on this device. The script in step 1 of the dialog changes to include the request for management.
  3. On the Mac, run the script, install the Command Line Tools if they are missing, then download and run the Workbrew Installer. Run the Installer again even if Workbrew is already on that Mac, because the Installer is what acts on the request.

To do the same through your MDM, install the Command Line Tools first, then run this script on the Device and push the Workbrew Installer .pkg. Without the tools, the Installer uses up the request and installs read-only.

sudo mkdir -p /opt/workbrew/etc
sudo chown 0:0 /opt/workbrew/etc
sudo chmod 0755 /opt/workbrew/etc
sudo touch /opt/workbrew/etc/adopt-homebrew

Run the Installer soon after the script. The request stays on the Mac until an Installer run uses it, and Workbrew's own automatic updates count as an Installer run. A request left behind would switch the Device at its next update, when nobody is expecting it.

A Device managed this way receives the Workspace's Policies, and you can create Default Packages and Commands for it. Granting brew access from the Console still needs the Workspace setting though, so if the person using this Device is a Standard User, you'll need to manually add them to the workbrew_users group via your MDM.

Check that a Device switched

Open the Device in the Console and look at Homebrew Mode. It reads Enabling management while the switch is in progress and Managed when it is done. A Device usually shows Managed one check-in after it starts.

On the Devices page, the Homebrew mode filter lists the Devices in each state, which is the quickest way to see who is left after you turn management on for a Workspace.

If a Device does not switch

A Device that fails shows Adoption failed in the Devices list and a banner on its own page with the last error. Workbrew keeps retrying on its own, so most fixes are a matter of removing the cause and waiting.

  • Missing Command Line Tools for Xcode. Install them on the Device. Workbrew checks again at every check-in and switches the Device once they are there.
  • Any other error. Workbrew retries after an hour, then at longer intervals up to once a day. If the same error keeps coming back, contact us with the error text from the banner and /var/log/install.log from the Mac.
  • Homebrew's folder is a symbolic link. Workbrew does not manage a Homebrew whose folder (/opt/homebrew on Apple Silicon, /usr/local/Homebrew on Intel) is a symlink to somewhere else. That Device never shows Adoption failed. In a Workspace with management on it stays on Enabling management and reports no Homebrew packages. Contact us if you need it managed.