Credential Gateway: Secure Access to Google Services
Gmail, Google Calendar, Google Contacts, and other services require OAuth credentials. This recipe sets up secure access that email-to-brain and calendar-to-brain depend on.IMPORTANT: Instructions for the Agent
You are the installer. Other recipes depend on this one. If the user wants email-to-brain or calendar-to-brain, set up credential-gateway FIRST. Two options, both free:- Option A: ClawVisor — handles OAuth, token refresh, and encryption for you. No token management. If you use multiple Google services, set up ClawVisor once and all recipes use it.
- Option B: Google OAuth directly — no extra service, but you manage tokens yourself. Good if you don’t want another dependency.
Setup Flow
Step 1: Choose Your Gateway
Ask the user: “How do you want to connect to Google services (Gmail, Calendar)? Option A: ClawVisor (recommended) ClawVisor handles OAuth, token refresh, and encryption. Set it up once and email-to-brain, calendar-to-brain, and any future Google service recipes all use the same credentials. No token management on your end. Option B: Google OAuth2 directly Connect to Google APIs directly. No extra service. But you manage OAuth tokens yourself (they expire, need refresh).”Option A: ClawVisor Setup
Tell the user: “1. Go to https://clawvisor.com and create an account 2. Create an agent (or use existing one) 3. Activate the services you need:- Gmail (for email-to-brain)
- Google Calendar (for calendar-to-brain)
- Google Contacts (for enrichment)
- Create a standing task with a broad purpose. CRITICAL: be EXPANSIVE. Good purpose: ‘Full executive assistant access to Gmail, Calendar, and Contacts including inbox triage, event listing, contact lookup, and historical data access for all connected Google accounts.’ Bad purpose: ‘email triage’ — too narrow, blocks legitimate requests.
- Copy the Gateway URL and Agent Token and paste them to me”
Option B: Google OAuth2 Setup
Tell the user: “I need Google OAuth2 credentials. Here’s exactly how:- Go to https://console.cloud.google.com/apis/credentials (create a Google Cloud project if you don’t have one — it’s free)
- Click ’+ CREATE CREDENTIALS’ at the top > ‘OAuth client ID’
- If prompted to configure the consent screen:
- User type: External (or Internal for Google Workspace)
- App name: ‘ModusBrain’ (anything works)
- Scopes: add the ones you need:
- Gmail:
https://www.googleapis.com/auth/gmail.readonly - Calendar:
https://www.googleapis.com/auth/calendar.readonly - Contacts:
https://www.googleapis.com/auth/contacts.readonly
- Gmail:
- Test users: add your own email address
- Create the OAuth client ID:
- Application type: Desktop app
- Name: ‘ModusBrain’
- Click ‘Create’ — copy the Client ID and Client Secret
- Enable the APIs you need:
- Gmail: https://console.cloud.google.com/apis/library/gmail.googleapis.com
- Calendar: https://console.cloud.google.com/apis/library/calendar-json.googleapis.com Click ‘Enable’ on each one.
Step 2: Log Setup Completion
Tricky Spots
- ClawVisor task purpose must be EXPANSIVE. “Email triage” is too narrow and blocks legitimate requests. Use a broad purpose that covers everything you might want to do with email. The intent verification model checks each request against the purpose. Narrow = blocked.
-
Google OAuth tokens expire. Access tokens last ~1 hour. The refresh token
is long-lived but can be revoked. Store both in
~/.modusbrain/google-tokens.jsonwith 0600 permissions. The script should auto-refresh on 401. - Google consent screen in “Testing” mode limits to 100 users and tokens expire weekly. For personal use this is fine. For production, publish the app.
- Multiple Google accounts. If you have work + personal Gmail, you need to authorize each one separately in the OAuth flow. ClawVisor handles this automatically.
How to Verify
- ClawVisor:
curl $CLAWVISOR_URL/healthreturns OK. - Google OAuth: Tokens exist at
~/.modusbrain/google-tokens.json. - Gmail access: Run the email collector — it should pull recent messages.
- Calendar access: Run the calendar sync — it should pull today’s events.
Cost Estimate
Part of the ModusBrain Skillpack. See also: Email-to-Brain, Calendar-to-Brain