Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

on-premise-agents

Manage on-premise agents (OPA) — software processes you run inside your own network that open a secure tunnel back to integrator.io so flows can reach systems behind a firewall.

REST API: On-premise Agents API reference

Backed by /v1/agents. Despite the endpoint name, this resource is exclusively for on-premise (network gateway) agents — not AI agents. AI agents are documented under ai-agents and live under /v1/imports with adaptorType: AiAgentImport.

celigo on-premise-agents <subcommand> [args] [flags]

Supports all global flags.

Subcommands

Subcommand
Purpose

list

List all on-premise agents on the account.

get <id>

Fetch one on-premise agent by ID.

create

Create an on-premise agent from JSON on stdin.

update <id>

Full replace from stdin (destructive PUT).

set <id> key=value …

Safe field edit via GET → modify → PUT.

delete <id>

Delete an on-premise agent record.

dependencies <id>

List resources that depend on this agent (alias: used-by).

audit <id>

Show the change-history audit log for one agent.

token <id>

Show the current access token.

rotate-token <id>

Rotate (regenerate) the access token.

installer-url <id>

Get the signed installer download URL.

celigo on-premise-agents list

List every on-premise agent registered on the account.

Signature

Default table columns: _id, name, offline, lastModified.

Corresponds to: GET /v1/agents.

celigo on-premise-agents get <id>

Fetch one on-premise agent by ID.

Signature

Arguments

Argument
Required
Description

<id>

yes

On-premise agent _id.

Corresponds to: GET /v1/agents/{_id}.

celigo on-premise-agents create

Create a new on-premise agent record from a JSON body. Read the body from a file with -f, --file (recommended), or pipe it on stdin. The record allocates an access token that an installed agent process uses to authenticate its tunnel.

Signature

Flags

Flag
Type
Default
Description

-f, --file <path>

string

—

Read the JSON body from a file instead of stdin (--file - also means stdin).

Request body: full agent JSON body.

Corresponds to: POST /v1/agents.

celigo on-premise-agents update <id>

Full replace of an on-premise agent via PUT. Omitted fields are erased: always get first, modify, then pass the complete object back in (--file <path> or stdin). Prefer set for small edits.

⚠️ update is a full PUT replace. Any field you omit from the body is erased. GET the current record first, modify it, then send the complete object back — or use set for targeted edits.

Signature

Arguments

Argument
Required
Description

<id>

yes

On-premise agent _id.

Flags

Flag
Type
Default
Description

-f, --file <path>

string

—

Read the JSON body from a file instead of stdin (--file - also means stdin).

--force

boolean

false

Submit even if the body contains masked credential values (***) copied from a get.

Request body: full agent JSON body.

Corresponds to: PUT /v1/agents/{_id}.

celigo on-premise-agents set <id> key=value …

Safe field edit. Whitelisted fields (name, debugUntil, schedule.*, and similar) are applied via an atomic PATCH; any other field goes through GET → modify → PUT. Values auto-parse (offline=true → boolean, name=null removes the field). Dot notation and array indices are supported. A key=file://<path> value loads that field's value from a file instead of the command line (a leading ~ and relative paths are supported).

Signature

Arguments

Argument
Required
Description

<id>

yes

On-premise agent _id.

key=value …

yes (at least one)

Assignments to apply. Use key=file://<path> to load a value from a file.

Example

Corresponds to: GET /v1/agents/{_id} then PUT /v1/agents/{_id} (or an atomic PATCH for whitelisted fields).

celigo on-premise-agents delete <id>

Delete the on-premise agent record. Deleting the record invalidates the token and the agent process can no longer connect, but this does not uninstall the agent software on the host — stop or remove the installed service separately.

⚠️ Deleting an agent cannot be undone. The record is removed and its token invalidated, so the running agent can no longer connect.

Signature

Arguments

Argument
Required
Description

<id>

yes

On-premise agent _id.

Flags

Flag
Description

-y, --yes

Skip the interactive confirmation prompt.

Corresponds to: DELETE /v1/agents/{_id}.

celigo on-premise-agents dependencies <id>

List the resources that depend on an on-premise agent. Use this to check whether the agent is safe to delete: an empty result means no dependents. Aliased as used-by.

Signature

Arguments

Argument
Required
Description

<id>

yes

On-premise agent _id.

Corresponds to: GET /v1/agents/{_id}/dependencies.

celigo on-premise-agents audit <id>

Show the audit log (change history) for one on-premise agent.

Signature

Arguments

Argument
Required
Description

<id>

yes

On-premise agent _id.

Corresponds to: GET /v1/agents/{_id}/audit.

celigo on-premise-agents token <id>

Return the current (unmasked) access token for an on-premise agent. The installer uses this value during setup so the running agent can authenticate its tunnel. Treat the output as a secret.

Signature

Arguments

Argument
Required
Description

<id>

yes

On-premise agent _id.

Corresponds to: GET /v1/agents/{_id}/display-token.

celigo on-premise-agents rotate-token <id>

Rotate the access token. The previous token is invalidated immediately, so any running agent process still using the old value will stop connecting until it is reconfigured with the new token (returned in this command's output).

⚠️ Rotating the token immediately invalidates the previous one. Any running agent still using the old token stops connecting until it is reconfigured with the new value.

Signature

Arguments

Argument
Required
Description

<id>

yes

On-premise agent _id.

Corresponds to: PUT /v1/agents/{_id}/change-token.

celigo on-premise-agents installer-url <id>

Get the signed installer download URL for an on-premise agent. The URL points at the agent installer the host runs to set up the tunnel.

Signature

Arguments

Argument
Required
Description

<id>

yes

On-premise agent _id.

Flags

Flag
Description

--os <os>

Target OS for the installer (e.g. windows, linux, macOS).

Example

Corresponds to: GET /v1/agents/{_id}/installer-url.

Gotchas

  • "OPA" means on-premise agent — not OpenAPI or OpenPolicy. The command is on-premise-agents (the API resource is /v1/agents); the CLI has no OpenPolicy/Rego integration.

  • Two different "agent" resources. This command targets /v1/agents (on-prem gateways). AI agent imports live at /v1/imports with adaptorType: AiAgentImport and are managed via celigo ai-agents. They are unrelated.

  • rotate-token is immediately destructive to running agents. Any host still running the old token drops off until its config is updated. rotate-token returns the new token in its output — roll it out before treating the rotation as done. (token re-fetches the current value later.)

  • update is a full PUT. Omitted fields are dropped. Use set for targeted edits.

  • delete only removes the record. The installed agent binary on your server is not touched — stop/uninstall it separately.

  • Tokens are secrets. token prints the token in plaintext; avoid piping it into logs or shared terminals.

Related

  • stacks — another on-premise runtime option (stack processes) for data-residency-sensitive flows.

  • environments — on-premise agents are scoped per environment; a flow reaches only the agents in its own environment.

  • ai-agents — AI agent imports (unrelated despite the similar name).

  • connections — reference an on-premise agent on a connection to route traffic through the tunnel.

Previousnotifications
Nextprocessors

Last updated

Was this helpful?