# 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:**
```bash
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

```bash
# 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

```bash
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:

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

Response:
```json
{
  "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](../reference/api.md) 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.