FAQs

To manually add a Device to a Workspace, follow these steps:

Step 1. Run the API key install script:

#!/bin/bash
if [[ $OSTYPE == darwin* ]]; then
  WORKBREW_HOME="/opt/workbrew/home/Library/Application Support/com.workbrew.workbrew-agent"
else
  WORKBREW_HOME="/opt/workbrew/home/.local/share/workbrew"
fi
sudo mkdir -pv "${WORKBREW_HOME}"
sudo chmod 700 "${WORKBREW_HOME}"
echo "qzbgukhwea5kie0r3axedxmiodxwwcamlytcpmlpffx07zzdbrykf039zweyitzs" | sudo tee "${WORKBREW_HOME}/api_key"

Step 2. Install the Command Line Tools for Xcode with one of these methods: - Use Apple's .pkg - Run xcode-select --install from a Terminal - Run the following script:

#!/bin/bash
if [[ $OSTYPE == darwin* && ! -f "/Library/Developer/CommandLineTools/usr/bin/git" ]]; then
  CLT_PLACEHOLDER="/tmp/.com.apple.dt.CommandLineTools.installondemand.in-progress"
  sudo touch "${CLT_PLACEHOLDER}"
  CLT_PACKAGE="$(softwareupdate -l | grep -B 1 "Command Line Tools" | awk -F"*" '/^ *\*/ {print $2}' | sed -e 's/^ *Label: //' -e 's/^ *//' | sort -V | tail -n1)"
  sudo softwareupdate -i --verbose "${CLT_PACKAGE}"
  sudo rm -vf "${CLT_PLACEHOLDER}"
fi

Step 3. Download and install the latest Workbrew Installer .pkg for macOS (or .sh for Linux/WSL (in beta)).

The Workbrew Installer is automatically and periodically upgraded. If you wish to upgrade manually, download the latest Workbrew Installer .pkg for macOS (or .sh for Linux/Windows Subsystem for Linux (in beta)) and install it on your device.

The Workbrew Agent on Devices will send information to and run commands from the Workbrew Console every 15 minutes (assuming they're awake and connected to the internet). You can force a device to check in by running brew update or sudo launchctl kickstart -k system/com.workbrew.workbrew-agent.

Workbrew supports three access modes that define the expected level of brew access per device or device group. Once configured in the Workbrew Console, the Workbrew Agent enforces them. Workbrew doesn't modify or elevate the underlying macOS user permissions, it only reports whether the device is compliant with the configured policy (for setting brew access on devices see: 'Which users can run brew on a Device?').

You can set a desired access mode for your workspace in your Workspace Settings, and override it per group in Device Groups.

• End-users can self-install any allowed formulae or casks
• Because they're in the admin group, they can also use sudo to modify Homebrew or override policies (even if temporarily)
• The Workbrew Console reports devices as “Sudo” if the end-user is in the admin group
• Workbrew doesn't grant or escalate privileges as it assumes the user already has sudo access

• End-users can self-install formulae
• End-users can self-install casks only if they're explicitly listed in a Cask Allowlist policy (Enterprise plan only)
• HOMEBREW_FORBID_CASKS environment variable blocks all other cask self-installs
• Admin's can provision casks to Standard users via Default Packages
• Forbidden Formulae or Forbidden License policies can block formula self-installs
• The Workbrew Console reports devices as “Standard” if the end-user is in the workbrew_users group (and not in admin)

• End-users can't run brew at all
• Access only to formulae and casks provisioned with Default Packages
• The end-user isn't in either the admin group or the workbrew_users group

There's also a "hidden" mode, mainly for internal use building Workbrew and Homebrew. We include it for full transparency:

• "Homebrew Maintainer or Contributor": end-users that need full modification access to Homebrew to maintain or contribute to Homebrew so are added to the workbrew group
• They can modify Homebrew without using sudo
• This permission model is only for Homebrew's maintainers and contributors

After Workbrew deployment, the brew CLI is available to all users in the admin or workbrew_users groups.

To add a user to the workbrew_users group (reporting them as “Standard” in the Workbrew Console), run the following command or deploy via MDM:

dseditgroup -o edit -a "$(/usr/sbin/scutil <<< "show State:/Users/ConsoleUser" | awk '/Name :/ && ! /loginwindow/ { print $3 }')" -t user workbrew_users

Please note: This will only succeed if there is a user currently logged in to the Mac. MDMs tend to operate differently in this area. If your MDM provides a way to inject the user account associated with a device into a script, you can use something like this instead, where USERNAME should match whatever variable your MDM injects into the script environment: dseditgroup -o edit -a "${USERNAME}" -t user workbrew_users.

Devices configured with an API key will automatically add (and re-add) themselves to the Workbrew Console's Devices page. Devices not configured with an API key will use the Workbrew improved security configuration (for example multiple users) but can't communicate with the Workbrew Console.

Some casks (never formulae) installed via Homebrew require sudo access to complete their installation. Since sudo normally prompts end-users for a password, that doesn’t work well for installs that are centrally managed via Workbrew.

To handle this securely and non-interactively:

• Workbrew adds a config file at /etc/sudoers.d/workbrew
• This file grants passwordless sudo access, but only to a specific system user: _workbrewd
• _workbrewd is the user account that runs the Workbrew Agent, which is a background daemon
• This limited sudo access allows Workbrew to safely and silently install those packages without giving broader root privileges to end-users and maintain the principle of least privilege

Run the uninstaller by executing sudo /opt/workbrew/sbin/uninstall from a Terminal. This will bring the device back to ‘vanilla’ Homebrew (e.g. /opt/homebrew/bin/brew).

Please see the Contact page.