Connect Hermes Agent to Google Workspace

Step 1: Create a Google Cloud project

Open the Google Cloud Console and:

• Click the project dropdown in the top bar and select New Project
• Name it something recognizable like "Hermes Agent Integration"
• Select your organization if applicable, or leave as "No organization"
• Click Create

Once created, make sure the new project is selected in the dropdown.

Step 2: Enable the relevant APIs

In the Google Cloud Console, go to APIs & Services → Library. Search for and enable each API you want Hermes to use:

• Gmail API — Read, send, and manage email
• Google Calendar API — Create events, check availability, manage schedules
• Google Drive API — List, search, upload, and organize files
• Google Docs API — Create and edit documents
• Google Sheets API — Read and write spreadsheet data

Enable only the APIs you actually plan to use. This follows the principle of least privilege and simplifies your security review.

Step 3: Create OAuth credentials

Go to APIs & Services → Credentials and:

• Click Create Credentials → OAuth client ID
• If prompted, configure the OAuth consent screen first:
  • Choose External user type (or Internal if you're on Google Workspace)
  • Fill in the app name (e.g., "Hermes Agent"), user support email, and developer contact
  • Add the scopes you'll use (you can start minimal and add later)
  • Add your own email as a test user during development
• For Application type, choose Desktop app
• Name it "Hermes Agent Desktop Client"
• Click Create

Download the JSON file containing your client ID and client secret. Store it securely — this file grants access to your Google data.

Step 4: Configure Hermes for Google integration

Place the downloaded OAuth credentials file in your Hermes config directory:

cp ~/Downloads/client_secret_*.json ~/.hermes/google-credentials.json

Then update ~/.hermes/config.yaml:

integrations:
  google:
    enabled: true
    credentials_file: ~/.hermes/google-credentials.json
    scopes:
      - gmail.readonly
      - gmail.send
      - calendar.events
      - drive.readonly
      - drive.file
      - documents.readwrite
      - spreadsheets.readwrite

Step 5: Authenticate and test

Run the Hermes setup command for Google integration. This opens a browser for the OAuth flow:

hermes setup --google

Your browser will open to a Google consent screen. Review the permissions and click Allow. Hermes stores a refresh token so it can access your Google data without re-authenticating each time.

Test the connection with a simple calendar query:

hermes
> What's on my calendar for tomorrow?

If Hermes returns your Google Calendar events, the integration is working. Try additional commands:

# Search Gmail
> Find emails from [email protected] about the Q3 report

# Work with Drive
> List my most recently modified Google Docs

# Create a spreadsheet
> Create a sheet called "Weekly Metrics" with columns for Date, Metric, and Value

Scoping advice: least privilege

When configuring scopes, grant only what Hermes actually needs:

• Use gmail.readonly unless Hermes needs to send email
• Use drive.file instead of drive to limit access to files Hermes creates or that you explicitly open with it
• For Calendar, calendar.events covers most use cases without full calendar management
• If you only need document creation, skip Docs and Sheets and use Drive file uploads instead

You can always add scopes later if your needs change. Revoking unused scopes reduces your exposure.

Canadian data residency notes

Google Workspace data is processed on Google's infrastructure. For Canadian organizations:

• Data storage: Google may store your data in US or global data centres. Google Workspace customers can choose a data region on certain plans, but not all data types are covered.
• PIPEDA considerations: If you handle personal information subject to PIPEDA, review Google's data processing terms and your organization's policies before connecting Hermes.
• OAuth tokens: The refresh token stored in ~/.hermes/ is as sensitive as a password. Ensure your machine is properly secured.
• What stays local: Hermes Agent itself runs on your machine. Prompts are processed by your configured model provider — not by Google — unless the model provider also happens to be Google (e.g., Gemini).
• Recommendation: For regulated data, consider using local-only workflows and avoid sending sensitive information through cloud APIs.