> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/cli/commands/on-premise-agents.md).

# 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`](/cli/commands/ai-agents.md) and live under `/v1/imports` with `adaptorType: AiAgentImport`.

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

Supports all [global flags](/cli/getting-started/global-flags.md).

***

## 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**

```
celigo on-premise-agents list
```

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

```
celigo on-premise-agents get <id>
```

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

```
celigo on-premise-agents create --file <path>
celigo on-premise-agents create < agent.json     # or pipe on stdin
```

**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`](#celigo-on-premise-agents-set-id-keyvalue-) 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**

```
celigo on-premise-agents update <id> --file <path>
celigo on-premise-agents update <id> < agent.json     # or pipe on stdin
```

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

```
celigo on-premise-agents set <id> key=value [key2=value2 …]
```

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

```bash
celigo on-premise-agents set 64f1a2b3c4d5e6f7a8b9c0d1 name="Warehouse gateway - DC2"
```

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

```
celigo on-premise-agents delete <id> [-y]
```

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

```
celigo on-premise-agents dependencies <id>
celigo on-premise-agents used-by <id>
```

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

```
celigo on-premise-agents audit <id>
```

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

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

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

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

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

```
celigo on-premise-agents installer-url <id> [--os <os>]
```

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

```bash
celigo on-premise-agents installer-url 64f1a2b3c4d5e6f7a8b9c0d1 --os linux
```

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

***

## Gotchas

* **"OPA" means&#x20;*****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`](/cli/commands/ai-agents.md). 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`](/cli/commands/stacks.md) — another on-premise runtime option (stack processes) for data-residency-sensitive flows.
* [`environments`](/cli/commands/environments.md) — on-premise agents are scoped per environment; a flow reaches only the agents in its own environment.
* [`ai-agents`](/cli/commands/ai-agents.md) — AI agent imports (unrelated despite the similar name).
* [`connections`](/cli/commands/connections.md) — reference an on-premise agent on a connection to route traffic through the tunnel.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.celigo.com/cli/commands/on-premise-agents.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.