Webinar: Workbrew 2.0: Secure the software your company runs
Register now
Getting Started
Guide

Getting started with Workbrew

Luke Hefson & Joe Nash

This guide will help you and your organization get the most from Workbrew, and is for people who will be administrating devices in some capacity, for example:

  • An IT administrator looking to improve developer productivity whilst staying compliant

  • A developer managing Homebrew configurations across your work and personal devices

  • A security team wanting to get an overview of potential vulnerabilities across the fleet, whether in Homebrew packages, npm packages, VS Code extensions or macOS applications

First-time setup: Create a Workspace and enroll your own device

In Workbrew, a Workspace represents your organization, and contains the devices belonging to your fleet. In this section, you will create a Workspace and enroll your own device in it, so you can see Workbrew working before you roll it out.

  1. Sign up at console.workbrew.com with your work email, or with Apple, GitHub, Google or Microsoft

  2. Create a Workspace, or join one if a colleague has already created it

  3. Download Workbrew from the Download page in the Workbrew Console. The package installs the Workbrew Agent and the Workbrew app

  4. Install the package on your device, then open the Workbrew app and follow the enrollment steps. The app sends you to the Console to sign in and choose the Workspace, then enrolls the device

Your device appears on the Devices page within a few minutes.

Adding additional devices

With your first device enrolled, you're ready to add more. There are three ways:

  • Deploy with your MDM. The recommended route for a fleet. Devices enroll with no action from the person using them, and Device inventory syncs from your MDM. Follow the deployment guide for your MDM below

  • Invite a device. On the Devices page, click Add Devices → Invite a device to create a single-use link that expires in 24 hours. Send it to whoever is setting up the device. It walks them through installing Workbrew and enrolling in your Workspace, and they don't need a Workbrew account or access to the Console

  • Manual setup. Also under Add Devices, for scripted or unattended installs where neither of the above fits. See How to manually install Workbrew

Workbrew has integrations with a variety of MDMs. Follow the deployment guide for your favorite MDM below:

You can still use Workbrew if your MDM isn't on this list. Contact us for help getting set up.

What brings you to Workbrew? Determining your objectives

Workbrew has features for remote management, developer productivity, security & compliance, and analytics & observability. Those all may be useful to your org, but it's likely you have more pressing reasons to use Workbrew. This section will help you choose your setup path and address your priorities fast.

Whatever brought you here, the rollout that works best follows the same order. Enroll the fleet first and let the inventory fill in for a week or two before you enforce anything. Every device reports what is installed from the moment it enrolls, so you can see which packages, versions and vulnerabilities you actually have before deciding what to forbid, allowlist or patch automatically. Policies written against real inventory are narrower, break fewer developers, and are easier to explain when someone asks why an install was blocked.

Monitor installed software for updates, usage, and vulnerabilities

You want to understand what software is installed across your organization, whether it is up to date, and whether any known CVEs affect your fleet. Workbrew inventories Homebrew formulae and casks, npm packages, VS Code extensions and macOS applications on every enrolled device, and reports vulnerabilities in all of them.

Check out Visibility into software across Devices to learn how to get the most from the Workbrew Console.

Much of the information available in the console is also available in JSON or CSV formats via the Workbrew API, allowing you to bring data into existing dashboards or automation pipelines. Check out the guide on getting started with the API, or dive straight into the reference documentation (requires login).

Control the software developers install

You know developers in your organization install their own tools, from brew to npm install -g to VS Code extensions, and probably already are, and you want to manage that. The Workbrew Agent securely wraps brew, letting developers keep the experience they love, whilst allowing you to control access by groups, allow or disallow Homebrew packages, and set policies around usage. For npm packages and VS Code extensions, Workbrew reports everything installed and lets you upgrade or remove it. Blocking rules for those sources are not yet available.

Start with Organize devices with Device Groups, allowing you to target different devices and users with different configurations and policies. You are then ready to Configure policies for formulas, taps, and casks.

Deliver and maintain software remotely

You want to equip your developers with all the tools they need on Day 0, and be able to remotely install, update, or remove software afterwards. With Workbrew, you can deliver anything in the brew ecosystem, and keep npm packages and VS Code extensions current or remove them, without touching the device.

If you haven't already, start with Organize devices with Device Groups to enable you to target different groups of devices or users with Default Package configurations or Commands. If you want to deploy software to new devices, or when devices join a particular Device Group, check out Standardize software across Devices with Default Packages. Finally, Remote management using Commands will show you how to run and monitor any brew command, or an upgrade or uninstall of an npm package or VS Code extension, on a device in your fleet.

Configure Workbrew Features

This section provides configuration steps feature-by-feature. Unsure where to start? Check out What brings you to Workbrew? Determining your objectives.

Organizing devices with Device Groups

Group devices based on team, department, or specific requirements using Device Groups. Device Groups make it easy to apply remote management configurations and commands to a subset of devices, streamlining fleet management.

Creating Device Groups

  1. Click on the Devices tab in the sidebar to view all of your Workspace's devices

  2. Search for and select more than one device

  3. Click Add to groups and then Create a new group from the dropdown

  4. Give your group a name and select Create Device group

View and manage Device Groups

  • Click on Device Groups in the sidebar to view all your Device Groups

  • Click on the number of devices in a group to view them filtered on the Devices page

  • Add more devices to an existing group by using the Add to groups dropdown

Syncing Device Groups from MDM

If you’ve connected your MDM, existing device groups will automatically sync into Workbrew. Synced groups are marked as Managed by… your MDM and update automatically as their membership changes in your MDM.

Visibility into software across Devices

The Dashboard, Vulnerabilities, Analytics, Packages, Taps and Licenses pages in the Workbrew Console provide insight into software usage, trends, and vulnerabilities across your devices. Inventory covers every source Workbrew collects, not only Homebrew.

