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 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.

On-Premise Agent vs Stack vs AI Agent

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

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?

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.

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.

Health & Metadata Fields

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

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 -- setting _agentId on filesystem, JDBC, database, MongoDB, and HTTP connections that reach a private network
• 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:

# List all on-premise agents
celigo on-premise-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 is the agent record without its access token -- read the token separately when you're ready to pair.

# Create a new agent registration
echo '{"name":"On-Prem DC1 - Oracle & File Share","description":"Tunnel for the datacenter-1 private network"}' | celigo on-premise-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. The installer download is a short-lived (about 15 minutes) pre-signed URL:

celigo on-premise-agents installer-url <id> --os linux     # or --os windows

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.

celigo on-premise-agents token <id>     # prints the access token

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

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

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). 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 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.

celigo on-premise-agents rotate-token <id>     # PUT /v1/agents/{id}/change-token; prints the new token

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 does not take all private-system connectivity with it.

CLI Commands

# CRUD
celigo on-premise-agents list
celigo on-premise-agents get <id>
celigo on-premise-agents create < agent.json
celigo on-premise-agents update <id> < agent.json
celigo on-premise-agents delete <id> [-y]
celigo on-premise-agents dependencies <id>       # connections that use it -- empty means safe to delete

# Token and installer
celigo on-premise-agents token <id>              # prints the access token (never on get/create) -- keep it out of chat
celigo on-premise-agents rotate-token <id>       # prints a new token; the old one stops working immediately
celigo on-premise-agents installer-url <id> --os <linux|windows>

# Discovery
celigo account search "<keyword>"

Note: only name and description are writable. Installing the software and applying a token happen on the host.

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 access token (celigo on-premise-agents token <id>) was applied to the installed software
• celigo on-premise-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 (see Connections That Route Through an Agent)

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 -- which the create response doesn't include (celigo on-premise-agents token <id> reads it). Nothing connects until you install the software on a host and pair it with that token.
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. rotate-token invalidates the old token immediately; the installed agent must be reconfigured with the new one and reconnects only after re-pairing. Rotate during a quiet window.
6. The access token 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