On-Premise Agent Installation Guide

On-Premise Agent Installation Guide

Overview

The OneEnterprise On-Premise Agent is a lightweight Windows service that enables secure communication between your on-premises systems and the OneEnterprise cloud platform. Once installed, the agent acts as a bridge — allowing OneEnterprise flows to access internal databases, file shares, APIs, and services that are not directly reachable from the internet.
This guide walks system administrators through downloading, installing, and configuring the OneEnterprise On-Premise Agent, as well as optional post-installation steps and the uninstall process.
Warning
Administrator privileges are required to install the OneEnterprise On-Premise Agent. Contact your IT team if you do not have local administrator rights on the target machine.

Key Features
  1. Guided Setup Wizard: A step-by-step installer walks administrators through language selection, installation path, and OE Proxy configuration.
  2. OE Proxy Authentication: The agent uses an administrator-provided key to authenticate and connect securely to the OneEnterprise network. 
  3. System Tray Management: Administrators start, stop, and manage the service directly from the Windows system tray without opening system settings.
  4. Optional Desktop Shortcut: Provides quick access to the agent after installation.
  5. Clean Uninstall: A dedicated uninstall wizard removes the agent with a prerequisite check to prevent data loss.

Prerequisites

Before you begin the installation, ensure that the target machine meets the functional and software requirements listed below. Attempting installation on an unsupported system may result in service failures or connectivity issues.

Functional Requirements

The following conditions must be met for the OneEnterprise On-Premise Agent to operate correctly:

Requirement

Details

Administrator access

The installer must be run with local administrator privileges. Without elevation, the service cannot register with Windows or write to the required directories.

Network connectivity

The host machine must have outbound internet access on port 443 (HTTPS) to communicate with the OneEnterprise cloud platform.

License key

A valid license key must be obtained from your OneEnterprise administrator before installation. The key is entered during setup and cannot be changed after installation without reinstalling.

Dedicated service account

For production deployments, it is recommended to run the agent under a dedicated Windows service account with least privilege access.

Firewall rules

Ensure that your corporate firewall or proxy permits outbound connections to *.oneenterprise.com on port 443.

Unique installation

Only one instance of the OneEnterprise On-Premise Agent may be installed per host machine. Installing multiple instances on the same machine is not supported.


Software Requirements

Verify that the target machine meets the minimum software specifications below before running the installer:

Component

Minimum requirement

Operating system

Windows 10 (64-bit) or Windows Server 2016 / 2019 / 2022

.NET Framework

.NET Framework 4.7.2 or later (included with Windows 10 v1803+; download separately for Windows Server)

Disk space

Minimum 500 MB of free disk space on the installation drive

RAM

Minimum 2 GB RAM available; 4 GB recommended for production workloads

CPU

Dual-core processor, 2 GHz or faster

Internet browser

Microsoft Edge, Google Chrome, or Firefox (for portal access only; not required on the agent host)

Windows Installer

Windows Installer 4.5 or later (pre-installed on all supported Windows versions)

Info
If your machine does not have .NET Framework 4.7.2 installed, download it from the Microsoft Download Center before proceeding. The installer will display an error if the required runtime is missing.

Installation steps

Follow the steps below in order. Do not close the installer wizard at any point during the installation — doing so may leave the service in an incomplete state and require a manual cleanup before reinstalling.

Step 1 – Download the Installer

  1. Obtain the OneEnterprise On-Premise Agent installer from your OneEnterprise tenant or from your administrator.
  2. Sign in to your tenant and navigate to Home > On-Premise Agent.
  3. Click on the Download Agent option, next to the Add button.

  1. Upon clicking the Download Agent, the Download Agent screen will appear.
  2. The screen provides a platform-specific installer for installing the OneEnterprise On-Premise Agent. Based on your operating system, you can download the installer for the OneEnterprise On-Premise Agent. 
  3. Click the Download button provided for every operating system.


  1. Once you click Download, the download will start.
  2. The installer file will be saved to your default downloads folder.

  1. Go to the Download folder and verify the installer name: it is OneEnterpriseOnPremiseAgent.exe.

