An on-premise agent is a Windows or Linux program you install on a server inside your private network. It creates a secure tunnel to connect to integrator.io, letting you integrate systems that aren't publicly accessible — without opening inbound firewall ports or adding IP addresses to an allow list.
You have two options for integrating data:
- Cloud – connects to a publicly accessible server application
- On-premise – connects to a publicly inaccessible server that has an on-premise agent installed on it.
If your application is inaccessible, you can still use two methods to connect:
- Add integrator.io IP addresses to your allow list to allow integrator.io to connect to your application or database directly
- Use an on-premise agent to connect to your application or database – without an allow list
The on-premise agent supports SQL databases, MongoDB, DynamoDB, and HTTP connections. For HTTP connections using OAuth, the agent also handles token exchange locally — so you can authenticate against authorization servers that aren't publicly accessible.
A connection can use a single agent or an agent group. An agent group keeps your connection available when one agent goes offline.
The on-premise agent requires a 64-bit operating system.
The on-premise agent automatically checks for updates and upgrades your agent to the latest version. Automatic upgrades require agent version 4.6.0 or later. If your agent is older, download and install the latest agent.
If you provide the same agent token to the new agent software, your existing connections that connect through that on-premise agent keep working without interruption.
At idle:
- CPU: Approximately 1-2% (single-core equivalent)
- RAM: Base memory footprint of about 150-300 MB
- Disk: Approximately 200-500 MB for the application and logs
- Network: Heartbeat traffic of about 1 KB every 15-30 seconds
Under load:
- CPU: 10-50%, depending on data volume and transformations
- RAM: 300 MB - 2 GB (configurable via AGENT_MAX_OLD_SPACE_SIZE)
- Disk: Variable, based on temporary file processing and log retention
Important
The agent enables multiple processes that are displayed separately in Task Manager. This is expected behavior.
You should only see the option to use an on-premise agent when you're connecting to an application. Using an on-premise agent is the best way to connect integrator.io to your on-premise server application. Because the agent makes outbound calls to integrator.io, you don't need to open inbound firewall ports or add IP addresses to an allow list. Allow outbound traffic on ports 443 (HTTPS) and 22 (SSH) in your firewall.
You can run only one agent on a machine. That agent can connect to multiple databases and applications on the same network.
For example, if you're running SQL on two virtual machines (VM1 and VM2) and you've installed an on-premise 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.
Because each machine runs only one agent, every agent in an agent group must be installed on its own machine.
Note
To run the agent as a Windows service, you need agent version 4.6.0 or later. Your account is automatically updated every time there's a release. See integrator.io release notes for the changes and current version in each release.
Agent groups for high availability
An agent group is a set of two or three on-premise agents that a connection can use instead of a single agent, so the connection keeps running when one agent goes offline. This is called high availability. When a connection uses a single agent, an outage on that agent's machine stops every flow that uses the connection. An agent group reduces this risk.
You create a group from your existing agents, then select the group in a connection instead of a single agent. You don't need to change your flows. To create a group and use it in a connection, see Set up an agent group.
How failover works
integrator.io sends all of an agent group's work to the first available agent in the group's ordered list. Work isn't spread across agents.
integrator.io stops sending new work to an agent when any of these happens:
- The agent goes offline.
- The agent hasn't sent a heartbeat for 60 seconds.
- A request to the agent fails with a connection error. integrator.io skips the agent immediately.
New work then goes to the next available agent in the list. When the first agent is available again, it takes the work back automatically.
If an agent stops partway through a flow run, imports and HTTP and REST exports continue on the next available agent. Other exports fail. When you retry them, they run on an available agent in the group.
During a failover, integrator.io can send some records from an import that was in progress a second time. Design imports to handle a record that arrives twice, for example by matching on an existing record and updating it instead of always creating a new one.
Connection status for an agent group
A connection that uses an agent group stays online while at least one agent in the group is available. It goes offline only when no agent in the group is available. The connection test succeeds when at least one agent is available.
When no agent is available, flow runs fail with an error that names the group. To resolve it, see On-premise agents: Troubleshooting and FAQs.
If every agent stops without a connection error, flow runs fail within 60 seconds, but the connection and the agents list can take up to 5 minutes to show the agents as offline.
Agent group health on the agents list
The agents list shows your agent groups above your individual agents. Go to Resources, and then select On-premise agents.
- Agent groups — Each group shows how many agents it has and how many of them are online or offline.
- Group — The groups each agent belongs to. Agents in no group show a dash (—).
- Version — The agent version of each agent.
- Status — Whether each agent is online or offline. To find out why an agent is offline, see On-premise agents: Troubleshooting and FAQs.
Requirements and limits
- Agent groups are available on Enterprise plans as a limited release. To enable On-premise agent groups, contact your account manager.
- A group must have at least two agents and can have up to three.
- Every agent in a group must belong to the same environment as the group. Agent groups can't be shared across environments.
- An agent must be on version 6.0 or later to join a group. Version 6.0 is available for Windows only.
- An agent can belong to more than one group.
- Automatic updates aren't coordinated across a group. More than one agent in a group can update and restart at the same time.
- A connection uses either one agent or one agent group.
- integrator.io can't detect agents that run on the same machine. Agents on the same machine give no protection against a machine failure.
- Integration logs don't show which agent in the group processed a flow run.
- You don't need a load balancer in front of an agent group.
Best practices for agent groups
- Install each agent on a separate machine, and preferably on separate infrastructure, so one failure can't stop every agent in the group.
- Put your most reliable machine first in the group's list.
- Run the same agent version on every agent in the group, and keep each one on the latest version. When you update agents manually, update them one at a time so the other agents keep handling work.
- Switch existing connections to a group one at a time, and test each connection after you switch.
- Check the connection test as well as the agents list. The agents list can take up to 5 minutes to show an agent as offline.
Permissions for agent groups
- Owners, administrators, and Manage all users — Create, edit, and delete agent groups.
- Monitor all users — View agent groups and the health of their agents.
- Integration-scoped Manage and Monitor users — View the agent groups that their integrations' connections use.
integrator.io records each agent group change, including changes to its agents, in the account audit log.