Connectors

Link Cargo to your CRM, warehouse, enrichment providers, and AI models with defineConnector — the foundation every model, tool, and agent builds on.

A connector is an authenticated link to an external system — a CRM, warehouse, enrichment API, or LLM provider. Creating one auto-provisions a dataset that data models source from, and exposes that integration’s actions to your workflows and agents.

Define a connector

connectors/hubspot.ts

import { defineConnector, secret } from "@cargo-ai/cdk";

export const hubspot = defineConnector("hubspot", {
  integration: "hubspot",
  config: { method: "privateApp", accessToken: secret("HUBSPOT_API_KEY") },
});

The integration slug selects which system to connect; config is a typed, per-integration shape (run cargo-ai project types to type it against your workspace). The connector handle carries deferred tokens — hubspot (the handle), hubspot.datasetUuid — that you pass into models and other resources.

Secrets vs. config

Use secret() or workspaceEnv() for credentials, and env() for non-secret config you want tracked:

config: { apiKey: secret("PROVIDER_API_KEY") }        // this deploy's value, never hashed or stored
config: { apiKey: workspaceEnv("PROVIDER_API_KEY") }  // read from the workspace on every use
config: { region: env("PROVIDER_REGION") }            // tracked in the content hash

The two credential helpers differ in where the value lives. secret() reads process.env at deploy time and sends the value, so rolling it means re-deploying. workspaceEnv() sends only a pointer at the workspace’s environment variables, which Cargo resolves on every run — so rotating it there takes effect immediately, with no deploy. A connector config is one of the two places that accepts a pointer.

Always use secret() or workspaceEnv() — never env() — for credentials. Both are excluded from the content hash and from the deploy state. env() bakes the value into the hash, so rotating it reads as drift.

See Secrets & environments for the full rules and the CARGO_* variables the CLI reads.

OAuth and existing connectors

Some integrations authenticate via OAuth in the browser rather than a static key. Adopt an already-connected instance by slug instead of re-creating it:

connectors/openai.ts

import { defineConnector } from "@cargo-ai/cdk";

export const openai = defineConnector("open_ai", {
  integration: "openAi",
  default: true,
});

default: true links an existing connector (e.g. one authorized through an OAuth flow in the workspace) rather than creating a new one. An adopted connector is read-only: deploys never push name, config, rateLimit or cacheTtlMilliseconds to it, so the credentials authorized outside the repo are never overwritten. A later destroy releases it instead of deleting it.

Aside from unified models — which Cargo generates and a project can only bind to, never create — this is the only implicit link a project makes. Every other resource is created outright: if one with the same slug or name already exists, the deploy fails rather than adopting it. To bring an existing workspace resource under code, use cargo-ai project pull, or cargo-ai project import <id> <uuid> to bind one resource explicitly.

Using a connector

Once defined, a connector powers three things:

• Data models source from its dataset — see Models and Extractors.
• Workflows call its actions via uses.<key>.<action>() (declared in uses) — see Workflows.
• Agents invoke its actions by referencing connector.actions.<slug> in their uses — see Agents.

Browse every available integration and its action slugs in the Integrations section, or discover them live with cargo-ai connection integration get <slug> (or generate typed editor autocomplete with cargo-ai project types).

From the CLI

cargo-ai connection integration list          # available integrations
cargo-ai connection connector list            # your connected instances
cargo-ai connection connector create \
  --name "HubSpot - Prod" --slug hubspot_prod --integration-slug hubspot \
  --config '{ ... }'

Using the UI

In the web app, go to Settings → Integrations → Add connection, pick the integration, and complete the auth flow (API key or OAuth). Connectors created in the UI are bound into code by slug, or with default: true. From the terminal, cargo-ai project add connector/<integration> authorizes one in the browser and writes the file for you.

Slug rules

Connector slugs are snake_case (my_source) and validated at define time, so a bad slug fails in plan rather than mid-deploy.