Connector packages

What a connector package is, how Console runs it, and how to write, test, sign and publish your own with the connector SDK.

Enterprise module

Connectors are the enterprise connectors module. A workspace without the module gets 402 from the connectors API, and the Connectors pages ask for an Enterprise licence.

A connector package teaches Console about one outside system: GitHub, a document system, a PostgreSQL server, a mail server. It brings the system's settings, its sign-in methods, its actions (which Console offers to agents as tools), and, where the system has them, an official MCP server, data sources for Knowledge Engine, and screens of its own. This section is for the people who write packages. If you use packages, start with the Connectors guide.

A package is code written against the connector SDK, built into one signed .cpkg file, and installed into Console. Console verifies the signature before it loads anything.

How Console runs a package

Console starts the package's server bundle in a separate Node.js process and talks to it over standard input and output, one JSON message per line. The protocol version is 1; Console supports that version and the one before it.

The package never holds a credential and never opens its own connection. When it needs something from outside, it asks Console, and Console does the work with the connected account's credential.

Host operation	What Console does	Package API
http	Makes the HTTPS request, adds the account's credential, checks the host against the package's declared egress	ctx.http
sql	Opens a read-only connection to the database named in the connector's settings and runs one statement	ctx.sql
mail	Builds the message, connects to the mail server named in the settings and sends	ctx.mail
change, file	Receives the items and file bytes a data source yields during a sync	sync generator of a source
log message	Writes the line to Console's log with every secret value cut out	ctx.log

Console calls the package for these operations: resolve, identity, action, sync, options, browse, rpc, authenticate, capture, beforeCall and migrate. You do not handle messages yourself; the SDK's runtime does.

A Console without a host operation answers it with RUNTIME_UNAVAILABLE. A package that uses ctx.sql or ctx.mail, or that asks Console to sign requests, sets engines.console to the first Console version that has the operation, so an older Console refuses to install it. See Connector definition reference.

What a package contains

You write a folder. cpc build turns it into the files below and cpc pack zips and signs them. The exact format is in Build, sign and publish.

my-connector/
  package.json          name, version, "cognipeer": { "entry": "./src/index.ts" }
  src/index.ts          export default defineConnector({ ... })
  i18n/en.json, tr.json messages for every t('key')
  guides/<id>.en.md     setup guides, one file per locale
  guides/<id>.tr.md
  assets/icon.svg       the icon
  ui/*.tsx              optional screens
  test/*.test.ts        tests, with cassettes in test/fixtures/

The package id is <publisher>.<name> in lower case, for example acme.notes. The publisher must match the namespace of the key that signs the package.

The SDK packages

Package	What it is for
@cognipeer/connector-sdk	defineConnector, the field builders, createKit for actions, sources and auth methods, p for safe paths, ConnectorError, MAIL_LIMITS, and the runtime that serves your package
@cognipeer/connector-sdk/testing	createTestHost: runs actions, sources and sign-in with the same rules as Console, with fakes for HTTP, SQL and mail. See Test a connector package
@cognipeer/connector-cli	The cpc command: build, pack, sign, verify, run an action against the live service. See Build, sign and publish
@cognipeer/connector-ui	Types and components for package screens written in React and rendered by Console in a sandboxed frame
SQL kit, storage kit	Shared code of the official PostgreSQL, MySQL, MariaDB, Amazon S3 and MinIO packages. They are bundled into those packages; a package of your own uses ctx.sql or the signing inject kinds directly

A minimal connector

This package calls a notes service with an API key and offers one read-only action. Settings are empty because the service has one fixed host.

// src/index.ts
import { createKit, defineConnector, field, guide, t, z } from '@cognipeer/connector-sdk'

const kit = createKit<Record<string, never>>()

const listNotes = kit.action({
  title: t('actions.list_notes'),
  description: 'List the notes of the connected account, newest first.',
  access: 'read',
  input: z.object({
    limit: z.number().int().min(1).max(100).optional().describe('How many notes to return. Default 20.'),
  }),
  async run(ctx, input) {
    return ctx.http.get('/notes', { limit: input.limit ?? 20 })
  },
})

export default defineConnector({
  id: 'acme.notes',
  name: 'Acme Notes',
  description: t('package.description'),
  category: 'other',
  icon: './assets/icon.svg',
  deployments: ['saas', 'onprem'],
  engines: { console: '>=1.20.0 <2.0.0' },

  settings: {},
  auth: [
    kit.auth.apiKey({
      id: 'token',
      label: t('auth.token'),
      fields: { token: field.secret({ label: t('auth.token.field'), required: true }) },
      inject: { header: 'Authorization', scheme: 'Bearer', from: 'token' },
      guide: 'token',
    }),
  ],

  http: { baseUrl: 'https://api.notes.example.com/v1', timeoutMs: 20_000 },
  permissions: { egress: { hosts: ['api.notes.example.com'] } },

  actions: { list_notes: listNotes },
  guides: { token: guide('./guides/token', { audience: 'admin' }) },
})

i18n/en.json and i18n/tr.json hold the four keys the code uses with t(), and guides/token.en.md and guides/token.tr.md explain where an administrator creates the API key. cpc build fails if a key or a guide file is missing in either language.

The agent sees the action as a tool named list_notes with the description and the input schema. Because the action is marked access: 'read', an agent runs it without asking. An action marked write or destructive asks by default; see Tool approvals.

The path through these pages

1. Connector definition reference: every member of the definition, with the auth methods, settings fields and the access marking.
2. Runtime context: ctx.http, ctx.sql, ctx.mail, ctx.state, logging and errors, with the limits Console enforces.
3. Test a connector package: the test host and its fakes.
4. Build, sign and publish: cpc, the .cpkg format, signing keys and distribution.

To see the result from the user's side, read Install connector packages and Create and connect a connector.