Warning
Always download the installer directly from your OneEnterprise tenant. Do not use copies shared via email or file shares, as these may not be the latest version.

Step 2 – Run the Installer as Administrator

  1. Elevation to administrator is required. Standard user permissions are insufficient to register the Windows service.
  2. Locate the downloaded installer file (OneEnterpriseOnPremiseAgent.exe) in your downloads folder.
  3. Right-click the file to open the context menu.
  4. Select Run as administrator from the menu.
  5. If a User Account Control (UAC) prompt appears, click Yes to allow the installation to proceed.


Idea
If Run as administrator is not visible in the context menu, your account may not have the rights to elevate. Contact your system administrator to run the installer on your behalf.

Step 3 – Select the Installer Language

  1. The setup wizard opens with the Application Language screen. The language label appears in five languages — English, German, French, Spanish, and Portuguese — ensuring accessibility for administrators in different locales.
  2. Review the Language dropdown. The default selection is English. Select a different language if you want the wizard to display in another language.
  3. Select your preferred language from the list.
  4. Click Next to continue to the next step.

Step 4 – Select the Installation Folder

  1. Choose the directory where the OneEnterprise On-Premise Agent will be installed. The default path is recommended for most deployments.
  2. The folder selection screen allows you to specify a custom installation path:
    1. The default installation path is C:\Program Files\OneEnterpriseOnPremiseAgent. However, you may modify the installation path. 
    2. To use the default path, click Next to proceed.
    3. To install to a different location, click Browse and navigate to the desired folder.
    4. Ensure the selected drive has at least 500 MB of free space before proceeding.
  3. Click Next to continue.

Idea
Installing to a non-default path is supported but may require additional configuration for service accounts and permissions. The default path is recommended for standard deployments.

Step 5 – Enter the License Key

  1. The license key activates the agent and links it to your OneEnterprise account. Obtain this key from your OneEnterprise administrator.
  2. On the license key screen:
    1. Copy the license key provided by your OneEnterprise administrator.
    2. Paste the key into the License Key field. Ensure there are no leading or trailing spaces.
    3. Click Next to validate the key and proceed.
    4. If the key is invalid or has expired, the installer displays an error message. Contact your administrator to obtain a valid key.

Warning
License keys are unique to each installation environment. Do not reuse a key across multiple machines unless your OneEnterprise plan explicitly allows multi-instance licensing.

Step 6 – Wait for the Installation to Complete

  1. The installer copies the agent files, registers the Windows service, and configures the startup settings. This process typically takes one to three minutes.
  2. During this phase:
    1. The progress bar shows the installation percentage. Do not close the wizard while the progress bar is running.
    2. The installer registers the OneEnterprise On-Premise Agent service with Windows Service Manager.
    3. Required directories, configuration files, and log folders are created automatically.
    4. The agent service is set to start automatically when Windows starts.

Step 7 – Complete the Installation and Launch the Agent

  1. Once all files are installed, the wizard displays a completion screen. You can choose to launch the agent immediately.
  2. On the completion screen:
    1. Review the summary to confirm that the installation has been completed without errors.
    2. Select the Run Launch On-Premise Agent checkbox if you want the agent to start immediately after closing the wizard.
    3. Click Finish to close the installer.
    4. The OneEnterprise On-Premise Agent icon appears in the Windows system tray, confirming that the service is running.


Info
After installation, verify that the OneEnterprise One-Premise Agent service is listed in Windows Services (services.msc) with a status of Running. If the service is not running, restart it manually or contact support.

Optional Configuration

After installation, you can manage the OneEnterprise On-Premise Agent directly from the Windows system tray. The tray icon provides quick access to service controls and diagnostic information.

View the Agent in the System Tray

Once installed, the OneEnterprise On-Premise Agent appears as an icon in the Windows notification area (system tray) in the bottom-right corner of the taskbar.
  1. If the icon is not visible, click the up arrow (^) on the taskbar to expand hidden tray icons.
  2. A running agent is indicated by the OneEnterprise icon appearing in the tray.
  3. Right-click the icon to open the agent's context menu and access management options.