Dashboard

  • Get a high-level view of your connected devices. Drill down to review specific details about installed packages, usage history, and configurations

Vulnerabilities

  • Identify and click-to-view CVEs for known vulnerabilities in Homebrew packages, npm packages, VS Code extensions and macOS applications on all connected devices, and filter by source

  • See CVE vulnerability scores at a glance

  • Isolate affected devices and run remote commands to remediate on just those devices

Analytics

  • Search for, view and filter across devices to get insight into how users have run brew on which Workspace devices, when

Packages

  • View every package installed across all connected devices, from Homebrew formulae and casks to npm packages, VS Code extensions and macOS applications, and filter by source

  • See which groups of devices are running which packages and whether they're up-to-date with the latest versions

Taps

  • View all of the Homebrew Taps that are hosting package definitions across all your connected devices

  • See which groups of devices are accessing Homebrew Taps and how many packages a tap can install

Licenses

  • Identify and learn more about the open source licenses that installed packages across your connected devices are using

Set Policies

Use Policies to define high-level security and compliance rules for your fleet.

Step 0: Configure your error message

Before setting up policies, configure the administrator name and contact message that end-users will see in the brew CLI during a blocked install:

  1. Go to Policies in the sidebar

  2. Edit the Workbrew administrator name and Contact details fields

  3. Click Save

Example: Lock down taps, restrict installs, and control casks

A common baseline setup for organizations operating within a highly regulated industry is:

  • Automatically patch vulnerable packages with a CRITICAL severity rating

  • Only allow official Homebrew taps and any connected private taps (no third-party taps)

  • Create a blocklist for risky Homebrew casks, formulae and licenses

  • Maintain a controlled allowlist of Homebrew casks

  • Automatically uninstall forbidden Homebrew casks and formulae

Vulnerability Patching is available with the Vulnerability Patching upgrade. The rest need the Governance upgrade, or a Business or Enterprise plan. See Plans.

To do this:

  1. Go to Policies in the sidebar

  2. Click New Policy → Vulnerability Patching

    • Set the minimum severity to patch for Homebrew formulae, Homebrew casks, npm packages and VS Code extensions

    • Choose All Devices and click Enable Vulnerability Patching

  3. Click New Policy → Allowed Taps

    • By default, only homebrew/homebrew-core, homebrew/homebrew-cask, and any connected private taps will be set

    • Choose All Devices and click Create policy

  4. Click New Policy → Forbidden Formulae

    • Add any formulae you want to block (for example proxytunnel)

    • Choose All Devices and click Create policy

  5. Click New Policy → Forbidden Licenses

    • Select any licenses that shouldn't be allowed (for example AGPL-3.0-only, AGPL-3.0-or-later)

    • Choose All Devices and click Create policy

  6. Click New Policy → Casks Allowlist

    • Add a set of approved casks (for example visual-studio-code, zoom, slack)

    • Choose All Devices and click Create policy

  7. Click New Policy → Automatic Upgrades and Uninstalls

    • Enable Automatically uninstall forbidden packages

    • Choose All Devices and click Create policy

These policies immediately apply to matching devices, and are enforced by the Workbrew Agent. Blocked installs return clear error messages pointing users to your designated administrator contact.

Remote management using Commands

The Commands page lets you manage software remotely across multiple workspace devices from the Console. A Brew Command runs any brew command. An Npm Command or VS Code Command upgrades or uninstalls a named npm package or VS Code extension, optionally to a specific version. Npm Commands also let you choose whether to act on system installs, user installs or both.

Run commands remotely

  • Execute any Homebrew command, such as brew install, brew update, or brew upgrade, across one or more devices in your fleet

  • Create commands by either manually writing and running a Brew Command argument (see example usage below), or by clicking on any of the quick-action Upgrade and Remove buttons throughout the Console to pre-fill a Command to run immediately

  • Run new commands immediately after creation or scheduled for a specific date and time

Track status and logs

The Console logs every Command under Command Runs, allowing you to track the status, view execution details, and troubleshoot issues as needed.

Command example usage

To upgrade VS Code once a week on just your developer's devices (and include any new devices added to the group).

  1. Create a Device Group called 'Developers', adding all your development team's devices to the group

  2. Go to Commands in the sidebar and click New Command → New Brew Command

  3. Add brew upgrade --cask visual-studio-code as an argument

  4. From the Run on Devices field select Developers

  5. Ensure that Run on new Devices added to the Device Group is checked

  6. Select Weekly from the Schedule dropdown

  7. Click Create Brew Command to create the command and run it now on all devices in the group

Standardize software across Devices with Default Packages

Use Default Packages to ensure essential software is consistently installed across your devices.

Define lists of essential packages

Create Brewfiles by listing essential packages for different devices, then install them all with a single command.

View and manage all your Default Packages

See all your Default Packages at a glance and know which lists of packages target which groups.

Monitor deployment

Track installation logs and status on the Command Runs page to verify successful deployment across targeted devices.

Default Packages example usage

To get your whole team started with a list of pertinent default packages:

  1. Click Default Packages in the sidebar

  2. Click the New Brewfile button

  3. List a combination of essential packages in the Brewfile text field that you'd like installed by default on all devices across your fleet (for example brew "git", brew "openssl")

  4. Add a label such as 'Essentials-for-Everyone' to describe the goal and denote that this list of default packages will install on every existing and new device in the fleet (as opposed to a label that might denote packages targeted at just a specific team)

  5. Check Run on new Devices added to the Device Group so that these packages will automatically run on all new devices added to your fleet

  6. Click Create Brewfile to create the command and install all the packages across your fleet