Managing On-Premise Agents

An on-premise agent is a secure tunnel between your own network and integrator.io. You install a small piece of Celigo software on a Windows or Linux host inside your network; it dials outbound to integrator.io and holds the connection open so the platform can send work back through it. Because the agent reaches out to Celigo, you do not open inbound firewall ports or whitelist Celigo IP addresses to let the cloud reach private systems behind your firewall.

There are two things sharing the name -- keep them apart:

The installed software -- the agent daemon running on a host inside your network. It maintains the tunnel and does the reaching.
The
/agents
resource -- the registration of that daemon in integrator.io: a
```
name
```
,
```
description
```
, and pairing/health metadata. This is what you manage via the API and CLI.

Concerns when managing an on-premise agent:

Reachability -- giving Celigo a path to systems that have no public endpoint (private DBs, file shares, internal apps)
Pairing -- installing the software and configuring it with the agent's
```
accessToken
```
to bring the tunnel up
Health -- heartbeats determine
```
offline
```
; a stopped host or service breaks every connection routed through the agent
Token lifecycle -- rotating the sensitive
```
accessToken
```
(which authorizes a tunnel into your network) on exposure or on schedule

Referenced by connections via

_agentId

On-Premise Agent vs Stack vs AI Agent

The word "agent" is overloaded in Celigo. An on-premise agent is none of the others:

Term	What it is	About
On-premise agent ( `/agents` )	Network tunnel daemon installed inside your network	Connectivity -- reach private systems behind your firewall
Stack	Runs your extension code (hooks/wrappers) on your own server or AWS Lambda	Compute -- run your custom code
AI agent ( `/aiagents` )	LLM processor that classifies or transforms records inside a flow	AI processing of records

Smell test: if it is about reaching a system on a private network, it is an on-premise agent. If it is about running your custom code, that is a stack. If it is about an LLM doing work on records, that is an AI agent. A single flow can use both an agent (to reach a private database) and a stack (to run a custom hook). When a request just says "the agent," confirm which one is meant before acting.

Quick Reference

Do You Need an On-Premise Agent?

The deciding question: is the system reachable from the public internet, or only from inside your network?

Target system	Public endpoint?	Agent needed?
Public SaaS API (Salesforce, Shopify, Stripe, public REST)	Yes	No -- Celigo's cloud connects directly
Cloud database with a public endpoint	Yes	No
On-prem / private database (SQL Server, Postgres) with no public listener	No	Yes
Oracle database	--	Yes -- Oracle runs in agent mode only
Local host directory or mounted network file share	No	Yes
Internal-only application (including JDBC-accessible systems)	No	Yes

Minimum Required Fields

Creating an agent resource needs at minimum:

name

Optional but common:

description

Connections That Route Through an Agent

A connection that needs private-network or filesystem access sets

_agentId

on the connection object. The agent supplies reachability; the connection supplies the target system's credentials and config.

Connection	`_agentId`	Notes
`filesystem`	Required	Local/network file access always needs an agent
`jdbc` ( `agent` / `activedirectory` )	Required	POST fails 422 without it
`rdbms` -- Oracle	Required	Oracle is agent-mode only; even a placeholder connection needs a real `_agentId`
`mongodb` -- on-premise instance	Required	Set `_agentId` for a private (non-cloud) instance

Wiring

_agentId

onto a connection is a connection-configuration task -- see configuring-connections.

Health & Metadata Fields

These are server-managed (read-only) on the response -- you do not set them:

Field	Meaning
`accessToken`	Sensitive pairing token generated on create; reconfigure the installed agent when it changes
`lastHeartbeatAt`	Timestamp of the last heartbeat received from the installed agent
`offline`	Derived from heartbeats -- `true` when heartbeats stop (host down, service stopped, network blip)
`version`	Agent software version reported by the host
`clientDetails`	Runtime/host details reported by the installed agent

Related Skills

configuring-connections > How to Build a Connection -- setting
```
_agentId
```
on filesystem, JDBC, Oracle, and on-prem MongoDB connections
managing-stacks -- the compute counterpart; use a stack to run custom code, an agent to reach private systems
configuring-ai-agents -- the AI agent (LLM processor), a different resource despite the shared name
troubleshooting-flows > Diagnostic Workflow -- diagnosing flow failures caused by an offline agent
getting-started > Which Skill to Use -- orientation across resource types

How to Set Up an On-Premise Agent

1. Confirm you actually need one

Only when the target system is not reachable from the public internet (see Do You Need an On-Premise Agent?). Public SaaS APIs and cloud databases with public endpoints need no agent.

2. Check for an existing agent

A single agent can back many connections -- every flow that reaches systems on that network can route through it. Reuse before creating:

bash

# List all on-premise agents
celigo agents list

# Search the account
celigo account search "agent"
celigo account search "<network location or data center name>"

3. Create the agent resource

Create the registration first. The response includes a sensitive

accessToken

used to pair the installed software -- capture it now.

bash

# Create a new agent registration
echo '{"name":"On-Prem DC1 - Oracle & File Share","description":"Tunnel for the datacenter-1 private network"}' | celigo agents create

4. Install the agent software on a host inside the network

Download and install the Celigo agent software on a Windows or Linux host that can reach the private systems. This step happens on the host and through the integrator.io UI (which provides the installer download) -- not via the CLI.

5. Pair the installed agent with the access token

Configure the installed agent with the

accessToken

from step 3. This pairs the daemon to the

/agents