Start and Stop the Agent Service

You can start and stop the OneEnterprise On-Premise Agent service directly from the system tray without opening Windows Services.

Stopping the Service

To stop the agent when it is currently running:
  1. Right-click the agent icon in the system tray.
  2. Select Stop from the context menu.
  3. The agent service stops, and the icon changes to indicate that the service is inactive.

Starting the Service

To start the agent when it is currently stopped:
  1. Right-click the agent icon in the system tray.
  2. Select Start from the context menu.
  3. The agent service starts and connects to the OneEnterprise platform. The icon updates to reflect the active state.


Warning
Stopping the agent disconnects all active integrations that depend on it. Ensure no critical flows are running before stopping the service in a production environment.

View Agent Information

The About screen provides diagnostic information about the installed agent, including the version number, agent ID, and connection status.
  1. Right-click the agent icon in the system tray.
  2. Select About from the context menu.
  3. The About dialog displays the agent version, installation path, connection status, and the agent's unique identifier.
  4. Share this information with OneEnterprise support when reporting issues.


Uninstalling the OneEnterprise On-Premise Agent

If you need to remove the OneEnterprise On-Premise Agent from a machine — for example, when decommissioning a server or migrating to a new host — follow the steps below. Uninstalling the agent stops the service and removes all related files and registry entries.
Warning
Before uninstalling, ensure that all OneEnterprise flows that depend on this agent are paused or rerouted to another agent instance. Removing the agent without updating the flow configuration will cause those flows to fail.

Step 1 – Access Programs and Features in the Control Panel

  1. Navigate to the Windows uninstaller through the Control Panel.
  2. Or
  3. Press Windows + R to open the Run dialog.
  4. Type control and press Enter to open the Control Panel.
  5. Navigate to Control Panel > All Control Panel Items > Programs and Features.
  6. Locate OneEnterprise On-Premise Agent in the list of installed programs.
  7. Click the entry to select it, then click Uninstall at the top of the list.

Step 2 – Confirm and Proceed with the Uninstall

  1. The uninstall wizard opens and guides you through the removal process.
  2. The uninstall wizard launches automatically when you click Uninstall.
  3. Review the prompt, then click Uninstall to confirm you want to remove the agent.
  4. The wizard stops the Windows service, removes all installed files, and cleans up registry entries.
  5. The progress screen shows the removal status. Do not close the wizard while it is in progress.

Step 3 – Close the Uninstall Wizard

  1. Once the removal is complete, the wizard displays a confirmation screen.
  2. Review the completion message to confirm that the uninstall succeeded without errors.
  3. Click Close or Finish to exit the wizard.
  4. The OneEnterprise On-Premise Agent icon is removed from the system tray.
  5. Verify removal by checking that the agent no longer appears in Programs and Features.


Idea
After uninstalling, the installation folder may remain on disk if it contained user-modified configuration files. Delete the folder manually if a clean removal is required.


    • Related Articles

    • On-Premise Agent

      Overview The On-Premise Agent in OneEnterprise is a lightweight proxy component that you deploy within your private network to enable secure, bidirectional communication between your on-premises systems and the OneEnterprise cloud integration ...

    • Error Details

      Overview This section provides a detailed guide on systematically reviewing the errors in your system. You can categorize and analyze different types of errors based on when they occur—during the design phase, setup process, or runtime execution. ...

    • Add Business Partner Communication

      Overview In this section, you will find a comprehensive and easy-to-follow guide on how to add communication details for your business partner. These details will be displayed on your business card and represent your official communication. You can ...

    • Business Partner Dashboard

      Overview In OneEnterprise, a Business Partner refers to any individual or organization that collaborates with us on a business-to-business (B2B) level. Becoming a Business Partner is simple—anyone who registers with OneEnterprise is automatically ...

    • Edit Business Partner Communication

      In this section, you will find a detailed guide that will help you update your business communications easily. The instructions provided here will guide you through the process of editing the communication details, such as email address, phone ...