Webinar: Mac Software Management for MSPs: From Visibility to Governance
Register now
Getting Started
Guide

Workbrew best practices

Adam Selby

This guide helps you get fully set up with Workbrew quickly, while avoiding common deployment pitfalls. In a few steps, you'll see what information is visible in Workbrew, connect your device management service, define core policies, and enroll your first Device.

This guide assumes you have already created a Workspace following First-time setup in Getting started with Workbrew.

1. Connect your device management service (MDM)

While Workbrew supports creating and using Device Groups, you likely already have groups that you can use in your MDM. Most customers can reuse existing groups from your MDM within the Workbrew Console. Read more about MDM integration.

Note: Connecting your MDM does not currently upload the Workbrew package to your MDM, nor does it create an install action for installing the Workbrew Agent to your fleet. You need to install Workbrew using our signed .pkg file, after running a bash script that connects the Workbrew agent you are installing to your Workbrew Console.

Managed Login Item

You should add a Managed Login Item payload to a configuration profile, using the Workbrew Developer Team ID 676JW3JDLF to prevent the Workbrew Agent from being disabled by your users. Instructions for this may vary by device management service.

Privacy Preferences Policy Control (PPPC)

If you are using Workbrew to allow app installs for standard users, you will want to follow our guide Preserve app settings during cask upgrades.

2. Allow essential network traffic

Devices with Workbrew installed need to be able to communicate with the Workbrew Console, as well as download packages from Homebrew. Check Configure your firewall for Workbrew to confirm that required traffic won't be blocked.

3. Understand your users and plan accordingly

Before you roll out Workbrew, it helps to detect Homebrew across your fleet. Knowing how many users have Homebrew already is helpful, and will help you plan your deployment. If your users already have Homebrew installed, Workbrew adopts their copy of Homebrew once Homebrew management is on. Some subset of users may have highly customized configurations, which may throw warnings or errors after Workbrew is installed.

When planning your rollout, we recommend including a mix of non-Homebrew users, casual Homebrew users, and Homebrew power users. As an example, power users may experience PATH issues, where typing brew runs Homebrew directly instead of through Workbrew. Read more: How to fix "conflicting Homebrew wrapper configuration" errors

4. Grant brew access to standard users

Your organization may want to limit administrator accounts in your fleet. Managed brew access is a feature of Workbrew, which automatically identifies Human User Accounts and adds them to the workbrew_users group. This allows standard users to interact with brew, so they can self-install formulae and casks. It works on Devices where Homebrew management is on, which step 5 covers.

5. Connect your first Devices

Your new Workspace starts with Homebrew management turned off, so that you can roll Workbrew out for full visibility from day one. You can turn on Homebrew management for a subset of Devices, such as your direct IT team. This allows you to add Devices for visibility while also testing Workbrew fully with a smaller group at the same time. Later, you can enable Homebrew management for all Devices when you're ready.

To easily test Workbrew on a single Device running macOS 26 or later, you can download the Workbrew app and enroll directly from the app after installation. You'll log in to Workbrew Console, select your Workspace and see your Device within minutes. On an older Mac, install Workbrew manually instead. For broader deployment to your pilot audience or your full fleet, deploy through your device management service. Once you've added the Workbrew installer script and package in your MDM, push it to your fleet. After install, you will see Devices appear in Workbrew Console quickly, usually within a few minutes. The Workbrew Agent checks in every 15 minutes, and you can force a check-in by running brew update.

If your organization uses an endpoint privilege management (EPM) or privilege access management (PAM) product or is using macOS' built-in binary allowlisting feature, you may need to add Workbrew's account, process, or Team ID first. Read more: Configure endpoint privilege management for Workbrew, Configure macOS binary allowlisting for Workbrew

6. Setup lightweight Policies

Workbrew offers complete flexibility to cover a variety of use cases, ranging from fully locked down to a subset of packages available in Homebrew to visibility-only monitoring. When you're getting started, we recommend starting from visibility-only, with only lightweight Policies in place. We recommend waiting to set up additional Policies such as denylist and allowlist Policies.

Policies, Automatic Uninstalls and Vulnerability Patching only act on Devices where Homebrew management is on. On read-only Devices, Workbrew reports Policy violations and vulnerabilities but does not act on them.

Admin contact

To get started, you should define the name and contact details for the "Workbrew administrator". This should be a name such as an internal department and details on how to contact said department. This information is shown when a user tries to install a forbidden package or cask. You can set this in Policies → Admin contact, which will also show you a preview of this message to users in Terminal.

Automatic Upgrades and Automatic Uninstalls

While it may be tempting to immediately enable automatic upgrades of outdated packages and casks, it is recommended to first gain visibility into your fleet's installed formulae and casks. This will allow you to make informed decisions about the impact automatic upgrades will have when enabled, and allow you to send both internal user-facing and support-facing communications as needed.

However, automatic uninstalls of packages and casks that you have explicitly denied access to is a sensible default for most organizations. On the Automatic Uninstalls page, click Enable Automatically Uninstalling Forbidden Packages to turn this on. If you forbid a package or cask through the Workbrew Console, it will now be automatically uninstalled at the next check-in.

Enable Vulnerability Patching

A more targeted option than Automatic Upgrades, vulnerability patching allows you to only upgrade packages or casks that have confirmed security vulnerabilities present in your fleet. This feature allows you to patch based upon a specific CVSS severity. You may only want to automatically upgrade formulae or casks with a critical CVSS score to start, to reduce potential impact to developers.

Note: Before enabling this feature, you may want visibility first. Review vulnerabilities in your fleet and their severity scores to understand the impact of this policy to your users. Enabling this feature may upgrade packages that developers do not expect to get upgraded. However, as Homebrew operates on a rolling release model most users will expect to be upgraded when interacting with brew. Read more: Automatically patch vulnerable packages

Where to go next

After you're set up for your early testing, you'll naturally want to do more with Workbrew. A few suggestions of next steps to consider before rolling out Workbrew more broadly are below.

Notifications

As the admin, you may want to receive email or Slack notifications. Under Settings → Notifications you can select from multiple notification types. Additionally, you can also send event notifications as webhooks, to pull data from the Workbrew Console into your SIEM. As an example, you may want to send high-value security events such as New Vulnerability to your SIEM.

Tap registration

Workbrew inventories all taps that are in use across your fleet. Taps are the sources of software that packages are installed from. In your taps list, you will see the official Homebrew taps, but you'll also find a list of other taps that your users have already set up as sources. You can confirm a tap is legitimate by registering it — associating a Git remote with a tap name. Tap trust is a core feature of Homebrew, and adding new taps requires users to trust a tap before installing something from an external source. Tap registration helps you ensure the tap they trust is the tap they intend to trust.

GitHub or GitLab Integrations

Workbrew supports automatically inventorying private taps that your company may use for internal software distribution. Taps selected via our GitHub or GitLab integration will be automatically installed, and are kept up-to-date on all Devices. Your internal packages are then made available for Policies in Workbrew Console, and you can use them in Default Packages.

Default Packages

You may have software that you want to automatically be installed for your users. Workbrew can do this for you, whether this is a formula or a cask. You can even add taps to Default Packages, ensuring everyone in your company has an internal tap available to them.