resource and brings the outbound tunnel up. Heartbeats begin flowing once it connects.

6. Verify the agent is online

bash

# Confirm the resource shows heartbeats and is not offline
celigo agents get <id>

Check that

offline

false

and

lastHeartbeatAt

is recent.

version

and

clientDetails

confirm what is running on the host.

7. Reference the agent from connections

On each connection that needs private-network access, set

_agentId

to this agent's

_id

. This applies to

filesystem

(required),

jdbc

agent/activedirectory, Oracle

rdbms

, and on-premise

mongodb

connections. See configuring-connections. For Oracle, install and pair the agent before creating the connection -- Oracle rejects even a placeholder connection without a real

_agentId

Rotating the Access Token

Rotate when the token may be exposed or on a security schedule. Rotation regenerates the
accessToken
and invalidates the previous one, so the installed agent must be reconfigured with the new token and will reconnect only after re-pairing -- expect a brief disconnect.

Rotation and installer download are platform actions (integrator.io UI / API), not CLI CRUD operations. Plan a rotation for a quiet window and have access to the host so the new token can be applied promptly. Treat the token like any credential.

Running More Than One Agent

Default to one agent per network location. Reasons to run more are about topology and resilience, not raw volume:

Segmentation -- an agent in each network segment or data center it must reach.
Availability -- a second agent so one host going down does not take all private-system connectivity with it.

CLI Commands

bash

# CRUD
celigo agents list
celigo agents get <id>
celigo agents create < agent.json
celigo agents update <id> < agent.json
celigo agents delete <id> [-y]

# Discovery
celigo account search "<keyword>"

Note: only

name

and

description

are writable. Installing/pairing the agent software and rotating the

accessToken

are done through the integrator.io UI on the host, not the CLI.

Pre-Submit Checklist

Before creating or wiring up an on-premise agent, verify:

The target is genuinely private -- a public SaaS API or public cloud database needs no agent
```
name
```
identifies the network location it serves (e.g. "On-Prem DC1"), not a single flow or operation
The
```
accessToken
```
from create was captured and applied to the installed software

celigo agents get <id>

shows

offline: false

with a recent

lastHeartbeatAt

before relying on it

For Oracle: the agent is installed and paired before the connection is created
Dependent connections set
```
_agentId
```
to this agent's
```
_id
```
(
```
filesystem
```
, JDBC agent/activedirectory, Oracle
```
rdbms
```
, on-prem
```
mongodb
```
)

Gotchas

"Agent" is overloaded. An on-premise agent (
```
/agents
```
, connectivity) is not a stack (compute) and not an AI agent (
```
/aiagents
```
, LLM processing). Confirm which one is meant before acting.
The tunnel is outbound-only. The agent dials out to integrator.io; you never open inbound firewall ports or whitelist Celigo IPs to reach private systems.
The resource is not the software. Creating the
```
/agents
```
resource only registers it and mints a token. Nothing connects until you install the software on a host and pair it with the
```
accessToken
```
.
Agent offline breaks dependent flows -- fix the agent, not the flow. When a flow to a private system fails and credentials look fine, check whether the agent is
```
offline
```
(host down, service stopped, network blip). Bringing the agent back online recovers every connection routed through it.
Rotating the token forces a re-pair. Rotation invalidates the old token; the installed agent must be reconfigured with the new one and reconnects only after re-pairing. Rotate during a quiet window.
The
accessToken
is a credential. It authorizes a tunnel into your network. Do not commit or share it; rotate it if it may have been exposed.
Oracle is agent-mode only. Oracle
```
rdbms
```
connections always require a real
```
_agentId
```
-- you cannot create even a placeholder Oracle connection without an installed agent first.
One agent can serve many connections. Add more agents for network segmentation or availability, not just for throughput.

Common Errors

Error	Cause	Fix
Agent shows `offline: true`	Heartbeats stopped -- host down, service stopped, or network interruption	Restart the agent software on the host; confirm outbound connectivity to integrator.io, then re-check `lastHeartbeatAt`
Flows to a private system suddenly fail; credentials fine	The shared agent is offline	Check `celigo agents get <id>` ; bring the agent back online rather than editing each connection
Installed agent will not connect after rotation	Old, invalidated token still configured on the host	Reconfigure the agent with the new `accessToken` and let it re-pair
`422` creating an Oracle / JDBC / filesystem connection -- `_agentId` missing	The connection type requires an agent but none is referenced	Install and pair an agent, then set `_agentId` on the connection
Connection routed through agent times out ( `ETIMEDOUT` )	Agent host cannot reach the target system on the private network	Verify the host can reach the target's host/port; check internal firewall/routing between the agent host and the system
`404` on agent get/update	Wrong agent ID or the agent was deleted	Verify the ID with `celigo agents list`

managing-on-premise-agents

NPX Install

Tags

SKILL.md Content

Managing On-Premise Agents

On-Premise Agent vs Stack vs AI Agent

Quick Reference

Do You Need an On-Premise Agent?

Minimum Required Fields

Connections That Route Through an Agent

Health & Metadata Fields

Related Skills

How to Set Up an On-Premise Agent

1. Confirm you actually need one

2. Check for an existing agent

3. Create the agent resource

4. Install the agent software on a host inside the network

5. Pair the installed agent with the access token

6. Verify the agent is online

7. Reference the agent from connections

Rotating the Access Token

Running More Than One Agent

CLI Commands

Pre-Submit Checklist

Gotchas

Common Errors