Manage Celigo on-premise agents -- lightweight software you install on a host inside your own network that opens a secure OUTBOUND tunnel to integrator.io, letting the platform reach private systems (on-prem databases, file shares, internal apps) without opening inbound firewall ports. An on-premise

<! TIER:1 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](../configuring connections/SKILL.md how to build a connection). 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](../configuring connections/SKILL.md how to build a connection) setting agentId on filesystem, JDBC, Oracle, and on prem MongoDB connections [managing stacks](../managing stacks/SKILL.md) the compute counterpart; use a stack to run custom code, an agent to reach private systems [configuring ai agents](../configuring ai agents/SKILL.md) the AI agent (LLM processor), a different resource despite the shared name [troubleshooting flows Diagnostic Workflow](../troubleshooting flows/SKILL.md diagnostic workflow) diagnosing flow failures caused by an offline agent [getting started Which Skill to Use](../getting started/SKILL.md which skill to use) orientation across resource types <! TIER:2 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?]( 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: 3. Create the agent resource Create the registration first. The response includes a sensitive accessToken used to pair the installed software capture it now. 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 Check that offline is 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](../configuring connections/SKILL.md how to build a connection). 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 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. <! TIER:3 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 1. "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. 2. 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. 3. 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 . 4. 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. 5. 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. 6. 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. 7. 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. 8. 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