# Catalogue and integration installation

> What is visible before installation, how the signature is checked, how versions are chosen and what revocation means.

An integration is a **signed bundle of code** that the connector downloads from the
catalogue and runs on its side. The agent’s core does not change: a new integration requires
neither an agent update nor trust in something you have not seen.

## What is visible before installation

For every version the catalogue shows exactly what settles the question “should this be let into
my network”:

| | |
|---|---|
| **Where it will be able to go** | not a list of addresses but a **rule**: “to the address from this connection’s `base_url` field”, plus the allowed methods and path prefixes. A specific address appears only once you fill in the form |
| **Which credentials it will ask for** | their names and kind (a token, an “account + secret” pair, the tracker’s own header) |
| **Whether it accepts webhooks** | and in what form: it parses the call’s content or only wakes up on it |
| **Tools** | the full list, marking which ones only read |
| **Publisher, version, host API, size** | and the bundle’s digital fingerprint |

_Illustration: The connector catalogue: access boundaries and tools — before the code ends up on the machine._

The same facts are on the public showcase: the [integration catalogue](/en/marketplace) is built from
the same signed catalogue your agent reads, so the page cannot promise
more than the connector will do.

The same in the terminal:

```bash
connector catalog show jira --config /etc/connector/connector.yaml
```

## The signature and where the code comes from

The catalogue and every bundle are signed with our key; **the public key is built into the agent’s
binary**. The check happens before unpacking: a bundle with a foreign or damaged signature never
reaches the disk.

The catalogue itself lives **in a container registry** (`registry.buff.systems`), not on
a separate host. This is done for closed perimeters: a registry is something your team can already
mirror into its own Harbor or Nexus, scan and allow by list. Then
the only change is the mirror’s address; the same signatures are checked, because the registry is
only the transport here.

## Installation

On the [local page](/en/docs/connector/web-setup#catalogue) — the **“Install”** button;
in the terminal:

```bash
connector install jira --config /etc/connector/connector.yaml        # the latest compatible one
connector install jira@1.4.1 --config /etc/connector/connector.yaml  # a specific version
```

Installation **does not create a connection** and starts nothing: the code has landed on the machine, and
you decide which system to connect it to. One installed piece of code serves any number of
connections.

## Versions

- **A connection is pinned to a version.** A new one appearing changes nothing by itself:
  “worked yesterday — works today” matters more than freshness.
- **`install` without a version** installs the latest one **compatible with this agent build**.
  An integration that needs a newer connector will not install — and will say why.
- **Updating is a separate decision.** When a newer installed version exists for a connection,
  it gets an **“Update to …”** button. Before
  switching, the connector checks that **this connection’s settings fit the new
  version**: if the version requires a field you do not have, the update does not happen and
  says what is missing — instead of a connection that falls over after the update.
- **A version is bytes.** The same version always means the same bundle:
  this is what the catalogue’s signature protects. If the content changed, a new version was released.

## Version revocation

If a problem is found in a version, we mark it as revoked in the revocation list — it is
signed and read together with the catalogue.

- A revoked version cannot be installed.
- A connection that is already running is not silently turned off: the connector marks it as
  running on a revoked version, and this is visible both on the local page and in the app
  — so that you, not a switch on our side, make the decision to move.

Revoking a version is not the same as [revoking the connector itself](/en/docs/connector/manage#revoking-access):
the latter ends the agent’s link to the platform.

## What an integration can and cannot do

This is described in full in [“Isolation and access boundaries”](/en/docs/connector/isolation);
in short:

- it runs **as its own process under its own OS user**;
- it **does not see** the connector’s key, your tokens or other connections’ files;
- it **does not open the network itself** — the connector makes the outgoing request, under the declared
  rule and with the credentials inserted;
- it gives the model **only the read-only ones among the declared tools**; writing ones are not given to the model
  at any stage — the connector uses them at the platform’s command.