Back to Details

managing-on-premise-agents

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- TIER:1 -->
<!-- TIER:1 -->

Managing On-Premise Agents

管理本地代理（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
.
本地代理是您自有网络与integrator.io之间的安全隧道。您需要在网络内的Windows或Linux主机上安装一款小型Celigo软件；它会向integrator.io发起出站连接并保持连接开放，以便平台通过该连接回传任务。由于是代理主动连接Celigo，因此您无需打开入站防火墙端口或白名单Celigo的IP地址，即可让云端访问防火墙后的私有系统。
有两个同名概念需要区分：
  • 已安装的软件——在您网络内主机上运行的代理守护进程，负责维护隧道并发起连接。
  • /agents
    资源    ——该守护进程在integrator.io中的注册信息：包含
    name
    、
    description
    以及配对/健康元数据。您可通过API和CLI管理该资源。
管理本地代理时需要关注的要点：
  • 可达性——为Celigo提供访问无公网端点系统的路径（私有数据库、文件共享、内部应用）
  • 配对——安装软件并使用代理的
    accessToken
    进行配置，以建立隧道
  • 健康状态——通过心跳判断
    offline
    状态；主机或服务停止会中断所有通过该代理路由的连接
  • 令牌生命周期——当访问令牌（accessToken）暴露或按计划轮换时，更新这个敏感的令牌（它授权隧道接入您的网络）
通过连接对象的
_agentId
字段关联代理。

On-Premise Agent vs Stack vs AI Agent

本地代理 vs 计算栈（Stack）vs AI代理

The word "agent" is overloaded in Celigo. An on-premise agent is none of the others:
TermWhat it isAbout
On-premise agent (
/agents
)		Network tunnel daemon installed inside your networkConnectivity -- reach private systems behind your firewall
StackRuns your extension code (hooks/wrappers) on your own server or AWS LambdaCompute -- run your custom code
AI agent (
/aiagents
)		LLM processor that classifies or transforms records inside a flowAI 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.
Celigo中“agent”一词存在多义性。本地代理与其他两者完全不同：
术语定义说明
本地代理（
/agents
）		安装在您网络内的网络隧道守护进程连接性——访问防火墙后的私有系统
计算栈（Stack）在您自有服务器或AWS Lambda上运行扩展代码（钩子/包装器）计算能力——运行自定义代码
AI代理（
/aiagents
）		在流程中对记录进行分类或转换的LLM处理器对记录进行AI处理
快速判断：如果是关于访问私有网络中的系统，则是本地代理；如果是关于运行自定义代码，则是计算栈；如果是关于LLM处理记录，则是AI代理。单个流程可同时使用代理（访问私有数据库）和计算栈（运行自定义钩子）。当请求中仅提到“agent”时，需先确认具体指哪一种再操作。

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 systemPublic endpoint?Agent needed?
Public SaaS API (Salesforce, Shopify, Stripe, public REST)YesNo -- Celigo's cloud connects directly
Cloud database with a public endpointYesNo
On-prem / private database (SQL Server, Postgres) with no public listenerNoYes
Oracle database--Yes -- Oracle runs in agent mode only
Local host directory or mounted network file shareNoYes
Internal-only application (including JDBC-accessible systems)NoYes
判断标准：目标系统能否从公网访问，还是仅能在您的网络内访问？
目标系统是否有公网端点？是否需要代理？
公网SaaS API（Salesforce、Shopify、Stripe、公网REST）是否——Celigo云端可直接连接
带公网端点的云数据库是否
无公网监听器的本地/私有数据库（SQL Server、Postgres）否是
Oracle数据库——是——Oracle仅支持代理模式
本地主机目录或挂载的网络文件共享否是
仅限内部访问的应用（包括JDBC可访问的系统）否是

Minimum Required Fields

最小必填字段

Creating an agent resource needs at minimum: 
name
.
Optional but common: 
description
.
创建代理资源至少需要：
name
。
可选但常用：
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
RequiredLocal/network file access always needs an agent
jdbc
(
agent
/ 
activedirectory
)		RequiredPOST fails 422 without it
rdbms
-- Oracle		RequiredOracle is agent-mode only; even a placeholder connection needs a real 
_agentId
mongodb
-- on-premise instance		RequiredSet 
_agentId
for a private (non-cloud) instance
Wiring 
_agentId
onto a connection is a connection-configuration task -- see configuring-connections.
需要访问私有网络或文件系统的连接，需在连接对象上设置
_agentId
。代理提供可达性，连接提供目标系统的凭证和配置。
连接类型是否需要
_agentId
？		说明
filesystem
必填本地/网络文件访问始终需要代理
jdbc
（
agent
/ 
activedirectory
）		必填未设置时POST请求会返回422错误
rdbms
——Oracle		必填Oracle仅支持代理模式；即使是占位连接也需要真实的
_agentId
mongodb
——本地实例		必填私有（非云端）实例需设置
_agentId
在连接上配置
_agentId
属于连接配置任务——请参阅配置连接。

