Name: managing-on-premise-agents
Author: celigo

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 open no inbound firewall ports for it; a network that restricts outbound traffic only has to let the agent host reach Celigo (see Gotcha 2). 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 access token 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 access token (which authorizes a tunnel into your network) on exposure or on schedule Referenced by connections via agentId . The agent resource is read and managed with the CLI, the REST API ( /v1/agents ) or the UI; no MCP tool reads it, and its id isn't an AI agent's, so don't look it up among AI agents. Over MCP, the connections that carry its agentId , their offline flag, and the agent not running errors on their flows say what you need to know. 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, MySQL, Postgres, MongoDB) 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 an HTTP/REST or SOAP API on the private network, or a JDBC accessible system 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. An export on it can't take an EDI profile: the spec accepts ediProfileId on FTP, AS2, S3 and HTTP file exports only jdbc ( agent / activedirectory ) Required POST fails 422 without it; other JDBC types commonly run on an agent too rdbms Oracle Required Oracle is agent mode only; even a placeholder connection needs a real agentId rdbms SQL Server, MySQL, PostgreSQL on a private network Set for an on premise instance The connection's on premise mode. SQL Server through an agent uses database user ( basic ) auth only, and a create still needs password (422 Expected field: password to be present. without it) mongodb on premise instance Required for a private instance Cloud reachable instances (including Atlas) need no agent http an API reachable only inside the network Set for an on premise endpoint The connection's on premise mode: baseURI is the address as the agent host sees it (an internal hostname, or localhost on the agent host itself). With OAuth, the agent performs the token exchange locally, so the authorization server can be private too The schemas' agentId description lists only the types where an agent is required . Celigo documents agent support for SQL databases, MongoDB, DynamoDB, and HTTP connections, in addition to filesystem and JDBC. 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 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. Agents 4.6.0 and later update themselves while they run as a service (on Windows, with administrator rights); Windows Server 2012 R2 hosts stay on 4.3.0 (Gotcha 10) The pairing access token is not on the resource at all create, get, and update never return it. Read it with celigo on premise agents token <id ( GET /v1/agents/{id}/display token ). Related Skills [configuring connections How to Build a Connection](../configuring connections/SKILL.md how to build a connection) setting agentId on filesystem, JDBC, database, MongoDB, and HTTP connections that reach a private network [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: celigo account search won't find them: the account index behind it doesn't include agents, so list is the check. An agent registered in another environment isn't in this list either (Gotcha 9). 3. Create the agent resource Create the registration first. The response is the agent record without its access token read the token separately when you're ready to pair. 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. The installer download is a short lived (about 15 minutes) pre signed URL: Running the installer happens on the host the CLI only fetches the download link. 5. Pair the installed agent with the access token Configure the installed agent with the agent's access token. This pairs the daemon to the /agents resource and brings the outbound tunnel up. Heartbeats begin flowing once it connects. The command prints the secret, so have the user run it on the host (or read the token in the UI) and enter it straight into the agent's configuration don't run it where the value lands in a chat transcript. 6. Verify the agent is online Check that offline is false and lastHeartbeatAt is recent. version confirms 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 , jdbc agent/activedirectory, and Oracle rdbms connections (required), and to any private SQL Server, MySQL, PostgreSQL, MongoDB, or HTTP endpoint (see [Connections That Route Through an Agent]( connections that route through an agent)). 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 . agentId is a top level field of the connection, beside type ; the host in the connection's own block is the address as the agent host sees it. Routing through an agent doesn't waive the database credentials: a SQL Server create without password is refused with 422. When the user will enter the password themselves, create the connection with a placeholder, and say in your reply that it holds a placeholder until they enter the real password in the connection's settings in the Celigo UI the connection stays offline until they do. Never ask for the password in chat. Rotating the Access Token Rotate when the token may be exposed or on a security schedule. Rotation regenerates the access token and invalidates the previous one immediately , so the installed agent disconnects and reconnects only after it is reconfigured with the new token expect a brief outage for every connection routed through it. The rotation itself is an API call; applying the new token happens on the host . Like token , the command prints the secret have the user run it where the value goes straight into the host's configuration, during a quiet window. 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 takes out fewer connections. It doesn't take over for the first: every connection names one agent ( agentId ), so each agent serves only the connections pointed at it. Moving a connection to another agent is a full update of the connection, because agentId isn't among the fields a PATCH can change: read the connection, change agentId (and the host in its own block, if the new agent's host reaches the system by another name), and send it back with every secret left as the mask you read ([configuring connections Credential Discipline & Runtime Behavior](../configuring connections/SKILL.md credential discipline runtime behavior)). CLI Commands Note: only name and description are writable. Installing the software and applying a token happen on the host. celigo account search doesn't index agents; use list . <! 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 [ ] na