Getting Started With Workbrew

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

If you are the user of a device managed by Workbrew, you may find {TODO} more useful.

In Workbrew, a Workspace represents your organization, and contains the devices belonging to your fleet. In this section, you will sign-up for an account to create a Workspace and add your first device.

To start using Workbrew, follow these steps:

1. Sign up at console.workbrew.com
2. Follow the onboarding tutorial to confirm your username and create a Workspace
3. Follow the manual device connection steps on the Devices page to manually connect your own device

With your first device set up, you’re ready to add more. You can continue to add devices manually, but it's recommended to distribute Workbrew via a device management platform (MDM) to benefit from zero-touch deployment and automatic inventory syncing.

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

• Fleet
• Iru
• Jamf
• Jumpcloud
• Microsoft Intune
• SimpleMDM

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

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.

You want to understand how your organization is using packages from brew: the packages installed, your organization's update hygiene, and whether any known CVEs affect your fleet. The Workbrew Console provides insights into software usage, trends, and vulnerabilities across your fleet.

Check out Visibility into brew Usage 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 {TODO}, or dive straight into the reference documentation (requires login).

You know developers in your organization want to use brew, and probably already are, and you want to manage that usage. The Workbrew Agent securely wraps brew, letting developers keep the experience they love, whilst allowing you to control access by groups, allow or disallow packages, and set policies around usage.

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.

You want to equip your developers with all the tools they need on Day 0, and be able to remotely install, update, or remove packages. With Workbrew, you can leverage the entire brew ecosystem to help developers hit the ground running.

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 brew 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 brew commands will show you how to run and monitor the execution of any brew command on a device in your fleet.

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

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 subsets of devices, streamlining fleet management.

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

• 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

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.

The Dashboard, Vulnerabilities, Analytics, Packages, Taps and Licenses pages in the Workbrew Console provide insight into software usage, trends, and vulnerabilities across your devices.

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

• Identify and click-to-view CVEs for known vulnerabilities across brew packages on all connected devices
• See CVE vulnerability scores at a glance
• Isolate effected devices and run remote commands to remediate on just those devices

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

• View and filter by all Formulae and Casks installed across all connected devices
• See which groups of devices are running which packages and whether they're up-to-date with the latest versions

• View all of the Taps that are hosting package definitions across all your connected devices
• See which groups of devices are accessing Taps and how many packages a tap can install

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

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

Before setting up policies, configure the administrator name and contact message that end-users will see in the 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

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

• Only allow official Homebrew taps and any connected private taps (no third-party taps)
• Create a denylist for risky formulae and licenses
• Maintain a controlled allowlist of casks
• Automatically upgrade vulnerable packages and uninstall forbidden ones

To do this:

1. Go to Policies in the sidebar
2. Click New Brew 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 Brew policy
3. Click New Brew Policy → Forbidden Formulae
   • Add any formulae you want to block (for example proxytunnel)
   • Choose All Devices and click Create Brew policy
4. Click New Brew 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 Brew policy
5. Click New Brew Policy → Casks Allowlist
   • Add a set of approved casks (for example visual-studio-code, zoom, slack)
   • Choose All Devices and click Create Brew policy
6. Click New Brew Policy → Automatic Upgrades and Uninstalls
   • Enable Automatically upgrade Vulnerable Formulae when detected
   • Enable Automatically uninstall forbidden packages
   • Choose All Devices and click Create Brew policy

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

Workbrew’s Brew Commands feature enables you to manage software remotely, executing brew commands across multiple workspace devices from the Console.

• 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 'Run' buttons throughout the Console to pre-fill a Brew Command to run immediately
• Run new commands immediately after creation or scheduled for a specific date and time

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

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 Brew Commands in the sidebar and click New Brew command
3. Add brew upgrade --cask visual-studio-code as an argument
4. From the Run on Devices dropdown 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

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

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

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

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

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 specifc 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