How the Workbrew Agent uses elevated privileges

Workbrew manages Homebrew across a fleet of Devices, and some of that work requires root. This page explains how the Workbrew Agent obtains and bounds the privileges it needs, and why allowing it through an endpoint privilege management (EPM) tool does not expand what Workbrew can do. It is background reading for security and platform teams evaluating Workbrew; for the steps to configure an EPM tool, see Configure endpoint privilege management for Workbrew.

Homebrew management needs root#

Several of the things Workbrew exists to do cannot be done as an ordinary user. Installing and upgrading software, moving applications into /Applications, repairing ownership of the Homebrew prefix, and adding users to the workbrew_users group are all privileged operations. Any tool that manages Homebrew centrally has to perform them with root authority at some point. The question is not whether root is involved, but how tightly its use is contained.

The Agent daemon runs as a dedicated account, not as root#

The Workbrew Agent's background daemon does not run as root. It runs as a dedicated system account, _workbrewd, created at install time for exactly this purpose. The account is hidden, has no password or login shell, and is not a member of the admin group. The daemon holds no root authority of its own. When its work needs root, it either asks the privileged helper described below or, for Homebrew's own privileged steps, elevates through sudo.

This matters because it keeps the Agent's normal operation off root. A process that runs as root continuously is a larger target than one that holds root only for the moments it is needed. Running as a dedicated account also separates the Agent from the workbrew account that user-invoked brew commands run under, so the two privilege contexts stay distinct.

The Agent's own root work goes through a privileged helper#

In current versions of the Workbrew Agent, the operations the Agent itself needs root for run in a separate privileged helper rather than through sudo. These are repairing ownership of the Homebrew prefix, adding users to the workbrew_users group, checking whether an account has a Secure Token, and installing Agent updates.

The helper is a second LaunchDaemon, com.workbrew.workbrew-agent.privileged, and it runs as root. It offers that fixed set of operations and nothing else, and it validates every request itself rather than trusting the caller. Only the Workbrew Agent binary can connect to it. On macOS 14.4 and later, macOS rejects any caller that is not the Agent binary signed by Workbrew. On earlier versions the helper listens on a socket that only the workbrew account can open, and it checks that the caller is /opt/workbrew/bin/brew. The helper never calls sudo, so an EPM rule that acts on sudo does not affect it.

The sudo grant, and why it is scoped the way it is#

On install, Workbrew adds one rule at /etc/sudoers.d/workbrew:

_workbrewd ALL=(root) NOPASSWD:ALL

We want to be upfront that this grant is broad: it lets the _workbrewd account run any command as root without a password. We chose breadth deliberately, and the important detail is what the grant is scoped to.

The grant applies to the _workbrewd account only. To use it, a process must already be running as _workbrewd, which only the Workbrew Agent's daemon, started by launchd, and the Homebrew commands it runs are. A Standard User cannot reach it: when a user runs brew, the wrapper runs as the workbrew account, not _workbrewd, and there is no passwordless sudo grant for ordinary users or for the workbrew account. Privileged work that a user triggers, such as installing an allowlisted cask, is delegated to the daemon over its controlled interface rather than handed to the user.

The grant is broad rather than a list of specific commands because the commands that go through it come mostly from Homebrew. When the Agent runs Homebrew on a Device, for a Brew Command, Default Packages, or a cask a user asked for, Homebrew elevates some cask steps through sudo as _workbrewd. Running a cask's package installer and removing an app during an uninstall or upgrade are two examples. Which commands those are depends on the casks you manage and changes across Homebrew releases. A fixed command allowlist would be brittle: it would silently break legitimate operations whenever Homebrew or the Agent changed, and it would invite a false sense of precision. Scoping the grant to a single dedicated account, and trusting the signed Agent binary that occupies that account, is the control we rely on instead. The Agent is distributed as a binary signed under Workbrew's Apple Developer Team ID (676JW3JDLF), so an EPM policy can pin the elevation to that verified publisher.

Why allowing it through an EPM tool is safe#

EPM tools exist to stop interactive users from escalating their own privileges in uncontrolled ways. A signed vendor management daemon that already holds a deliberate, install-time sudo grant is a different case. Allowing _workbrewd through your EPM tool does not grant Workbrew anything it does not already have: the sudoers rule is installed with the Agent, and the daemon's authority comes from that rule, not from the EPM policy. When an EPM tool intercepts sudo for _workbrewd, it does not reduce that authority. It only breaks the elevation, so cask installs, upgrades, and uninstalls that Workbrew runs fail partway through. On older Agent versions, the Agent's own operations also go through sudo and fail the same way, so the Secure Token check behind Managed brew access fails and Standard Users silently lose brew access. Exempting the daemon restores the behavior Workbrew was installed to provide.

Put differently, the trust decision was already made when you deployed Workbrew to manage Homebrew on your fleet. The daemon's elevation is part of that decision, and the EPM exemption simply lets it function as intended.

The alternative, and its limits#

On older Agent versions, you can leave your EPM tool blocking the daemon and add users to the workbrew_users group another way, with a script deployed through your MDM. That works as an interim step, but it only substitutes for one of the Agent's privileged operations, group membership. The Agent's other root operations on those versions, such as ownership repair and self-update, still run through the same sudo path and remain blocked. A blocked self-update also means the Agent cannot move itself to a version that avoids the problem. See Adding Users to the workbrew_users Group via MDM for that approach.

On current versions the script is unnecessary, because group membership runs in the privileged helper. It also does nothing for the cask steps that still elevate through sudo. Allowing the daemon's elevation is what covers those.

Related docs#

• Configure endpoint privilege management for Workbrew - the steps to apply this in your EPM tool
• Managed brew access - the feature that depends on the Agent's elevation
• Adding Users to the workbrew_users Group via MDM - the MDM-script alternative for group membership
• Why we recommend FQDN-based allowlisting - related reasoning behind another Workbrew environment recommendation