docs: update the capabilities and connectors guides for this edition (P2.4)
Remove KVARK enterprise connectors, the 120+ package count and the curl examples, which no longer work without the session token. Describe Skills Hub, the marketplace scan as the code applies it, MCP Hub, the 30 native connectors, the approval modes, and the messaging channels with the whatsapp-web.js warnings and browser download.
This commit is contained in:
@@ -1,195 +1,98 @@
|
||||
# Connectors
|
||||
# Connectors and channels
|
||||
|
||||
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.
|
||||
**Connectors** let the agent work with services you use, such as GitHub, Slack or Google Drive.
|
||||
**Channels** let you talk to Waggle from a messaging app. Credentials for both are kept in the
|
||||
encrypted Vault on your computer, and actions that change something go through approvals.
|
||||
|
||||
## Vault Setup
|
||||
## The Vault
|
||||
|
||||
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.
|
||||
The Vault stores provider keys, connector credentials and other secrets in
|
||||
`<data>/vault.json`. Each entry is encrypted with AES-256-GCM using a key kept in
|
||||
`<data>/.vault-key`. Open **Vault** to see the stored secrets (names only), add one, reveal a
|
||||
value or delete it.
|
||||
|
||||
### Adding a Secret to the Vault
|
||||
Provider keys added in Settings → Models land in the Vault too.
|
||||
|
||||
**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**
|
||||
## Native connectors
|
||||
|
||||
**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"}'
|
||||
```
|
||||
Waggle has 30 built-in connectors:
|
||||
|
||||
### Suggested Keys
|
||||
| Area | Connectors |
|
||||
|---|---|
|
||||
| Code | GitHub, GitLab, Bitbucket |
|
||||
| Chat | Slack, Discord, Microsoft Teams |
|
||||
| Email and calendar | Gmail, Google Calendar, Outlook (calendar and email), Email via SendGrid |
|
||||
| Documents and files | Google Docs, Google Drive, Google Sheets, OneDrive, Microsoft OneNote, Dropbox, Notion, Confluence, Obsidian |
|
||||
| Projects | Jira, Linear, Asana, Trello, Monday.com, Airtable |
|
||||
| CRM | HubSpot, Salesforce, Pipedrive |
|
||||
| Data | PostgreSQL |
|
||||
| Other services | Composio, a bridge to many more services |
|
||||
|
||||
The vault suggests common API key names that are not yet configured:
|
||||
### Connect a service
|
||||
|
||||
- `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
|
||||
1. Open **Connector Hub** (at the Everything interface level).
|
||||
2. Choose the service and **Connect**.
|
||||
3. Enter what the form asks for: a token, an API key, an email and token, a file path for
|
||||
Obsidian, or a connection string for PostgreSQL. The form links to where the service issues
|
||||
it.
|
||||
|
||||
## Native Connectors
|
||||
When a service is connected, the agent gets tools for it, for example creating issues and
|
||||
pull requests on GitHub or searching pages in Confluence. `/connectors` lists the connected
|
||||
services in a chat.
|
||||
|
||||
Waggle registers 29 native connectors at startup. Each connector has a defined auth type and generates agent tools when credentials are available.
|
||||
**Disconnect** removes the credentials from the Vault. Connector Hub also shows each
|
||||
connector's health and a history of what was done with it.
|
||||
|
||||
| # | 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 |
|
||||
Composio keeps the credentials for the services behind it on Composio's side, not in Waggle's
|
||||
Vault.
|
||||
|
||||
## Connecting a Service
|
||||
## Approvals
|
||||
|
||||
### From the UI
|
||||
When the agent wants to do something with an effect outside the chat, such as sending an email,
|
||||
posting a message, creating a ticket or pushing a commit, it pauses and shows an approval card
|
||||
with the tool and its input. Nothing happens until you choose **Approve** or **Deny**.
|
||||
|
||||
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**
|
||||
**Settings** → **Permissions** sets how often Waggle asks:
|
||||
|
||||
The connector status changes from "Disconnected" to "Connected".
|
||||
| Mode | Behavior |
|
||||
|---|---|
|
||||
| Ask every time | Approve every write, edit and other action that changes something |
|
||||
| Ask only for risky | Writes and edits pass; pushes, installs and cross-workspace actions still ask |
|
||||
| Never ask | Everything passes except a fixed list of critical actions |
|
||||
|
||||
### From the API
|
||||
## Channels
|
||||
|
||||
```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"}'
|
||||
**Settings** → **Channels** connects messaging apps, so you can message Waggle from them.
|
||||
|
||||
# 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"}'
|
||||
```
|
||||
| Channel | What you need |
|
||||
|---|---|
|
||||
| Telegram | A bot token from @BotFather |
|
||||
| Discord | A bot token from the Discord developer portal |
|
||||
| Slack | An app token (Socket Mode) and a bot token |
|
||||
| WhatsApp | A phone to pair by QR code |
|
||||
|
||||
### Disconnecting
|
||||
### WhatsApp
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3333/api/connectors/github/disconnect
|
||||
```
|
||||
WhatsApp runs through `whatsapp-web.js`, an unofficial client that drives WhatsApp Web in a
|
||||
browser. WhatsApp does not allow this and may block the account: link a secondary number, not
|
||||
your personal one.
|
||||
|
||||
This removes the credentials from the vault and any associated metadata.
|
||||
- Waggle uses Chrome, Edge or Chromium if one is installed (or the browser named in
|
||||
`CHROME_PATH`). Otherwise it downloads Chrome for Testing (about 170 MB) into
|
||||
`<data>/browsers` the first time you start WhatsApp. On Linux on ARM, install Chromium
|
||||
yourself.
|
||||
- Start the channel, then scan the pairing QR code with WhatsApp on your phone (Linked
|
||||
devices).
|
||||
- The session is kept as a browser profile in `<data>/channels/whatsapp/session`. It is
|
||||
protected by file permissions, not by the Vault.
|
||||
- Only text messages are handled. Voice, video and other media are ignored.
|
||||
|
||||
## Checking Connector Health
|
||||
## Troubleshooting
|
||||
|
||||
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.
|
||||
- **A connector shows as disconnected after a restart.** Check its health in Connector Hub. If
|
||||
the token expired (common with Google and Microsoft tokens), connect it again with a new one.
|
||||
- **The agent has no tools for a connected service.** Tools are rebuilt on the next message. If
|
||||
they still do not appear, restart Waggle.
|
||||
- **"Vault not available".** Check that the data directory is writable. If `vault.json` cannot
|
||||
be read, Waggle copies it to `vault.json.bak` and treats the Vault as empty; you then need to
|
||||
enter the secrets again.
|
||||
|
||||
Reference in New Issue
Block a user