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.

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

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

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 set <id> name="<name>"  # GET + PUT; name and description are the only writable fields
celigo on-premise-agents delete <id> [-y]
celigo on-premise-agents dependencies <id>       # connections that use it -- empty means safe to delete
celigo on-premise-agents audit <id>              # change history

# 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> [-y]  # asks first (-y skips), full mode; prints a new token, the old one stops working immediately
celigo on-premise-agents installer-url <id> --os <linux|windows>

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.

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
• The agent is registered in the same environment as the connections that will use it (Gotcha 9)
• 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, so no inbound firewall port opens for it -- not the database's port either. A network that restricts outbound traffic must let the agent host connect out over HTTPS (443) and SSH (22) to Celigo's published addresses for its region: the integrator.io addresses for HTTPS and the agent-extension server addresses for SSH, listed in Celigo's on-premise agent documentation.
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 (agent_not_running) 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 its token or recreating the connections doesn't.
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 so one host's failure takes out fewer connections -- not for throughput. A second agent doesn't take over the first one's connections; each connection names one agent.
9. Agents belong to one environment. A connection in a sandbox or other environment needs an agent registered there, installed and paired with that agent's own token. Each environment's agents count against that environment's agent entitlement (celigo subscriptions entitlement-usage reports agentUsage). celigo promote never copies an agent: it binds each one to the target's single agent of the same name, or the one you pin with --map, and otherwise refuses unless --create-connections registers a new agent there, which still has to be installed and paired.
10. Update an agent in place. If version stays behind on an agent that should update itself (4.6.0 or later, running as a service), reinstall on the same host with this agent's installer and token (celigo on-premise-agents installer-url <id>, then token <id> on the host). Creating a new agent instead leaves every connection on the old one.
11. A delete is refused while connections use the agent, and doesn't touch the host. Deleting fails with 422 while any connection's _agentId names the agent: repoint or remove those connections first (celigo on-premise-agents dependencies <id> lists them). The API answers an unknown id's dependencies with the same empty {}; the CLI reads the agent too, so a wrong id fails with 404 there. A deleted agent stays in the recycle bin for 30 days, and its software stays installed on the host: stop and uninstall it there.

Common Errors