Install connector packages

How connector packages get onto a Console, how they are verified and trusted, and what happens to your connectors when a package is updated or removed.

Enterprise module

Connector packages belong to the enterprise connectors module. Without an Enterprise licence the Catalog and the connectors API answer 402.

Two meanings of "install"

Where	What it does	Who
Install on a card in Build → Connectors → Catalog	Opens the form that creates a connector of that type in the current project. It does not add a package to the Console.	A project member with write access
Putting a package on the Console	Makes a new connector type appear in the Catalog.	The operator of the Console

The dashboard has no upload for packages. The Catalog lists what the Console already has. If it is empty, it says This Console has no connector packages yet. An operator adds them with the Console.

Browse the Catalog

Open Build → Connectors → Catalog.

• Search with Search connector types… and narrow with Category: All, Development, Documents and files, Productivity, Communication, Databases, Storage, Business apps, Other.
• Each card shows the package name, what it is for, how it signs in (OAuth, API key, Sign-in form, Public access), and badges for what it offers: Tools with a count, MCP when the tools come from the vendor's MCP server, Knowledge when it can read documents into a Knowledge Engine module. A Developer build badge marks a package signed with a development key.
• A card shows how many connectors of that type are installed in the project.
• Two built-in cards lead to services that already exist: Web site (Go to Crawler) and Remote MCP server (Go to MCP).

Install is hidden if you only have read access.

Installed connectors

Build → Connectors → Installed lists the project's connectors. The Type column shows the package name and the version in use, as name · vversion. The Status column is one of:

Status	Meaning
Ready	Connected, with tools.
Not connected	No account yet.
Reconnect required	The sign-in no longer works.
Access revoked	The system no longer accepts the account.
Connected, tools not synced	Run Sync tools.
Connected, no tools	The package offers no tool with these settings.
Tool disabled	The managed tool is off.
Disabled	The connector is disabled.
Package missing	The package is no longer installed on this Console.

How a package gets onto the Console

The operator controls this with the Console's server environment. Packages are loaded when Console starts.

Source	How	Setting
Bundled	Packages that ship with the Console release.	CONNECTOR_PACKAGES_DIR (default ./connector-packages)
Local	.cpkg files the operator copies into a directory, for offline installs and your own packages.	CONNECTOR_PACKAGES_EXTRA_DIR
Signed index	A signed list of packages the Console downloads from. Checked at start and again every 6 hours by default.	CONNECTOR_PACKAGES_INDEX_URL, optional CONNECTOR_PACKAGES_INDEX_TOKEN (sent as a bearer token), CONNECTOR_PACKAGES_INDEX_REFRESH_HOURS

A package file may be up to 50 MB and an index up to 2 MB.

When two copies of the same package are found, the higher version replaces the lower one. The same file found twice changes nothing.

Verification and trust

Every package is verified before anything in it is used. A package that fails is logged and skipped, and loading carries on with the others; a bad package never stops Console from starting.

• The signature and the file checksums must match.
• The signing key must be trusted for the package's namespace. Official packages use the cognipeer namespace and are signed with Cognipeer's release keys.
• The manifest must be valid, and every file it names must be in the package.
• The package must be offered on this deployment (SaaS or on-prem). Otherwise it is refused with not_for_deployment.
• If the Console reports its version, it must satisfy the package's supported Console range.
• The package and its signing key must not be revoked.

To use packages you build yourself, the operator adds your namespace and public keys to a trust file and points CONNECTOR_PACKAGES_TRUST_FILE at it. That file cannot add keys to the cognipeer namespace.

When an index is used, the Console checks that the downloaded file matches the digest the index lists. An index with an older serial than the last one seen is not used, and an index may carry revocations: a revoked package version or key is refused, and a package already loaded that was revoked is unloaded. Revocations are remembered across restarts in CONNECTOR_PACKAGES_STATE_FILE (default ./data/connector-packages-state.json).

Packages run in their own process, and everything they reach on the network is limited by what the package declared. See Security and limits.

Versions and updates

Each connector records the package version and the settings version it was last checked with. When a newer package version is installed:

• Existing connectors and their accounts stay in place and keep working.
• The connector page shows The package was updated with the versions involved. The settings are migrated to the new settings version and checked again the next time you press Sync tools.
• The actions that run are always those of the installed package. If an update drops an action, a call to it fails with a message that the connector no longer offers the action.
• The markings of existing tools (read, write, destructive) are filled in again when Console starts and after packages are updated from the signed index.

When a package is removed

If a package is no longer installed on the Console, for example after the operator removed the file or a revocation unloaded it:

• The connector shows Package missing and its page says The connector package is not installed. Only deleting it works.
• Agent calls to its tool fail with a message that the package is not installed.
• Sources of the connector pause with the reason The connector package is not installed.

Installing the package again restores the connector as it was.

SaaS and on-prem

All current packages are offered on both. The differences are in what they allow:

Area	SaaS	On-prem
Reaching private network addresses	Not allowed	Packages that declare it (databases, mail, MinIO and S3-compatible storage, self-hosted GitHub, Jira, Confluence, Bitbucket, Grafana, MediaWiki, Azure Blob) can reach private addresses the operator allows
SMTP Relay without sign-in and the plain (unencrypted) security mode	Not offered	Offered
Own certificate authority settings on packages that have them	Ignored	Honoured
GitHub Sign in with GitHub (OAuth)	Can use the OAuth app of the deployment	Needs your own OAuth app
Index download	The index host must be public	May be a private host

The OAuth rows are explained in Create a connector and connect an account.