Installing on-prem clients on MacOS

Installing the On-Premise Client (OPC) on macOS establishes a high-performance, secure data pipeline between your local infrastructure and the Celonis Platform. This connection enables continuous, real-time data extraction and process automation directly behind your corporate firewall, allowing Celonis to surface and eliminate hidden execution gaps within your source systems.

Execute these steps to deploy the client package and establish your local data pipeline.

Before you begin

Ensure you have the following prerequisites before starting the installation:

An active SAP Service User (S-user) account with software download permissions (typically managed by your organization's SAP BASIS team).
The unique installation link provided in your Celonis Platform deployment invitation.
Make sure your system meets hardware and software requirements for clients. See System requirements.

Step 1: Preparing the installation package

In your Celonis Platform instance, go to Admin & Settings > On-prem clients.
In the upper-right corner, click Set up on-prem clients.
Select Install the clients on a central server.
Enter a unique installation package name.
Select the operating system on which you want to install the clients.
Enter your IT admin email address and click Send.

Your IT admin will receive a link where they can download the package prepared based on the settings you selected. They will also receive detailed instructions on how to install the package on the server. Once they completed the installation, you’ll receive a verification URL or code to verify the connection with the Celonis Platform. If you already received that, jump straight to Step 3: Verifying the installation.

Step 2: Installing on-prem clients (IT Admin task)

Click the download link provided in your Celonis deployment invitation to save the installation package to your local environment.
Extract the installation package into a designated subdirectory within your macOS home directory. For example, to isolate the data pipeline for an Accounts Payable optimization project, extract the archive to your local environment path: ~/celonis/pipelines/accounts-payable/
Optional: Establish an SAP Connection.
Download the SAP Java Connector (SAP JCo) library, version 3.1 or later, to your local directory. The Celonis Agent requires this library to execute Remote Function Calls (RFC) against your target SAP instances.
1. Download the respective package from the SAP Support Portal.
  The downloaded SAP JCo folder contains two required library files: the Java component sapjco3.jar and the operating system-specific binary component.
2. Copy the contents of the SAP JCo folder directly into your assigned agent library paths. For instance, to establish an active link for an Order-to-Cash process tracking project, copy the files into the following destination paths:
  - For Automation Agent
    ~/celonis/pipelines/order-to-cash/automation-agent/libraries/external/
  - For Extraction Agent
    ~/celonis/pipelines/order-to-cash/extraction-agent/libraries/external/
Navigate to the Shared application directory in Terminal. To clear security attributes for your Order-to-Cash pipeline manager and prevent macOS Gatekeeper execution blocks, run the following recursive command:
```
cd ~/celonis/pipelines/order-to-cash/Shared && xattr -cr opc-management-tool.app
```
Note
The -c flag removes all attributes, and -r applies recursively to the entire targeted .app directory contents.
Launch the interactive client manager from your terminal interface. For headless server environments or automated execution, launch the client manager using the Command Line Interface (CLI).
Tip
To initialize the setup configuration for a Procurement process stream using the headless execution pathway, run the binary directly:
```
./opc-management-tool.app/Contents/MacOS/opc-management-tool cli
```
In the Management Tool, select the clients you want to install.
(optional) In the Management Tool, generate the encryption key to encrypt sensitive data in the installation package:
1. Click Generate encryption key.
  Tip
  We use java.security and javax.crypto fameworks to store and encrypt sensitive data in the application.yml file.
2. Define a passphrase which will be used to create the hash for the private encryption key.
3. Click Save.
  This will automatically create the celonis-kms.yml file and encrypt all sensitive data like the application key and the proxy password.
(optional) If necessary, define the proxy server between the on-prem client and the source system or between the on-prem client and the Celonis Platform:
1. Click Use proxy for communication.
2. Define the properties of your proxy connection:
  - protocol: HTTP or HTTPS
  - host: the IP address or hostname of the proxy server
  - port: the port at which the server can be reached
  - user (optional): the user name for basic authentication with the proxy
  - password (optional): password for basic authentication with the proxy
3. Click Save.
  This will automatically ensure that your connection will use the proxy for communication.
Click Connect to Celonis Platform to generate the Verification URL.
Copy the Verification URL and share it with your Celonis Platform user.
(Optional) Connect to SAP. This step is only required when automating in SAP.

Step 3: Verifying the installation

If you’re a Celonis Platform user and you received a request to verify the on-prem client installation from your IT admin, follow these steps.

Important

To verify the on-prem clients' installation, you must be Celonis Platform admin or you must have "edit agent" permissions assigned to your role.

Go to the Verification URL sent by the IT admin.
Log in to Celonis Platform.
Verify the request and click Authorize.
On-prem clients can now connect to Celonis Platform and create their own OAuth client. Newly created clients will also now be visible in the On-prem clients overview page under Admin & Settings > On-prem clients.
Note
In July 2025, Celonis Platform replaced appkeys with OAuth 2.0 as a method of authentication for OPC. For details, see AUTOMATION OAuth for on-prem clients (2025-08-13).
If you're having trouble connecting the on-prem clients to Celonis Platform, see Manual authentication.