Remote Management
Guide

Decommission a Device or move it to another Workspace

Petros Amoiridis

Use this guide to remove a Device from a Workspace, or to move a Device from one Workspace to another. The Workbrew Console has no direct "move" action, so moving is a decommission followed by a fresh enrollment in the destination Workspace.

Prerequisites

  • Write access in the source Workspace
  • For a move, write access in the destination Workspace as well
  • Terminal access with sudo on the Device

Decommission a Device

  1. Run the uninstall command on the Device: sudo /opt/workbrew/sbin/uninstall. This removes /opt/workbrew, including the Device-specific API key, leaving a clean slate.

    The uninstall command must run as root, and it gives ownership of the Homebrew installation to the user named in the SUDO_USER environment variable. When you run it with sudo, that is the account you ran sudo from. An MDM script that runs as root has no SUDO_USER, so the uninstall command stops before removing anything and prints Error: Workbrew Uninstaller must have SUDO_USER variable set!. First set SUDO_USER to the account of the person who uses Homebrew on the Device. It cannot be workbrew.

    export SUDO_USER=<username>
/opt/workbrew/sbin/uninstall

    If you are an admin running the command for someone else, run the same two lines from a root shell (sudo -s). Otherwise Homebrew ends up owned by your account instead of theirs.

  2. In the Console, go to the Devices page and click the Device.

  3. At the bottom of the Device details page, click Remove Device from Workbrew Console.

Once the Device record is removed, the Device-specific API key is invalidated and the Device can no longer check in to that Workspace.

What is removed

Removing a Device from the Console deletes:

  • All command run history for the Device
  • Device Group memberships
  • Installed formulae, casks, and package inventory tracked for the Device
  • Pending package requests
  • The Device-specific API key

The Workspace API key is unaffected.

Revoking Workspace access (when applicable)

Most people who use Workbrew-managed Devices do not have a Workbrew Console account. Typically only admins do. If the person who used this Device was also a Workbrew Console User and should no longer have access to this Workspace, remove them from Settings > Users. That removes them from this Workspace only, not from Workbrew entirely.

This is separate from decommissioning the Device. If the person did not have a Console account, there is nothing to remove here.

Move a Device from one Workspace to another

Moving a Device is a two-part operation: decommission in the source Workspace, then enroll in the destination Workspace using its install script. History tracked in the source Workspace (command runs, Device Group memberships, inventory) is left behind and does not transfer.

  1. Follow the Decommission a Device steps above in the source Workspace.

  2. In the destination Workspace, get the install script (for manual installs) or the pre-install script (for MDM deployments). Either way the script must come from the destination Workspace, since the API key is Workspace-specific. See How to manually install Workbrew on a Device for the manual flow, or the deployment guides for MDM-specific instructions.

  3. Install Workbrew on the Device using your chosen flow. Within 15 minutes the Device checks in and appears on the Devices page of the destination Workspace.

The Device re-enters the destination Workspace as a new record. Apply Device Group memberships, Policies, and Default Packages in the destination Workspace as needed.

Workspace vs Device API keys

Each Workspace has its own API key that an install script uses to enroll a Device. On first check-in, the Device is issued its own Device-specific API key. Decommissioning a Device invalidates its Device-specific key but does not change the Workspace API key.

You can reset a Workspace API key in the Console.