Files
waggle-os/docs/guides/connectors.md
shumeiko.it 834096146e 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.
2026-11-01 01:58:42 +01:00

99 lines
4.3 KiB
Markdown

# Connectors and channels
**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.
## The Vault
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.
Provider keys added in Settings → Models land in the Vault too.
## Native connectors
Waggle has 30 built-in connectors:
| 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 |
### Connect a service
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.
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.
**Disconnect** removes the credentials from the Vault. Connector Hub also shows each
connector's health and a history of what was done with it.
Composio keeps the credentials for the services behind it on Composio's side, not in Waggle's
Vault.
## Approvals
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**.
**Settings** → **Permissions** sets how often Waggle asks:
| 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 |
## Channels
**Settings** → **Channels** connects messaging apps, so you can message Waggle from them.
| 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 |
### WhatsApp
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.
- 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.
## Troubleshooting
- **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.