Skip to main content

Google Woekspace app setup

Setting Up Gmail Per Hermes Profile

Each Hermes profile authenticates to its own Google account via OAuth. This guide covers the one-time Google Cloud setup, then the per-profile authorization.

Prerequisites

  • A Hermes profile for each Gmail account you want to connect
  • Access to the Google Cloud Console

Step 1: Create Google OAuth Credentials (one-time)

Do this once in the Google Cloud Console. The same OAuth client can be used across all profiles — each profile just signs in with a different Google account during the auth flow.

  1. Go to Google Cloud Console → Project Selector
  2. Create or select a project
  3. Enable the APIs you need from the API Library:
    • Gmail API
    • Google Calendar API
    • Google Drive API
    • Google Sheets API
    • Google Docs API
    • Google Slides API
    • People API (contacts)
  4. Go to Credentials
    • Create Credentials → OAuth 2.0 Client ID
    • Application type: Desktop app
    • Click Create
  5. If the app is in Testing mode, add each Google account you want to connect as a test user:
    • Go to Audience
    • Test users → Add users → add each Gmail address
  6. Download the JSON file

The client secret is just your app's identity — it doesn't grant access to any account by itself. Access comes from the per-profile auth flow where you sign in with a specific Google account.

Step 2: Place the client secret file

Put the downloaded JSON file in a shared location:

cp ~/Downloads/client_secret_*.json ~/.hermes/shared/google-app-secret.json

Step 3: Authorize each profile

Run these commands for each profile you want to connect. Replace <profile> with the profile name (e.g. james, gabriel, helios-ai).

Important: Use the Hermes venv Python (~/.hermes/hermes-agent/venv/bin/python), not system python3 — the Google libraries require Python 3.10+ and the system Python is 3.9.

3a. Install the client secret into the profile

HERMES_HOME=~/.hermes/profiles/<profile> ~/.hermes/hermes-agent/venv/bin/python ~/.hermes/profiles/<profile>/skills/productivity/google-workspace/scripts/setup.py --client-secret ~/.hermes/shared/google-app-secret.json

3b. Get the authorization URL

HERMES_HOME=~/.hermes/profiles/<profile> ~/.hermes/hermes-agent/venv/bin/python ~/.hermes/profiles/<profile>/skills/productivity/google-workspace/scripts/setup.py --auth-url

This prints an OAuth URL. Open it in your browser and sign in with the Gmail account you want this profile to use.

Note: After approving, the browser will likely show an error on http://localhost:1 — this is expected. Copy the ENTIRE URL from the browser address bar.

Note: The --services and --format json flags are NOT supported in the current version. The setup script uses a fixed set of scopes covering all Google Workspace APIs.

3c. Exchange the authorization code

Paste the redirect URL (or just the code) back:

HERMES_HOME=~/.hermes/profiles/<profile> ~/.hermes/hermes-agent/venv/bin/python ~/.hermes/profiles/<profile>/skills/productivity/google-workspace/scripts/setup.py --auth-code "PASTE_REDIRECT_URL_HERE"

3d. Verify it worked

HERMES_HOME=~/.hermes/profiles/<profile> ~/.hermes/hermes-agent/venv/bin/python ~/.hermes/profiles/<profile>/skills/productivity/google-workspace/scripts/setup.py --check

Should print AUTHENTICATED.

Step 4: Test it

GAPI=~/.hermes/hermes-agent/venv/bin/python

# Search unread emails
HERMES_HOME=~/.hermes/profiles/<profile> $GAPI ~/.hermes/profiles/<profile>/skills/productivity/google-workspace/scripts/google_api.py gmail search "is:unread" --max 5

# List calendar events
HERMES_HOME=~/.hermes/profiles/<profile> $GAPI ~/.hermes/profiles/<profile>/skills/productivity/google-workspace/scripts/google_api.py calendar list

Step 5: Repeat for each profile

Run Steps 3a–3d again for each profile, signing in with a different Gmail account each time. Each profile stores its own token at:

~/.hermes/profiles/<profile>/google_token.json

File Locations Per Profile

File Path Purpose
Client secret ~/.hermes/profiles/<profile>/google_client_secret.json OAuth client credentials (copied from shared file)
OAuth token ~/.hermes/profiles/<profile>/google_token.json Authenticated session (unique per profile)

How It Works

Piece Role
Client secret Your app's identity — "I am Hermes app". Shared across all profiles.
Auth flow (browser sign-in) Pick which Google account to connect. Done once per profile.
Token (google_token.json) Proof that a specific Gmail account authorized the app. One per profile.

One client secret, many tokens — each token tied to whichever Google account signed in during that profile's auth flow.

Troubleshooting

Problem Fix
NOT_AUTHENTICATED Run Steps 3b–3d again
REFRESH_FAILED Token revoked or expired — redo Steps 3b–3d
HttpError 403: access_denied Add the Gmail address as a test user in Google Cloud Console → Audience
HttpError 403: Insufficient Permission Missing API scope — revoke and redo
ModuleNotFoundError / No matching distribution Use the Hermes venv Python: ~/.hermes/hermes-agent/venv/bin/python
zsh: no such file or directory: python Don't use the GSETUP variable pattern in zsh. Call the venv Python directly with HERMES_HOME=... prefix

Revoking Access

To disconnect a profile's Gmail and re-authorize with a different account:

# Revoke
HERMES_HOME=~/.hermes/profiles/<profile> ~/.hermes/hermes-agent/venv/bin/python ~/.hermes/profiles/<profile>/skills/productivity/google-workspace/scripts/setup.py --revoke

# Re-authorize (Steps 3b–3d)
HERMES_HOME=~/.hermes/profiles/<profile> ~/.hermes/hermes-agent/venv/bin/python ~/.hermes/profiles/<profile>/skills/productivity/google-workspace/scripts/setup.py --auth-url

Quick Reference: All Commands For One Profile

PROFILE=james
HH="HERMES_HOME=~/.hermes/profiles/$PROFILE"
PY=~/.hermes/hermes-agent/venv/bin/python
SCRIPT=~/.hermes/profiles/$PROFILE/skills/productivity/google-workspace/scripts/setup.py

# 1. Install client secret
$HH $PY $SCRIPT --client-secret ~/.hermes/shared/google-app-secret.json

# 2. Get auth URL (sign in with the Gmail account for this profile)
$HH $PY $SCRIPT --auth-url

# 3. Exchange code (paste the redirect URL)
$HH $PY $SCRIPT --auth-code "http://localhost:1/?code=4/0A..."

# 4. Verify
$HH $PY $SCRIPT --check

# 5. Test Gmail
GAPI=~/.hermes/profiles/$PROFILE/skills/productivity/google-workspace/scripts/google_api.py
$HH $PY $GAPI gmail search "is:unread" --max 5
Back to top