What changes on a Device when Workbrew manages Homebrew

Installing Workbrew on a Mac does not have to change anything about Homebrew on it. A Device starts out read-only, which means Workbrew reports what is installed and leaves Homebrew alone. Workbrew only takes over Homebrew once an administrator turns on Manage Homebrew on devices for the Workspace. This page explains the two modes, what the switch does to a Device, and why the switch only goes one way.

Two modes#

A Device is in one of two modes. On a read-only Device, Homebrew belongs to whoever installed it. Workbrew reports inventory and vulnerabilities to the Workbrew Console and changes nothing. On a managed Device, Homebrew belongs to Workbrew, and the Console can install, upgrade, configure and restrict packages on it.

The mode is a property of each Device, and the Console shows it as Homebrew Mode on the Device's page. The Workspace setting decides which mode your Devices move toward. The Console decides what to send a Device from the mode that Device reports, so a managed Device in a mostly read-only Workspace still receives its Policies.

Linux Devices are always managed. Read-only applies to macOS. In a read-only Workspace, a Linux Device is treated like a single managed Mac.

What a read-only Device does#

On a read-only Device the Workbrew Agent reads what is installed and reports it. That covers Homebrew formulae and casks, npm packages, VS Code extensions and macOS apps, along with the vulnerabilities Workbrew finds in them. The Agent reads Homebrew's folders directly and never runs brew to do it. A read-only Device does not need Homebrew at all. Without it, the Console shows the Device as Read-only, Homebrew not installed and still lists its other software.

Everything else on the Device stays as it was. The user's brew is the same brew, owned by the same account, with the same taps and the same running services. The Workbrew Installer does add Workbrew's own files under /opt/workbrew and creates the accounts and groups the Agent runs with, but it does not touch Homebrew's folders or the PATH.

Workbrew also changes nothing through the Console. A read-only Device receives no Commands, no Default Packages and no Brew Configurations, and no Policy is enforced on it. This includes Commands for npm packages and VS Code extensions, even though those have nothing to do with Homebrew. That keeps the rule simple. If a Device is read-only, Workbrew does not change it. Policy violations on a read-only Device are still reported in the Console. Workbrew does not act on them.

You can still prepare. Policies, Vulnerability Patching and Brew Configurations can be created in a read-only Workspace, and the Console tells you they take effect once management is on. Default Packages and Commands can be created once at least one Device in the Workspace is managed.

What the switch does to a Device#

When management turns on, each read-only Device picks up the change at a check-in and then runs the Workbrew Installer again in its managed form. On that Device, Workbrew:

• Installs Homebrew if the Device does not have it.
• Makes the workbrew service account the owner of Homebrew and of the packages already installed.
• Puts Workbrew's brew at /opt/workbrew/bin in front of Homebrew's on the PATH. From then on brew runs through Workbrew, which is how Policies are applied to what a user types. Some shell setups need adjusting after this, for example the PATH order, zsh completions, or tools like npm that write into Homebrew's folders. Troubleshooting has the fixes.
• Stops the Homebrew services users started and removes their launch agents. They stay stopped until someone runs brew services start, and then they run as the workbrew account. If a service will not stop, the switch fails and Workbrew tries again later.
• Starts applying the Workspace's Default Packages, Policies, Vulnerability Patching and Brew Configurations. Commands set to run on new Devices are queued as well. Packages your Policies forbid can be uninstalled.

The Console shows the Device as Enabling management while this is in progress and Managed once the Device reports back, which is usually one check-in later. The switch waits for running Commands to finish and for the Mac to be awake, so a sleeping laptop switches when it wakes.

The person using the Mac notices two of these changes.

The first is access to brew. On a managed Device, macOS administrators can run brew as before. A Standard User needs to be granted brew access first, and that is true even for someone who installed and owned Homebrew before the switch. Managed brew access describes how that access is granted.

The second is services. A database or other service that was running under the user's account is stopped at the switch and stays stopped until someone starts it again with brew services start. From then on it runs as the workbrew account, and its data belongs to that account too. Troubleshooting covers the effects of that, such as the PostgreSQL role error.

What management makes possible#

Most of what Workbrew does beyond reporting depends on it owning Homebrew.

The last row is about Standard Users. A Standard User cannot install Homebrew for themselves, and one who already has it cannot install most casks, because those need administrator rights. Once Workbrew owns Homebrew it can do that work on the user's behalf, within the Policies you set.

Why it cannot be turned off#

Turning management on is permanent for the Workspace, and a managed Device does not go back to read-only.

Read-only works because someone on the Mac owns Homebrew and can look after it. After the switch that is no longer the case. Homebrew and the services' data belong to a service account, and the people using the Device may be Standard Users who could not own Homebrew again if it were handed back. Workbrew has no step that undoes all of that safely, so it does not offer one.

The way out is to uninstall Workbrew from the Device, which hands Homebrew and the apps it installed back to the user you choose. Services stay stopped until that user starts them. See Decommission a Device or move it to another Workspace.

The Workbrew app in each mode#

The Workbrew app follows the mode of the Device it runs on.

On a read-only Device it is a front end to the user's own Homebrew. The user can browse and install from the whole Homebrew catalog, and nothing needs approval. Apps that need administrator rights cannot be installed from the app in this mode. An administrator is told to install them from Terminal, and a Standard User is told to ask their Workbrew administrator to enable management.

On a managed Device the app works through Workbrew, so the Workspace's Policies apply to it the same way they apply to brew in Terminal.

Related docs#

• Turn on Homebrew management - the steps for a whole Workspace or a single Device
• Managed brew access - how Standard Users get brew on a managed Device
• How the Workbrew Agent uses elevated privileges - what runs as root and why
• Troubleshooting - PATH, permissions and brew services on a managed Device
• How to detect Homebrew across your fleet - find existing Homebrew installs before you roll out