waggle-os/docs/guides/connectors.md

Connectors

Connectors let Waggle interact with external services -- GitHub, Slack, Google, Jira, and 25 others. Credentials are stored in the encrypted vault, and sensitive operations go through approval gates.

Vault Setup

Before connecting any service, you need to understand the vault. The vault is Waggle's encrypted credential store, using AES-256-GCM encryption. It lives at ~/.waggle/vault.db and is the single source of truth for all secrets.

Adding a Secret to the Vault

From the UI:

1. Go to Settings > Vault
2. Click Add Secret
3. Enter the name (e.g., GITHUB_TOKEN) and value
4. Click Save

From the API:

curl -X POST http://localhost:3333/api/vault \
  -H "Content-Type: application/json" \
  -d '{"name": "GITHUB_TOKEN", "value": "ghp_your_token_here"}'

Suggested Keys

The vault suggests common API key names that are not yet configured:

• ANTHROPIC_API_KEY -- LLM provider
• OPENAI_API_KEY -- LLM provider
• GITHUB_TOKEN -- GitHub API
• SLACK_BOT_TOKEN -- Slack Bot
• JIRA_API_TOKEN -- Jira Cloud
• GOOGLE_API_KEY -- Google services
• TAVILY_API_KEY -- Web search
• BRAVE_API_KEY -- Web search
• SENDGRID_API_KEY -- Email sending
• GOOGLE_CALENDAR_TOKEN -- Calendar access

Native Connectors

Waggle registers 29 native connectors at startup. Each connector has a defined auth type and generates agent tools when credentials are available.

#	Connector	Service	Auth Type
1	GitHub	GitHub API	Bearer token (PAT)
2	Slack	Slack Bot API	Bot token
3	Jira	Jira Cloud	Basic auth (email + API token)
4	Email (SendGrid)	SendGrid API	API key
5	Google Calendar	Google Calendar API	OAuth token
6	Discord	Discord Bot API	Bot token
7	Linear	Linear API	API key
8	Asana	Asana API	Bearer token
9	Trello	Trello API	API key
10	Monday	Monday.com API	API key
11	Notion	Notion API	Integration token
12	Confluence	Atlassian API	Basic auth
13	Obsidian	Local vault	File path
14	HubSpot	HubSpot API	Bearer token
15	Salesforce	Salesforce API	OAuth token
16	Pipedrive	Pipedrive API	API key
17	Airtable	Airtable API	Bearer token
18	GitLab	GitLab API	Bearer token (PAT)
19	Bitbucket	Bitbucket API	App password
20	Dropbox	Dropbox API	OAuth token
21	PostgreSQL	PostgreSQL	Connection string
22	Gmail	Gmail API	OAuth token
23	Google Docs	Google Docs API	OAuth token
24	Google Drive	Google Drive API	OAuth token
25	Google Sheets	Google Sheets API	OAuth token
26	MS Teams	Microsoft Graph API	OAuth token
27	Outlook	Microsoft Graph API	OAuth token
28	OneDrive	Microsoft Graph API	OAuth token
29	Composio	Composio Bridge	API key

Connecting a Service

From the UI

1. Open the Cockpit from the sidebar
2. Scroll to the Connectors section
3. Click Connect on the service you want
4. Enter your credentials (token, API key, or OAuth details)
5. Click Save

The connector status changes from "Disconnected" to "Connected".

From the API

# Connect GitHub with a personal access token
curl -X POST http://localhost:3333/api/connectors/github/connect \
  -H "Content-Type: application/json" \
  -d '{"token": "ghp_your_token_here"}'

# Connect Jira with email + API token
curl -X POST http://localhost:3333/api/connectors/jira/connect \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "your_jira_token", "email": "you@company.com"}'

Disconnecting

curl -X POST http://localhost:3333/api/connectors/github/disconnect

This removes the credentials from the vault and any associated metadata.

Checking Connector Health

Each connector can report its health status:

curl http://localhost:3333/api/connectors/github/health

Response:

{
  "id": "github",
  "name": "GitHub",
  "status": "connected",
  "lastChecked": "2026-03-19T10:30:00.000Z",
  "tokenExpiresAt": null
}

Possible statuses: connected, disconnected, expired, error.

Connector Tools

When a connector is connected (credentials in vault), the agent gains tools for that service. For example, connecting GitHub gives the agent:

• Create issues
• List repositories
• Read file contents
• Create pull requests

The exact tools depend on the connector implementation. Tools appear in the agent's tool list and are visible in the Cockpit capabilities dashboard.

Approval Gates

Sensitive connector operations go through approval gates. When the agent wants to:

• Send an email
• Create a Jira ticket
• Post a Slack message
• Push a git commit

It pauses and shows an approval card in the chat. You see:

• Tool name (e.g., send_email)
• Input (e.g., recipient, subject, body)
• Approve or Deny buttons

The agent waits for your decision before proceeding. This prevents accidental or unwanted actions.

YOLO Mode

If you trust the agent fully, you can enable YOLO Mode in Settings > Permissions. This auto-approves all tool executions without asking. You can also set per-workspace overrides for specific tools.

Composio Bridge

The 29th connector, Composio, is a bridge to 250+ additional services. If you have a Composio account:

1. Add your Composio API key to the vault
2. Connect the Composio connector
3. The agent gains access to Composio-managed services

Composio manages its own credential lifecycle. Note: Composio credentials are stored and managed by Composio's infrastructure, not in Waggle's local vault.

Enterprise Connectors (KVARK)

For enterprise deployments, KVARK provides an additional layer of governed connectors with:

• 28+ document connectors (SharePoint, Box, Google Drive, etc.)
• Permission-aware retrieval (respects source system ACLs)
• Semantic search with reranking
• Full audit trail

Enterprise connectors require a KVARK connection. See the API Reference for the /api/marketplace/enterprise-packs endpoint.

Troubleshooting Connectors

"Connector not found"

The connector ID must match exactly (lowercase). Check GET /api/connectors for the full list.

"Vault not available"

The vault database could not be initialized. Check that ~/.waggle/ is writable and the vault.db file is not corrupted.

Token Expired

Some OAuth-based connectors (Google, Microsoft) have tokens that expire. Re-connect the service to refresh.

No Tools Appearing

After connecting, the agent tools are regenerated on the next chat message. If tools still do not appear, restart the server.