Skip to main content

Celonis Product Documentation

Installing on-prem clients on Linux

This guide provides step-by-step instructions on how to set up the Celonis on-prem clients on Linux. The installation process consists of three stages which are performed by a Celonis Platform user with Admin rights, and an IT admin interchangeably.

Before you begin

Make sure your system meets hardware and software requirements for clients. See System requirements.

If you’re an Celonis Platform user follow these steps to prepare the installation package which you can later send to your IT admin so that they can install it on a central server.

Before you begin:

You need to have admin rights to prepare the installation package.


  1. In your Celonis Platform instance, go to Admin & Settings > On-prem clients.

  2. In the upper-right corner, click Set up on-prem clients.

  3. Select Install the clients on a central server.

  4. Enter a unique installation package name.

  5. Select the operating system on which you want to install the clients.

  6. 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 3. Verifying the installation.

If you’re an IT admin and you received an installation request from your Celonis Platform users, follow these steps.


  1. Using the link from the email you received from the Celonis Platform user, download the installation package.

  2. Extract the installation package to the location where you want to install the clients.

  3. In the extracted folder, go to the Shared folder and start OPC-Management-Tool.


    The -c flag removes all attributes, and -r applies recursively to the entire targeted .app directory contents.


    We also provide a CLI version of this tool

    In Terminal, run:

  4. (optional) In the Management Tool, generate the encryption key to encrypt sensitive data in the installation package:

    1. Click Generate encryption key.


      We use 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.

  5. (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.

  6. Click Connect to Celonis Platform to generate the Verification URL.

  7. Copy the Verification URL and share it with your Celonis Platform user.

  8. (Optional) Connect to SAP. This step is only required when automating in SAP.

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.


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


  1. Go to the Verification URL sent by the IT admin.

  2. Log in to Celonis Platform.

  3. Verify the request and click Authorize.

    On-prem clients can now connect to Celonis Platform and create own AppKeys. Newly created clients will also now be visible in the On-prem clients overview page under Admin & Settings > On-prem clients.

To establish a connection between Celonis Platform and SAP, you must download the SAP Java Connector (SAP JCo) library and place it in your local directory. SAP Jco allows applications to communicate with SAP systems using SAP's RFC protocol.

  1. Download the respective package from the SAP Marketplace.


    Only SAP Service User (S User) can download software from SAP portals. Usually, a customer's SAP BASIS has this access.

    The downloaded SAP Jco folder already contains two files: a Java part “sapjco3.jar”, and an operating system-specific part e.g. sapjco3.[.dll | .so | .sl ].

  2. Copy the Library files directly into the external folder located at {installation_folder}/shared/libraries/external

    The Celonis Agent is configured to read the library from this directory.


    After setting up the SAP Jco, the Windows Service Celonis Agent needs to be restarted for the SAP Jco-related changes to take effect.

  3. Restart the Celonis Automation client:

    1. On Windows, go to the On-prem Client Management Tool.