Contents x
    macOS Agent Installation
      • Print
      • Dark
        Light
      • PDF
      Contents

      macOS Agent Installation

        • Print
        • Dark
          Light
        • PDF
        Article summary

        This article covers how to install the ControlUp for Desktops Agent onto macOS devices.

        Important
        Before you deploy any Agents, read the prerequisites for Agent deployment and make sure that your environment is ready.

        The following macOS versions are supported on Intel x64 or Apple Silicon (M1+)

        macOS versionMinimum Agent versionRecommended Agent version
        12.x (Monterey)2.82.15 (2.16 can run on Monterey but does not support Remote Control)
        13.x (Ventura)2.8Latest GA version
        14.x (Sonoma)2.8Latest GA version
        15.x (Sequoia)2.16Latest GA version

        Download the Agent Manager

        To install the macOS Agent, you download and install the Agent Manager. The Agent Manager installs the Agent and updates it according to your version control settings. 

        To download the macOS Agent Manager:

        1. Go to Configuration > Downloads.
        2. Select macOS Agent.
        3. Click Download.

        JAMF deployment

        Read our ControlUp for Desktops JAMF deployment article for details.

        Command line installation

        To install the macOS Agent Manager from the command line, follow the steps on the Downloads page. The commands are ready for you to copy and already include your unique tenant URL and device registration code.

        Proxy server configuration

        The macOS Agent uses the proxy server configured in your macOS settings.

        Manual GUI installation

        To install the Agent Manager manually, run the downloaded file. You'll need to enter your tenant URL and device registration code, which you can copy from the Agent Downloads page.

        User prompts for data collection

        Note
        This section describes using Extended Settings to control user prompts and data collection. You can target these settings to certain devices using groups and tags. Read Extended Settings for details.

        When the macOS Agent is installed on a device, the Agent requires permission to access certain data on the device. By default, the end user receives multiple prompts to grant these permissions to the Agent. This section describes the required permissions and user prompts, and how you can control data collection and user prompts for the relevant features.

        Network filter

        The end user is prompted to install and use a network filter. The network filter is used for Agent data collection from Microsoft Teams for UC&C monitoring, and collecting network bytes used per process.

        • If you want to use an MDM solution to grant these permissions, you can enable the setting Mac only: Prevent network filter user prompt to block the user prompts. You can then configure an MDM policy to allow the Agent to install and use the network filter.
        • If you don't want to use these features, you can enable the setting Mac only: prevent network filtering. This setting prevents data collection from a network filter (even if configured with an MDM policy) and also prevents relevant user prompts.

        Remote Control/Shadow

        The end user is prompted to give the Agent permission to view the screen and control the device for Remote Control/Shadow. 

        For more information about the required permissions for Remote Control, see How to Allow Remote Control on macOS.

        Location Services

        The end user is prompted to give the Agent permission to access location data from Location Services. Learn more about device geolocation.

        • If you want to use an MDM solution to grant this permission, you can enable the setting Mac only: prevent location user prompt to block the user prompt. You can then configure an MDM policy to allow the Agent to collect the location data.
        • If you don't want to collect location data from Location Services, you can enable the setting Disable device location. This setting prevents the user prompt for location data.

        Active URL collection

        The end user is prompted to give the Agent permission to get data from Chrome and Safari to collect active URLs for End User Activity monitoring.

        Uninstall the Agent with a script

        To perform a scripted uninstall of the Agent for macOS, run this command as root:

        /usr/local/com.controlup.edgedx.agent/Bin/AgentAssist --uninstall

        Troubleshooting

        If you have performed the steps above to install the Agent Manager, but you don't see the device in the ControlUp, perform these troubleshooting steps:

        1.  Check if the Agent Manager is installed by running `ls -lap /usr/local/com.controlup.edgedx.agentmanager`. If it returns "No such file or directory", this means the Agent Manager isn't installed correctly.

        2.  Check if your tenant information was entered correctly by running `sudo cat /usr/local/com.controlup.edgedx/TenantInfo.json`. Make sure that the tenant name and device registration code is correct for your organization. If no information is returned, then the Agent Manager isn't installed correctly.

        3.  Check if the Agent is installed by running `ls -lap /usr/local/com.controlup.edgedx.agent`. If it returns "No such file or directory", check the log files (/usr/local/com.controlup.edgedx.agent/Bin/AgentAssist logs).

        4.  Check if the Agent is running by running `pgrep -a CoreAgent`. If it returns a number, check the log files (/usr/local/com.controlup.edgedx.agent/Bin/AgentAssist logs).

        5.  Make sure you meet all the networking requirements so that the Agent can communicate with your tenant.

        If you still need help, contact ControlUp Support!

        Was this article helpful?
        What's Next