Install and configure OpenLM Components

This document explains how to install and configure external OpenLM components. Select the appropriate tab for detailed instructions.

Broker

Install and configure OpenLM Broker

Follow these steps to install and configure OpenLM Broker: For Linux distributions (tar.gz archive, DEB and RPM packages, systemd and non-systemd systems), follow the single canonical procedure: Install Broker → Install on Linux/Unix. It also covers configuration with detect.sh and upgrades.

Windows Installation

1. Download the latest version of OpenLM Broker from the OpenLM website.
2. Run the installer and follow the installation wizard.
3. Open OpenLM Broker Configuration Tool.
4. Add your license servers by selecting Add Server.
5. Configure connection settings and authentication details.
6. Select Check Connectivity to verify connection.
7. Select Apply to save changes.

Workstation Agent

Install and configure Workstation Agent

To install and configure the Workstation Agent:

Windows Installation

1. Download the Workstation Agent installer from the OpenLM downloads page.
2. Run the installer and follow the prompts.
3. Launch the Workstation Agent application.
4. Enter your organization-specific credentials provided by your OpenLM administrator.
5. Select Test Connection to confirm connectivity.
6. Select Save to apply the settings.

Linux Distributions

tar.gz

1. Download the tar.gz package.
2. Extract the package using the command: tar -xzf openlm-workstation-agent.tar.gz.
3. Navigate to the extracted directory.
4. Run the installation script: ./install.sh.
5. Follow the on-screen instructions to complete the installation.

RPM

1. Download the RPM package.
2. Install the package using the command: sudo rpm -ivh openlm-workstation-agent.rpm.
3. Follow the on-screen instructions to complete the installation.

DEB

1. Download the DEB package.
2. Install the package using the command: sudo dpkg -i openlm-workstation-agent.deb.
3. If there are dependency issues, run: sudo apt-get install -f.
4. Follow the on-screen instructions to complete the installation.

Install on macOS

OpenLM Workstation Agent runs on macOS 10.15 (Catalina) and later, 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.

Remove the quarantine attribute first

OpenLM Workstation Agent for macOS is not yet notarized by Apple, so Gatekeeper blocks the downloaded installer. After you download the installer, remove the quarantine attribute before you open it:

xattr -d com.apple.quarantine <file>

Replace <file> with the file you downloaded, for example ~/Downloads/OpenLMAgent.pkg. Until the agent is notarized, repeat this step on every machine where you install from a browser download.

Before you begin

Confirm these prerequisites:

• The Mac runs macOS 10.15 (Catalina) or later.
• You have administrator (sudo) rights. The installer writes to /Library/OpenLMAgent/.
• The Mac has outbound access to your OpenLM server host on the Agents Hub port (default 443, SSL enabled). The agent connects over a WebSocket.
• You have the authorization file for the agent, retrieved from OpenLM Identity.

Install on a single Mac

1. Download the macOS Workstation Agent from the OpenLM downloads page. Choose the build that matches the Mac's processor — Intel (x86_64) or Apple Silicon (arm64).
2. Remove the quarantine attribute from the downloaded installer, as described in the previous warning.
3. Install the agent with one of these methods:
   • Package (.pkg): Double-click the package and follow the macOS Installer prompts.
   • Shell installer: From the folder that contains the unpacked files, run sudo sh install.sh.
4. Configure the agent to point at your server, as described in Configure the agent.
5. Verify the connection, as described in Verify the installation.

The installer copies files to /Library/OpenLMAgent/, signs the binary, and registers a LaunchAgent that starts the agent automatically when a user logs in.

The macOS Installer welcome pane.

The installer confirms a successful installation.

Install across a fleet with MDM

Push OpenLMAgent.pkg through your MDM and run the macOS installer command in the root context:

sudo installer -pkg OpenLMAgent.pkg -target /

The package identifier is com.openlm.agent. The install runs with no 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 current build is ad-hoc signed and not notarized, validate it against your MDM's Gatekeeper policy before a fleet rollout.

Configure the agent

The agent reads its configuration from /Library/OpenLMAgent/settings.json. The one required field is the server address under agentsHub:

{
  "agentsHub": {
    "address": "<your-openlm-server-host>",
    "port": 443,
    "useSSL": true
  }
}

After you edit settings.json, restart the agent so the change takes effect:

