The Windows on-premise agent is a program you install on a server in your private network to create a secure outbound tunnel to integrator.io. It lets you build integrations with internal systems — databases, on-premise apps — without exposing them to the internet. This article covers how to install and configure the agent on Windows and how to set up a connection that uses it.
Legacy production and sandbox licenses
In legacy Production and Sandbox environments, changes to resources in one environment can affect both environments. In most cases, the Production and Sandbox environments share the same underlying resources. Any resource you create, edit, or delete in one environment is immediately reflected in the other.
This includes connections, imports, exports, flows, scripts, and API tokens. Use caution when editing resources in either environment.
This behavior doesn't apply to accounts on the multi-environment license, where each environment maintains its own isolated resources.
Migrations from the legacy Production/Sandbox license to the new multi-environment license are underway. Your account has not migrated to the new multi-environment license if you can toggle between environments.
Important
The Windows on-premise agent supports only one running agent instance per Windows machine. This means you cannot register both a Production and a Sandbox environment token against the same agent installation.
If you use multiple environments, you must:
-
Install a separate agent for each environment.
-
Run each agent on a separate physical machine or a separate Windows OS instance (such as a separate VM) that has network access to the same internal resources.
The Production agent token cannot be added to a Sandbox installation, and the Sandbox token cannot be added to an existing Production installation.
For guidance on planning agent installations across environments, see On-premise agent overview.
Before you install the agent, make sure you have:
-
An integrator.io account with access to Resources → On-premise agents
-
Network access from the agent machine to the internal systems you want to integrate
Minimum system requirements:
-
Windows version: Windows 7 or later
-
RAM: 2 GB (Minimum), 4 GB (Recommended)
-
2 CPU cores
Important
The agent enables multiple processes that are displayed separately in Task Manager. This is expected behavior.
-
Navigate to Resources → On-premise agents.
-
Select + Create on-premise agent.
-
Name your agent and add a description.
-
Select Save. Your agent now appears on the list.
-
From the Install column, select Download and choose the operating system (Windows).
-
After downloading, proceed to install the agent software.
If you downloaded the agent to the target computer, open agent-windows.exe and run the installer.
Otherwise, copy the downloaded file to the server and double-click to launch setup.
The setup prompts you to choose who can run the agent:
-
Only for me (Administrator) — accessible to only one user.
-
Anyone who uses this computer (all users) — any user can run the service, but only one user should run it at a time. Administrative privileges are not automatically assigned, and the auto-upgrade feature will not work.
-
Select your preferred option, then select Install.
-
Give Windows permission to trust the downloaded executable and proceed.
-
In the Completing Agent Setup window, ensure that Run agent is checked. Then, select Finish.
The Agent shortcut is added to your desktop and Windows programs, and the software opens to ask you for an integrator.io token.
If you selected All users, complete these steps after installation to grant administrator access:
-
Stop the service if it's running.
-
Right-click Celigo Agent in your Windows Services app.
-
Select Properties > Log on.
-
Select on this account, enter Administrator as the username, and enter the administrator password.
-
Restart the agent service.
An access token secures communication between the agent and integrator.io. Your agent token is automatically generated when you create the agent. To find the token:
-
Return to integrator.io and navigate to Resources → On-premise agents.
-
In the list of agents, select Show token.
-
Select Copy (
) next to the unmasked access token to copy it to your clipboard.
-
In the agent software, enter the access token. The agent will automatically start communicating with integrator.io.
The agent should now be online. You may need to refresh the page to confirm it's online.
If your token is compromised, you can generate a new token:
-
In integrator.io, navigate to Resources → On-premise agents.
-
Select Actions → Generate token.
This will automatically revoke the old token, so you must enter the new one.
By default, the agent runs as a standard Windows executable. Running it as a Windows service instead offers these benefits:
-
The agent will run silently and continuously after installation and each time the system starts up
-
The agent will run regardless of which user account is logged on
-
As a service, the agent can be managed and monitored from remote systems
To run the agent as a Windows service:
-
Double-click the Agent shortcut on your desktop.
-
Choose Install service.
-
The agent will confirm the successful installation.
-
Click OK to dismiss the user interface.
-
Your system must restart to run the agent as a service.
The agent will automatically launch as a Windows service once the system restarts. However, you can choose to launch it right away. To launch it immediately:
-
Double-click the Agent shortcut on your desktop.
-
Click Close.
-
Click Stop to stop it from running in the background.
-
In Windows, search for the Services application.
-
From the list of services, find Celigo Agent.
-
Right-click the service and click Start to run it right away.
If you later decide that you prefer to run it as an executable, in the taskbar or in the background, double-click the Agent shortcut and click Uninstall service.
-
Create a connection in integrator.io from Resources → Connections or by adding a new Source or Destination app in flow builder.
-
For Mode, select On-premise (the default is Cloud).
-
Select your agent from the Agent drop-down list.
When creating an integrator.io connection that uses an on-premise agent, your settings will depend on whether the agent is installed on the same server as the application or database.
-
Same server – set the Base URI to
localhostor127.0.0.1 -
Different servers on the same network – Set the Base URI to the hostname or IP address of the system the application or database is running on.
You can run only one instance of an agent on a Windows machine. However, the same agent can connect to multiple databases and applications on the same network as the agent.
For example, if you're running SQL on two virtual machines (VM1 and VM2) and you've installed an integrator.io agent on VM1, your agent can access every SQL database on the same machine and any applications in the same network. Say you have an HTTP application running on VM2 and you want to create a connection. You can use the existing agent for that connection since VM1 and VM2 are on the same network.
So, as long as VM1 and VM2 are on the same network, you can access any application on both machines.
On-premise agents route OAuth token exchange locally for HTTP connections that authenticate against private network servers. If your authorization server is on a private network, you don't need to expose it to the public internet. Make sure your agent is on the latest version to use this feature. The agent auto-update process handles this for most customers.
Note
OAuth token exchange through the agent applies only to connections configured to use an on-premise agent. Cloud-based connections are unaffected.
To verify your on-premise agent, open your Control Panel and navigate to Programs → Programs and Features. Find the agent, which may be preceded by the Celigo logo, and look at the Version column.