Why Workbrew needs Full Disk Access to update apps in place

When the Workbrew Agent upgrades a cask, the app is sometimes deleted and reinstalled rather than updated in place, which resets settings like its Dock position and notification permissions. This page explains why that happens, and why the fix is to grant the Agent Full Disk Access rather than App Management. For the steps, see Preserve app settings during cask upgrades.

In-place update versus delete-and-reinstall#

When Homebrew upgrades a cask whose app is already installed, it can take one of two paths. If it has permission to modify the existing app bundle, it replaces the bundle's contents in place and leaves the .app folder itself intact. macOS continues to treat it as the same application, so its Dock position, notification permissions, login-item status, and similar state are preserved.

If it does not have that permission, it instead deletes the entire .app folder and installs the new version from scratch. macOS treats the deletion of the app folder as an uninstall and discards the state tied to that app. The same permission gap also breaks cask adoption, where Homebrew takes over management of an app that already exists: the adoption can fail partway through with an Operation not permitted error and leave the app uninstalled.

Why a permission is involved at all#

On modern macOS, modifying files inside another application's bundle is gated by the system's privacy controls (TCC). A tool can be granted this either through the App Management permission or through Full Disk Access. Homebrew checks for the permission by attempting to write a small test file inside the app bundle before it decides which path to take.

Why Full Disk Access rather than App Management#

The Workbrew Agent's daemon runs as a dedicated account that does not own the apps in /Applications. Because of that, both the permission check and the actual update are performed through an elevated helper: Homebrew runs the file operations with sudo. This is the key detail. macOS attributes that elevated write to the sudo and touch chain rather than directly to the Workbrew Agent, and an App Management grant scoped to the Agent's binary does not reliably extend across that chain. The write is still denied, and Homebrew falls back to delete-and-reinstall.

Full Disk Access behaves differently. Granted to the Agent's binary, it is evaluated more broadly by the system and does cover the elevated write, so the in-place update succeeds. In our experience, customers who granted only App Management continued to see the delete-and-reinstall behavior, while granting Full Disk Access resolved it. This is why the profile leads with Full Disk Access, and includes App Management only for completeness.

Why this needs a configuration profile#

On a managed fleet there is a second reason the problem is easy to miss. macOS normally prompts a user to grant App Management the first time a tool needs it, but the Workbrew Agent runs in the background and suppresses that prompt, since there is no one at the keyboard to answer it. The upgrade proceeds down the delete-and-reinstall path silently rather than waiting for a permission that will never be granted interactively.

A configuration profile resolves both issues. It grants the permission without any interactive prompt, it can be scoped to exactly the signed Workbrew Agent binary, and the MDM re-enforces it, so it survives the occasional TCC reset that a major macOS upgrade can cause. This is the same reason other Workbrew permissions are best managed centrally rather than per-machine; see How the Workbrew Agent uses elevated privileges for the Agent's broader use of elevated access.

Related docs#

• Preserve app settings during cask upgrades - how to deploy the profile that fixes this
• How the Workbrew Agent uses elevated privileges - the Agent's broader use of root and how it is bounded
• Managed brew access - another macOS-specific behavior of the Workbrew Agent
• Troubleshooting - other common post-installation issues