Health & Metadata Fields

健康与元数据字段

These are server-managed (read-only) on the response -- you do not set them:
FieldMeaning
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
这些字段由服务器管理（只读），您无需设置：
字段含义
accessToken
创建时生成的敏感配对令牌；令牌变更时需重新配置已安装的代理
lastHeartbeatAt
最后一次接收已安装代理心跳的时间戳
offline
由心跳状态推导——心跳停止时为
true
（主机宕机、服务停止、网络中断）
version
主机上报的代理软件版本
clientDetails
已安装代理上报的运行时/主机详情

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
<!-- TIER:2 -->
  • 配置连接 > 如何创建连接——在文件系统、JDBC、Oracle和本地MongoDB连接上设置
    _agentId
  • 管理计算栈——计算能力的对应组件；使用计算栈运行自定义代码，使用代理访问私有系统
  • 配置AI代理——AI代理（LLM处理器），尽管同名但属于不同资源
  • 流程故障排查 > 诊断流程——诊断因代理离线导致的流程失败
  • 入门指南 > 如何选择技能——各类资源的定位指南
<!-- TIER:2 -->

How to Set Up an On-Premise Agent

如何设置本地代理

1. Confirm you actually need one

1. 确认是否真的需要代理

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.
仅当目标系统无法从公网访问时才需要（请参阅是否需要本地代理？）。公网SaaS API和带公网端点的云数据库无需代理。

2. Check for an existing agent

2. 检查是否已有代理

A single agent can back many connections -- every flow that reaches systems on that network can route through it. Reuse before creating:
bash
undefined
单个代理可支持多个连接——所有访问该网络内系统的流程都可通过它路由。创建前优先复用：
bash
undefined

List all on-premise agents

列出所有本地代理

celigo agents list
celigo agents list

Search the account

搜索账户

celigo account search "agent" celigo account search "<network location or data center name>"
undefined
celigo account search "agent" celigo account search "<网络位置或数据中心名称>"
undefined

3. Create the agent resource

3. 创建代理资源

Create the registration first. The response includes a sensitive 
accessToken
used to pair the installed software -- capture it now.
bash
undefined
先创建注册信息。响应中包含用于配对已安装软件的敏感
accessToken
——请立即保存该令牌。
bash
undefined

Create a new agent registration

创建新的代理注册

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

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

4. 在网络内的主机上安装代理软件

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.
在可访问私有系统的Windows或Linux主机上下载并安装Celigo代理软件。此步骤需在主机上通过integrator.io UI完成（UI提供安装程序下载）——无法通过CLI完成。

5. Pair the installed agent with the access token

5. 使用访问令牌配对已安装的代理

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.
使用步骤3中获取的
accessToken
配置已安装的代理。这会将守护进程与
/agents
资源配对，并建立出站隧道。连接成功后开始发送心跳。

6. Verify the agent is online

6. 验证代理是否在线

bash
undefined
bash
undefined

Confirm the resource shows heartbeats and is not offline

确认资源显示心跳且未处于离线状态

celigo agents get <id>

Check that `offline` is `false` and `lastHeartbeatAt` is recent. `version` and `clientDetails` confirm what is running on the host.
celigo agents get <id>

检查`offline`是否为`false`，且`lastHeartbeatAt`为最近时间。`version`和`clientDetails`可确认主机上运行的代理信息。

7. Reference the agent from connections

7. 在连接中引用代理

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
.
对每个需要访问私有网络的连接，将
_agentId
设置为该代理的
_id
。这适用于
filesystem
（必填）、JDBC agent/activedirectory、Oracle 
rdbms
和本地
mongodb
连接。请参阅配置连接。对于Oracle，需先安装并配对代理，再创建连接——Oracle会拒绝未设置真实
_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.
当令牌可能已暴露或按安全计划需要轮换时执行此操作。轮换会重新生成
accessToken
并使旧令牌失效，因此已安装的代理必须使用新令牌重新配置，且仅在重新配对后才会重新连接——会出现短暂中断。
令牌轮换和安装程序下载是平台操作（integrator.io UI / API），而非CLI的CRUD操作。请选择业务低峰期进行轮换，并确保可访问主机以便及时应用新令牌。请像对待其他凭证一样妥善保管令牌。

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