launchctl bootout "gui/$(id -u)/com.openlm.agent"
launchctl bootstrap "gui/$(id -u)" /Library/LaunchAgents/com.openlm.agent.plist

On upgrade, the installer preserves settings.json and agent-authorization.json, so your configuration survives package updates.

Common optional settings:

• process.trackingMs — process monitoring interval in milliseconds (default 30000).
• webmonitor.useWebMonitor — enable 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

macOS gates two capabilities the agent uses behind privacy controls. Grant them so data collection works:

• Screen Recording — required to track window titles. Open System Settings, go to Privacy & Security → Screen Recording, and enable OpenLM Workstation Agent. Restart the agent afterward.
• Full Disk Access — required to read Safari browsing history. Open System Settings, go to Privacy & Security → Full Disk Access, and enable the OpenLM.Agent.macOS binary. Without it, Safari history collection fails silently. Other browsers are unaffected.

The agent enabled for Screen Recording.

The agent enabled 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 current build is ad-hoc signed, a PPPC profile might not reliably pre-approve the agent, and users might still be prompted. Until the agent ships with an Apple Developer ID, plan for a one-time manual grant per machine as the reliable path.

Verify the installation

Confirm the agent process is running:

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 is up.

Confirm the agent reports to OpenLM:

• In Agents Activity Manager → Agents, confirm the workstation appears as online.
• If monitored applications are running, confirm sessions appear in Process Manager → Active Sessions.

Check the per-user logs for a successful connection and no permission warnings:

tail -n 100 /Library/OpenLMAgent/logs/$(whoami)/<latest-log-file>

Troubleshooting

The agent does not start after installation. Confirm the LaunchAgent is registered, then reload it in the user context (not as root):

launchctl bootout "gui/$(id -u)/com.openlm.agent" 2>/dev/null
launchctl bootstrap "gui/$(id -u)" /Library/LaunchAgents/com.openlm.agent.plist

Confirm the quarantine attribute is cleared — this command returns nothing when it is:

xattr -p com.apple.quarantine /Library/OpenLMAgent/OpenLM.Agent.macOS

If it is still set, run sudo xattr -rd com.apple.quarantine /Library/OpenLMAgent. Also confirm you installed the build that matches the Mac's processor.

The agent runs but does not appear in Agents Hub. Verify agentsHub.address and port in settings.json, confirm useSSL matches the server, and test outbound reachability to the server host and port. A firewall or proxy can block the WebSocket connection.

Window titles are empty, or the Screen Recording prompt repeats. Grant the Screen Recording permission, then restart the agent. A repeating prompt usually means the recorded permission identity is unstable, which is related to ad-hoc signing. Grant the permission once per machine and avoid re-signing the binary.

Safari history is not collected. Grant Full Disk Access to OpenLM.Agent.macOS, and confirm webmonitor.useWebMonitor is true.

To diagnose other issues, set logging.minimumLevel to Debug in settings.json, restart the agent, and re-check the logs.

Uninstall the agent

Run the bundled uninstaller with administrator rights:

sudo sh uninstall.sh

It stops the agent, removes the LaunchAgent, and deletes /Library/OpenLMAgent/, including logs.

The uninstaller does not reset the privacy permissions you granted. To remove them, run:

tccutil reset ScreenCapture com.openlm.agent
tccutil reset SystemPolicyAllFiles com.openlm.agent

Known 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 logged 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.

Directory Synchronization Agent (DSA)

Install and configure Directory Synchronization Agent (DSA)

To install and configure DSA:

1. Download the DSA installer from the OpenLM downloads page.
2. Run the installer.
3. Launch the DSA application.
4. Enter the URL of your Directory Synchronization Service (DSS).
5. Add sync definitions from DSS.
6. Configure access:
   • For local directories (LDAP), ensure network access to the directory.
   • For cloud directories (Azure AD, Google), ensure external access to those directories.
7. Select Test Connection to validate.
8. Select Save.

AI Proxy

Install and configure AI Proxy

AI Proxy is deployed as a Docker Compose stack in your network, not through a desktop installer. Follow the dedicated guide:

1. AI Proxy overview — what it does and how it fits OpenLM Platform.
2. Deploy AI Proxy — run the Docker Compose stack in your network.
3. Configure AI Proxy — connect to OpenLM Platform, set up providers, and route clients.