--- title: Install Workstation Agent on macOS description: Install the Workstation Agent for OpenLM Platform on macOS, on one Mac or across a fleet with MDM, connect it, and grant its privacy permissions. product: OpenLM Platform --- To collect application usage from Macs, install the Workstation Agent on each Mac and connect it to OpenLM Platform with its authorization file. You can install the package on one Mac, or push it across a fleet with your MDM. The Workstation Agent runs on macOS 10.15 (Catalina) or higher, on both Intel (x86_64) and Apple Silicon (arm64) Macs. The agent is a self-contained binary, so you don't install a separate .NET runtime. :::warning[Remove the quarantine attribute first] The Workstation Agent for macOS is not notarized by Apple, so Gatekeeper blocks the downloaded installer. After you download the installer, remove the quarantine attribute before you open it, as described in step 2 of Install on a single Mac. ::: ## Before you begin Confirm these prerequisites: - The Mac runs macOS 10.15 (Catalina) or higher, and meets the [system requirements](https://www.openlm.com/documentation/cloud/deployment-operations/system-requirements/?component=workstation-agent). - You have administrator (`sudo`) rights. The installer writes to `/Library/OpenLMAgent/`. - The Mac has outbound access to your OpenLM Platform address on the Agents Hub port (default `443`, SSL turned on). The agent connects over a WebSocket. - You have the authorization file for the agent. Generate it for a client of type **Agent** in **Identity**, as described in [Authorize components](https://www.openlm.com/documentation/cloud/getting-started/authorize-components). Identity names the file `agent-authorization.json`. ## Install on a single Mac To install the Workstation Agent on one Mac: 1. Download the macOS Workstation Agent from the [Downloads page](https://www.openlm.com/downloads/). Select the build that matches the processor of the Mac: Intel (x86_64) or Apple Silicon (arm64). 2. Remove the quarantine attribute from the downloaded installer, so that Gatekeeper doesn't block it: ```bash xattr -d com.apple.quarantine ``` Replace `` with the package you downloaded, for example `~/Downloads/.pkg`. Repeat this step on every machine where you install from a browser download. 3. Open the package (`.pkg`) and follow the macOS Installer prompts. 4. Copy your authorization file over the placeholder the package installs, `/Library/OpenLMAgent/agent-authorization.json`. 5. Restart the agent, as described in [Connect the agent](#connect-the-agent). 6. Check the agent, as described in [Check the agent](#check-the-agent). The installer copies files to `/Library/OpenLMAgent/`, signs the binary, and registers a LaunchAgent that starts the agent automatically when a user signs in. The installer opens on its welcome pane. *The macOS Installer welcome pane.* At the end, the installer confirms a successful installation. *The installer confirms a successful installation.* ## Install across a fleet with MDM Push the package through your MDM and run the macOS installer command in the root context: ```bash sudo installer -pkg .pkg -target / ``` Replace `` with the name of the package. The package identifier is `com.openlm.agent`. The installation runs without an interface, and the bundled scripts handle signing, permissions, configuration backup on upgrade, and LaunchAgent activation. Some MDM platforms require a signed and notarized package for unattended installation. Because the build is ad-hoc signed and not notarized, validate it against your MDM's Gatekeeper policy before a fleet rollout. ## Connect the agent The agent reads its authorization file from `/Library/OpenLMAgent/agent-authorization.json`, and its configuration from `/Library/OpenLMAgent/settings.json`. For OpenLM Platform in the cloud, the authorization file also gives the agent the address to connect to. For a self-hosted OpenLM Platform, set the server address under `agentsHub` in `settings.json`: ```json { "agentsHub": { "address": "", "port": 443, "useSSL": true } } ``` Replace `` with the host of your self-hosted OpenLM Platform. After you edit `settings.json` or replace the authorization file, restart the agent so the change takes effect: ```bash launchctl kickstart -k "gui/$(id -u)/com.openlm.agent" ``` On upgrade, the installer preserves `settings.json` and `agent-authorization.json`, so your configuration survives package updates. These optional settings are common: - `process.trackingMs`: process monitoring interval in milliseconds (default `30000`). - `webmonitor.useWebMonitor`: turn on browser activity monitoring (default `true`). - `process.autoPromptScreenRecording`: prompt for the Screen Recording permission at start (default `false`). - `logging.minimumLevel`: log verbosity, for example `Information` or `Debug` (default `Information`). ## Grant the required permissions The agent needs two macOS privacy permissions. Grant them so data collection works: - **Screen Recording**: required to track window titles. Open **System Settings**, select **Privacy & Security**, then **Screen Recording**, and turn on **OpenLM Workstation Agent**. Restart the agent afterward. - **Full Disk Access**: required to read Safari browsing history. Open **System Settings**, select **Privacy & Security**, then **Full Disk Access**, and turn on the `OpenLM.Agent.macOS` binary. Without it, Safari history collection fails silently. Other browsers are unaffected. The agent is turned on in the Screen Recording list. *The agent turned on for Screen Recording.* The agent is turned on in the Full Disk Access list. *The agent turned on for Full Disk Access.* For fleet machines, you can pre-approve these permissions with a PPPC (Privacy Preferences Policy Control) configuration profile pushed through MDM. Because the build is ad-hoc signed, a PPPC profile might not reliably pre-approve the agent, and users might still be prompted. Plan for a one-time manual grant per machine as the reliable path. ## Check the agent Confirm the agent process is running: ```bash launchctl print "gui/$(id -u)/com.openlm.agent" pgrep -x "OpenLM.Agent.macOS" ``` A `running` state and a non-empty `pgrep` result confirm the agent runs. Confirm the agent reports to OpenLM Platform: - In **Agent Activity**, select the **Refresh** icon, and confirm the workstation appears as online. - If monitored applications are running, confirm sessions appear in **Process Manager**, then **Active Processes**. Check the per-user logs for a successful connection and no permission warnings: ```bash tail -n 100 /Library/OpenLMAgent/logs/$(whoami)/ ``` ## Open the Personal Dashboard Users open their [Personal Dashboard](https://www.openlm.com/documentation/cloud/users/personal-dashboard/) from the Workstation Agent. The package copies the **OpenLM Agent** app into the **Applications** folder. To open the dashboard, open **OpenLM Agent**, for example from Launchpad or Spotlight. The dashboard opens in the default browser. Users sign in with their account in Identity, as described in the [prerequisites of the Personal Dashboard](https://www.openlm.com/documentation/cloud/users/personal-dashboard/#before-you-begin). If the dashboard doesn't open, see [Why doesn't the Personal Dashboard open?](https://www.openlm.com/documentation/cloud/getting-started/install-workstation-agent/troubleshooting#why-doesnt-the-personal-dashboard-open) ## Uninstall the agent Run the bundled uninstaller with administrator rights: ```bash sudo sh /Library/OpenLMAgent/uninstall.sh ``` The uninstaller stops the agent, removes the LaunchAgent and the `/Applications/OpenLM Agent.app` copy, and deletes `/Library/OpenLMAgent/`, including logs. The uninstaller does not reset the privacy permissions you granted. To remove them, run: ```bash tccutil reset ScreenCapture com.openlm.agent tccutil reset SystemPolicyAllFiles com.openlm.agent ``` ## Known limitations The macOS build has these limitations: - The macOS build is ad-hoc signed and not notarized. Gatekeeper can warn on a browser-downloaded installer, and a PPPC profile might not reliably pre-approve permissions. Plan for manual permission grants. - Safari history collection requires Full Disk Access. Without it, Safari history is skipped silently. Other browsers are unaffected. - The agent installs as a LaunchAgent, so it runs only while a user is signed in. This is by design: it needs the user's GUI session to track window titles and per-user browser history. - Uninstalling does not reset the privacy permissions. Reset them manually if needed. If the agent doesn't start, appear in Agent Activity, or collect window titles or Safari history, see [Troubleshoot Workstation Agent](https://www.openlm.com/documentation/cloud/getting-started/install-workstation-agent/troubleshooting#why-doesnt-the-agent-start-on-macos). :::info[Next step] The agent reports the applications that OpenLM Platform asks it to monitor. To select them, open **Navigation**, select **Agents**, then **Process Manager**, and add the processes of your licensed applications, as described in [Process Manager](https://www.openlm.com/documentation/cloud/automations/process-manager/). After that, continue the setup with [Install the Directory Synchronization Agent (DSA)](https://www.openlm.com/documentation/cloud/getting-started/install-dsa) to synchronize user and group data from your directories. :::