Connectors Overview

Connectors keep CortexDB in sync with the systems your team already uses — chat, tickets, docs, code, CRM. There are 18 connectors, and every one runs two ways:

• Self-hosted (recommended) — the cortexdb-connectors package ships a cortexdb-sync CLI you run yourself against your own CortexDB instance. Nothing leaves your infrastructure, and it's the path documented on each connector page and below. Point it at http://localhost:3141 (or your server's URL) and it ingests into your scopes.
• Managed — alternatively, CortexDB can run the connector as a worker on its infrastructure; configure it once from your dashboard and it handles webhook registration, retries, backfill, and idempotency.

Install the CLI

pip install cortexdb-connectors

This provides the cortexdb-sync command with six subcommands:

Add a connector's optional extra to pull its dependencies, e.g. pip install 'cortexdb-connectors[slack]'.

Point it at your instance

CortexDB credentials resolve in precedence order: CLI flags → environment → ~/.cortexdb/state.json (written by cortexdb init). The relevant global flags:

cortexdb-sync \
  --api-url http://localhost:3141 \
  --api-key <PASETO-or-CORTEX_API_KEY> \
  --actor user:alice \
  --scope-template "org:acme/source:slack/channel:{channel}" \
  sync slack

cortexdb-sync auth prints the resolved (redacted) credentials so you can confirm what it will use.

Configure a source

Each connector needs its third-party credentials. Two ways to supply them:

1. Environment variables — run cortexdb-sync list to see exactly which are required per connector (they're the required env column on each connector page).
2. A YAML --config file keyed by connector slug — useful for selectors that aren't plain auth (e.g. Jira's project_keys, Teams' team_ids).

Run modes

# One-shot: sync everything new since the last cursor, then exit
cortexdb-sync sync slack

# Watch: loop forever, sleeping --interval seconds between cycles
cortexdb-sync watch slack --interval 60

# Serve: receive real-time webhooks (create/update/delete)
cortexdb-sync serve

Cursor state persists in ~/.cortexdb/sync_state.json (per-connector), so re-running picks up where the last cycle left off. --state-file overrides the location, and CORTEX_SYNC_STATE_PATH is the environment equivalent — useful when the connector runs in a container with a mounted state volume. (The packaged worker entrypoint reads SYNC_INTERVAL, default 300 seconds, for its own loop.)

Webhooks (real-time)

cortexdb-sync serve runs a receiver for connectors that support push. Verification is per-connector: some sources sign their payloads, while sources that don't (e.g. tl;dv) use a static shared secret header instead. The receiver reads these environment variables:

A secret left unset defaults to empty, which disables verification for that source — set one for every connector you actually expose. Individual connector pages cover the webhook path and payload details.

Cross-connector notes

• Idempotency keys are per-connector and version-aware where the source supports edits (a content-version or updated timestamp segment lets an edit land as a new version rather than colliding). The exact shape is on each connector page.
• Self-host auth may differ from the dashboard. Some connectors use OAuth apps in the managed dashboard but simpler token/password auth self-hosted (GitHub, Salesforce, ServiceNow). Each page notes both.

The 18 connectors