Personal AI, On Personal Devices
Python
docs: add Channels & Connectors troubleshooting guide
Jon Saad-Falconbec38ebc1dca
diff --git a/docs/user-guide/channels-and-connectors.md b/docs/user-guide/channels-and-connectors.mdnew file mode 100644index 00000000..99ccd605--- /dev/null+++ b/docs/user-guide/channels-and-connectors.md@@ -0,0 +1,351 @@+# Channels & Connectors++OpenJarvis connects to your personal data sources to power Deep Research. This guide walks you through setting up each connector and troubleshooting common issues.++---++## Gmail++**What it indexes:** Email messages and threads from your Gmail inbox.++### Setup (App Password — recommended)++1. **Enable 2-Factor Authentication** on your Google account:+ [Open Google Security Settings →](https://myaccount.google.com/signinoptions/two-step-verification)++2. **Generate an App Password** for "Mail":+ [Open App Passwords →](https://myaccount.google.com/apppasswords)+ - Select "Mail" as the app+ - Copy the 16-character password (e.g. `qpde kebj evhy zljc`)++3. **Connect in OpenJarvis:**+ - Desktop/Browser: Agents → your agent → Channels tab → Gmail → Reconnect+ - CLI: `uv run jarvis connect gmail_imap`+ - Enter your email address and the app password++### Troubleshooting++| Issue | Solution |+|-------|----------|+| "App Passwords" page not available | Enable 2-Factor Authentication first |+| Login failed | Make sure you're using the app password, not your regular Google password |+| No emails syncing | Check that IMAP is enabled: [Gmail Settings → Forwarding and POP/IMAP](https://mail.google.com/mail/u/0/#settings/fwdandpop) |+| Only getting recent emails | By default, the last 500 emails are synced. Increase with `max_messages` config |++---++## Google Drive++**What it indexes:** Documents, Sheets, PDFs, and other files from your Drive.++### Setup++1. **Go to Google Cloud Console** and create a project (or use an existing one):+ [Create Project →](https://console.cloud.google.com/projectcreate)++2. **Enable the Google Drive API:**+ [Enable Drive API →](https://console.cloud.google.com/apis/library/drive.googleapis.com)++3. **Create OAuth credentials:**+ [Open Credentials →](https://console.cloud.google.com/apis/credentials)+ - Click "Create Credentials" → "OAuth 2.0 Client ID"+ - Choose "Desktop app" as the application type+ - Copy the **Client ID** and **Client Secret**++4. **Add yourself as a test user** (required while app is unverified):+ [Open OAuth Consent Screen →](https://console.cloud.google.com/apis/credentials/consent)+ - Scroll to "Test users" → click "+ Add Users"+ - Add your Gmail address (e.g. `[email protected]`)++5. **Add the redirect URI:**+ [Open Credentials →](https://console.cloud.google.com/apis/credentials)+ - Click your OAuth Client → Authorized redirect URIs+ - Add: `http://localhost:8789/callback`++6. **Connect in OpenJarvis:**+ - Desktop/Browser: Agents → Channels tab → Google Drive → paste Client ID and Client Secret+ - Your browser will open Google's consent page → grant read-only access+ - You'll see "Authorization successful!" → Drive data starts syncing++### Troubleshooting++| Issue | Solution |+|-------|----------|+| "Access blocked: app has not completed verification" | Add your email as a test user (step 4 above) |+| "Error 400: redirect_uri_mismatch" | Add `http://localhost:8789/callback` as an authorized redirect URI (step 5) |+| "Error 403: access_denied" | Make sure you selected "Desktop app" when creating the OAuth client |+| Connected but 0 files | Check that you granted Drive read access in the consent screen. Try reconnecting. |+| Token expired | Access tokens expire after 1 hour. Reconnect to get a new one. (Auto-refresh coming soon.) |++---++## Google Calendar++**What it indexes:** Events, meetings, and calendar entries.++### Setup++Same as Google Drive — use the same Google Cloud project and OAuth client.++1. **Enable the Google Calendar API:**+ [Enable Calendar API →](https://console.cloud.google.com/apis/library/calendar-json.googleapis.com)++2. Follow steps 3-6 from the Google Drive section above (same Client ID/Secret works)++### Troubleshooting++Same as Google Drive. Additionally:++| Issue | Solution |+|-------|----------|+| Only seeing primary calendar | The connector reads all calendars you have access to |+| Missing shared calendars | Shared calendars from other users may require additional permissions |++---++## Google Contacts++**What it indexes:** People, phone numbers, emails, and contact information.++### Setup++Same as Google Drive — use the same Google Cloud project and OAuth client.++1. **Enable the People API:**+ [Enable People API →](https://console.cloud.google.com/apis/library/people.googleapis.com)++2. Follow steps 3-6 from the Google Drive section above++---++## Slack++**What it indexes:** Channel messages and threads from your Slack workspace.++### Setup++1. **Go to Slack App Settings:**+ [Open Slack Apps →](https://api.slack.com/apps)++2. **Create a new app** (or use existing):+ - Click "Create New App" → "From scratch"+ - Name it (e.g. "OpenJarvis") and select your workspace++3. **Add OAuth scopes:**+ - Go to "OAuth & Permissions"+ - Under "Bot Token Scopes", add: `channels:history`, `channels:read`, `users:read`++4. **Install to workspace:**+ - Click "Install to Workspace" → Authorize+ - Copy the **Bot User OAuth Token** (starts with `xoxb-`)++5. **Connect in OpenJarvis:**+ - Desktop/Browser: Agents → Channels tab → Slack → paste the bot token+ - CLI: `uv run jarvis connect slack`++### Troubleshooting++| Issue | Solution |+|-------|----------|+| "not_allowed_token_type" | Make sure you're using the **Bot** token (`xoxb-...`), not a user token (`xoxp-`) or session token (`xoxe-`) |+| No messages found | The bot can only see channels it's been added to. Invite it: `/invite @OpenJarvis` in the channel |+| Missing private channels | Add `groups:history` and `groups:read` scopes, then reinstall the app |++---++## Notion++**What it indexes:** Pages, databases, and their content.++### Setup++1. **Create an internal integration:**+ [Open Notion Integrations →](https://www.notion.so/profile/integrations)+ - Click "New integration"+ - Name it (e.g. "OpenJarvis")+ - Select your workspace+ - Copy the **Internal Integration Secret** (starts with `ntn_`)++2. **Share pages with your integration:**+ - Open any Notion page you want indexed+ - Click "..." (top right) → "Connections" → find your integration → click it+ - Repeat for each page or database++3. **Connect in OpenJarvis:**+ - Desktop/Browser: Agents → Channels tab → Notion → paste the token+ - CLI: `uv run jarvis connect notion`++### Troubleshooting++| Issue | Solution |+|-------|----------|+| 0 pages found | You must explicitly share pages with the integration (step 2). The integration can only see pages you've connected. |+| Missing database content | Share the database page itself, not just individual entries |+| Token expired | Notion integration tokens don't expire. If it stops working, regenerate at the integrations page. |++---++## Granola++**What it indexes:** AI meeting notes and transcripts from the Granola app.++### Setup++1. **Open the Granola desktop app** → Settings → API+2. **Copy your API key** (starts with `grn_`)+3. **Connect in OpenJarvis:**+ - Desktop/Browser: Agents → Channels tab → Granola → paste the key+ - CLI: `uv run jarvis connect granola`++### Troubleshooting++| Issue | Solution |+|-------|----------|+| No API key in settings | Granola API is available on Business and Enterprise plans |+| 0 meeting notes | Check that you have meetings recorded in Granola |++---++## Apple Notes++**What it indexes:** Notes from the macOS Notes app.++### Setup (automatic)++1. **Grant Full Disk Access** to your terminal app:+ - Open System Settings → Privacy & Security → Full Disk Access+ - Enable access for Terminal, iTerm, Warp, or the OpenJarvis desktop app++2. Apple Notes is detected automatically when Full Disk Access is granted++### Troubleshooting++| Issue | Solution |+|-------|----------|+| "Not connected" despite Full Disk Access | Restart your terminal app after granting access |+| Notes content is garbled | Some very old notes may have encoding issues. Most notes should be clean. |+| Missing notes | Only notes stored locally or in iCloud are indexed. Notes in third-party accounts (Gmail, Exchange) may not appear. |++---++## iMessage++**What it indexes:** Text messages from the macOS Messages app.++### Setup (automatic)++Same as Apple Notes — requires Full Disk Access.++### Troubleshooting++| Issue | Solution |+|-------|----------|+| "Not connected" | Grant Full Disk Access (see Apple Notes above) |+| Very slow sync | iMessage databases can be large (50K+ messages). First sync may take 10-30 seconds. |+| Missing recent messages | Messages sync from the local database. If Messages.app hasn't synced from iCloud yet, recent messages may be missing. |++---++## Outlook / Microsoft 365++**What it indexes:** Email messages via IMAP.++### Setup++1. **Enable 2-Factor Authentication** on your Microsoft account:+ [Open Microsoft Security →](https://account.microsoft.com/security)++2. **Generate an App Password:**+ - Go to Security → Advanced security options → App passwords+ - Create a new app password++3. **Connect in OpenJarvis:**+ - Desktop/Browser: Agents → Channels tab → Outlook → enter email + app password+ - CLI: `uv run jarvis connect outlook`++### Troubleshooting++| Issue | Solution |+|-------|----------|+| Login failed | Use the app password, not your regular Microsoft password |+| "Authentication failed" | Some Microsoft 365 organizations disable IMAP. Check with your IT admin. |+| Only getting Inbox | Currently only the Inbox folder is synced |++---++## Obsidian++**What it indexes:** Markdown files from your Obsidian vault.++### Setup++1. Find your Obsidian vault folder (the folder containing the `.obsidian` directory)+2. **Connect in OpenJarvis:**+ - Desktop/Browser: Agents → Channels tab → Obsidian → paste the vault path+ - CLI: `uv run jarvis connect obsidian --path /path/to/vault`++### Troubleshooting++| Issue | Solution |+|-------|----------|+| "Not connected" | Double-check the path exists and contains a `.obsidian` folder |+| Missing files | Only `.md`, `.markdown`, and `.txt` files are indexed. Binary files and images are skipped. |+| Slow sync for large vaults | Vaults with 1000+ files may take a minute to sync |++---++## Dropbox++**What it indexes:** Files and documents from your Dropbox.++### Setup++1. **Create a Dropbox app:**+ [Open Dropbox App Console →](https://www.dropbox.com/developers/apps/create)+ - Choose "Scoped access" → "Full Dropbox"++2. **Set permissions:**+ - Under Permissions tab, enable `files.metadata.read` and `files.content.read`++3. **Generate an access token:**+ - Go to Settings tab → "Generated access token" → Generate++4. **Connect in OpenJarvis:**+ - Desktop/Browser: Agents → Channels tab → Dropbox → paste the token+ - CLI: `uv run jarvis connect dropbox`++### Troubleshooting++| Issue | Solution |+|-------|----------|+| "Invalid access token" | Dropbox short-lived tokens expire after 4 hours. Generate a new one. |+| Missing files | Check that you enabled the correct permissions (step 2) |++---++## General Troubleshooting++### All connectors++| Issue | Solution |+|-------|----------|+| "Connected — no data synced yet" | The connector authenticated but hasn't synced. Try running `uv run jarvis deep-research-setup --skip-chat` to trigger a sync. |+| Data seems stale | Connectors sync on demand. Run the setup command or click "Reconnect" to re-sync. |+| Want to reset a connector | Click "Reconnect" in the Channels tab, or delete the credential file at `~/.openjarvis/connectors/{connector}.json` |++### Where credentials are stored++All credentials are saved locally at `~/.openjarvis/connectors/` with file permissions `0600` (owner-only read/write). No credentials are sent to any server — everything stays on your device.++```+~/.openjarvis/connectors/+├── gmail_imap.json # Gmail email + app password+├── gdrive.json # Google Drive OAuth tokens+├── gcalendar.json # Google Calendar OAuth tokens+├── gcontacts.json # Google Contacts OAuth tokens+├── slack.json # Slack bot token+├── notion.json # Notion integration token+├── granola.json # Granola API key+├── outlook.json # Outlook email + app password+└── dropbox.json # Dropbox access token+```diff --git a/mkdocs.yml b/mkdocs.ymlindex a90a5e9c..ddf85eec 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -165,6 +165,7 @@ nav:- Design Principles: architecture/design-principles.md- API Reference: api-reference/- User Guide:+ - Channels & Connectors: user-guide/channels-and-connectors.md- Tools: user-guide/tools.md- External MCP Servers: user-guide/mcp-external-servers.md- Leaderboard: leaderboard.md