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:
shumeiko.it
2026-11-01 01:58:42 +01:00
parent eca050328b
commit 834096146e
2 changed files with 144 additions and 352 deletions

View File

@@ -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.