Building an integration

Integrations connect agents to external services: messaging platforms, APIs, developer tools. This guide is for contributors adding one to the platform, not for users connecting one.

How they work

1. Credentials are stored server-side

   The user pastes a key, or completes an OAuth flow. Nothing is held in the browser.

2. They are injected into agent pods

   Agents see them as environment variables. No custom code is needed to read them.

3. Agents use them

   Directly for API keys and tokens, or through a per-office proxy service when the integration needs a running process.

Three kinds

Kind	When	Examples
Secret-only	The user pastes a credential and it is done	GitHub, Telegram, ElevenLabs
Per-office service	A proxy process must run for the office	Tailscale (SOCKS5), Claude Code (OAuth proxy)
OAuth	The provider supports OAuth	Google Workspace, Claude Code, Codex

Most community integrations are secret-only.

Register it

Integrations are declared in src/lib/integrations/registry.ts. The entry drives the UI, the wizard, the secret storage and the per-agent toggle:

{
  id: 'acme',
  name: 'Acme API',
  description: 'Connect agents to the Acme API for data processing.',
  icon: 'acme',
  category: 'services',          // 'llm' | 'communication' | 'services'
  aliases: ['acme-api'],
  verified: false,               // Mitosis-verified only
  capabilities: ['data_processing'],
  channels: [],                  // Empty for tool-only integrations
  wizard: 'guide',               // 'guide' | 'interactive' | 'oauth' | 'auto'
  guideFile: 'integrations/acme.md',
  requiredSecrets: [{ key: 'ACME_API_KEY', label: 'API Key' }],
  agentEnvVars: ['ACME_API_KEY'],
  officeLevel: false,
  k8sSecretName: (officeId) => `acme-${officeId}`,
}

Optional fields worth knowing

Field	Effect
multiInstance	Users can add several named instances, each with its own secret and per-agent toggle
defaultStatus	Integrations with no DB row default to configured or active instead of pending
comingSoon	Shows a "Coming soon" badge, hides the wizard, and withholds the connect_<id> capability

The bar for removing comingSoon is a complete pipeline: ingest → embed → enrich → visible in the graph with a clickable source_url → navigable by an agent through the SDK. Anything short of that stays gated.

Test it

Connect it on dev.mitosislabs.ai first. Credentials there are scoped to the sandbox and cannot touch production. Then verify the whole path, not just the wizard:

1. The secret lands

   client.integrations.list(officeId) shows it connected.

2. An agent can see it

   Enable it with toggleAgent, then check getCredentials(officeId, agentName).

3. Data reaches the graph

   Ingest something and confirm it is retrievable by cortex_ask, with a working source_url.