CLI命令

bash
undefined
bash
undefined

CRUD

CRUD操作

celigo agents list celigo agents get <id> celigo agents create < agent.json celigo agents update <id> < agent.json celigo agents delete <id> [-y]
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.

<!-- TIER:3 -->
celigo account search "<keyword>"

注意：仅`name`和`description`字段可修改。代理软件的安装/配对以及`accessToken`的轮换需通过主机上的integrator.io UI完成，无法通过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
    )
创建或配置本地代理前，请验证：
  • 目标系统确实是私有系统——公网SaaS API或公网云数据库无需代理
  • name
    能标识其服务的网络位置（例如“On-Prem DC1”），而非单个流程或操作
  • 创建时获取的
    accessToken
    已保存并应用到已安装的软件中
  • celigo agents get <id>
    显示
    offline: false
    且
    lastHeartbeatAt
    为最近时间，之后再依赖该代理
  • 对于Oracle：先安装并配对代理，再创建连接
  • 关联连接已将
    _agentId
    设置为该代理的
    _id
    （
    filesystem
    、JDBC agent/activedirectory、Oracle 
    rdbms
    、本地
    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.
  1. “Agent”一词存在多义性。本地代理（
    /agents
    ，连接性）不是计算栈（计算能力），也不是AI代理（
    /aiagents
    ，LLM处理）。操作前需确认具体指哪一种。
  2. 隧道仅支持出站连接。代理主动连接integrator.io；您无需打开入站防火墙端口或白名单Celigo的IP地址即可访问私有系统。
  3. 资源不等于软件。创建
    /agents
    资源仅完成注册并生成令牌。只有在主机上安装软件并使用
    accessToken
    配对后，才会建立连接。
  4. 代理离线会中断关联流程——修复代理而非流程。当访问私有系统的流程失败且凭证无误时，请检查代理是否处于
    offline
    状态（主机宕机、服务停止、网络中断）。代理恢复在线后，所有通过它路由的连接都会恢复。
  5. 轮换令牌需重新配对。轮换会使旧令牌失效；已安装的代理必须使用新令牌重新配置，且仅在重新配对后才会重新连接。请选择业务低峰期进行轮换。
  6. accessToken
    是敏感凭证    。它授权隧道接入您的网络。请勿提交或分享该令牌；若可能已暴露，请立即轮换。
  7. Oracle仅支持代理模式。Oracle 
    rdbms
    连接始终需要真实的
    _agentId
    ——如果未先安装代理，无法创建甚至是占位的Oracle连接。
  8. 单个代理可支持多个连接。仅在需要网络分段或高可用性时添加更多代理，而非仅为了吞吐量。

Common Errors

常见错误

ErrorCauseFix
Agent shows 
offline: true
Heartbeats stopped -- host down, service stopped, or network interruptionRestart the agent software on the host; confirm outbound connectivity to integrator.io, then re-check 
lastHeartbeatAt
Flows to a private system suddenly fail; credentials fineThe shared agent is offlineCheck 
celigo agents get <id>
; bring the agent back online rather than editing each connection
Installed agent will not connect after rotationOld, invalidated token still configured on the hostReconfigure 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 referencedInstall 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 networkVerify 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 deletedVerify the ID with 
celigo agents list
错误原因修复方案
代理显示
offline: true
心跳停止——主机宕机、服务停止或网络中断在主机上重启代理软件；确认到integrator.io的出站连接正常，然后重新检查
lastHeartbeatAt
访问私有系统的流程突然失败；凭证无误共享代理处于离线状态执行
celigo agents get <id>
检查；恢复代理在线状态，而非修改每个连接
轮换令牌后已安装的代理无法连接主机上仍配置着已失效的旧令牌使用新的
accessToken
重新配置代理并重新配对
创建Oracle/JDBC/文件系统连接时返回
422
——
_agentId
缺失		该连接类型需要代理但未引用安装并配对代理，然后在连接上设置
_agentId
通过代理路由的连接超时（
ETIMEDOUT
）		代理主机无法访问私有网络中的目标系统验证代理主机能否访问目标系统的主机/端口；检查代理主机与目标系统之间的内部防火墙/路由
获取/更新代理时返回
404
代理ID错误或代理已被删除使用
celigo agents list
验证ID