End-users using zsh will see a warning when using brew after installing Workbrew that states:

zsh compinit: insecure directories and files, run compaudit for list.
Ignore insecure directories and files and continue [y] or abort compinit [n]?

This happens because zsh treats files owned by a different user as potentially unsafe. Since Workbrew manages Homebrew under the workbrew user, zsh flags the completion files as insecure. This is a known zsh behavior and not an issue with Workbrew itself. Users who rely on brew completions will need to apply a fix to prevent these warnings from appearing.

To resolve this, users should add the following to their ~/.zprofile:

echo 'autoload -U compinit && compinit -u' >> ~/.zprofile
source ~/.zprofile

This ensures that zsh initializes completions while bypassing security checks for Workbrew-managed files and reloads the user's ~/.zprofile file immediately. If the user is on Ubuntu, they may also need to add:

echo 'skip_global_compinit=1' >> ~/.zprofile
source ~/.zprofile

This prevents the system zsh configuration from running compinit without -u, which would reintroduce the warning.

If a user also has nvm installed, they must ensure that autoload -U compinit && compinit -u runs before nvm initializes completions to avoid conflicts.

Users should add eval $(/opt/workbrew/bin/brew shellenv) to their shell startup configuration. If users already have eval $(/opt/homebrew/bin/brew shellenv) in their shell startup configuration, that will also work.

Workbrew will attempt to stop all existing brew services on installation. After installation, Workbrew will run all (non-root) services as the workbrew user.

You need to run brew through /opt/workbrew/bin/brew, and not /opt/homebrew/bin/brew or /usr/local/bin/brew. Please see the FAQ above about adding Workbrew and Homebrew to PATH.

With Workbrew, the Homebrew directory is intentionally not writable by non-workbrew users. Instead, configure your tools to write to your HOME directory. See below for instructions for npm. If you need help with other tools, please contact us and we'll help.

npm install -g fails with EACCES errors because the npm global install directory is not writable by non-workbrew users under Workbrew. Please configure npm install -g to install into your HOME directory using the following steps:

1. Create the npm global directories under HOME: mkdir -p ~/.npm-global/bin ~/.npm-global/lib
2. Configure npm to use the directories created above: npm config set prefix '~/.npm-global'
3. Add your npm global directory to PATH: export PATH="~/.npm-global/bin:$PATH"

See the npm documentation for more details.

Some macOS updates or App Store auto-updates might reset the Xcode license. Until the license is accepted again, brew commands and Workbrew Agent check-ins may fail.

Console admins can remediate this by deploying the following script via their MDM:

#!/bin/bash
set -euo pipefail

if /usr/bin/xcrun -find xcodebuild >/dev/null 2>&1; then
  if ! /usr/bin/xcodebuild -license check >/dev/null 2>&1; then
    /usr/bin/xcodebuild -license accept
  fi
fi