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 for each Gmail account

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

Do this in the Google Cloud Console for each Gmail account you want to connect:

  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 (optional — only if you want calendar)
    • Google Drive API (optional)
    • Google Sheets API (optional)
    • Google Docs API (optional)
    • People API (optional — for 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 your Google account as a test user:
    • Go to Audience
    • Test users → Add users → add your Gmail address
  6. Download the JSON file

You can reuse the same OAuth client for multiple profiles/accounts, but each Google account needs to be added as a test user if the app is still in Testing mode.

Step 2: Place the client secret file

Put the downloaded JSON file somewhere accessible. You can use the same file for all profiles:

# Example: save to home directory
cp ~/Downloads/client_secret_*.json ~/google_client_secret.json

Step 3: Authorize each profile

Run this for each profile you want to connect to Gmail. Replace <profile> with the profile name (e.g. james, gabriel).

3a. Set the shorthand

GSETUP="python ~/.hermes/profiles/helper/skills/productivity/google-workspace/scripts/setup.py"

Adjust the skill path if the skill is installed in a different profile. The setup script respects $HERMES_HOME or --hermes-home to target the right profile.

3b. Install the client secret into the profile

hermes --profile <profile> config set google.client_secret ~/google_client_secret.json

Or run the setup script directly:

HERMES_HOME=~/.hermes/profiles/<profile> $GSETUP --client-secret ~/google_client_secret.json

3c. Get the authorization URL

Choose the services you need:

# Email only
HERMES_HOME=~/.hermes/profiles/<profile> $GSETUP --auth-url --services email --format json

# Email + Calendar
HERMES_HOME=~/.hermes/profiles/<profile> $GSETUP --auth-url --services email,calendar --format json

# Full Workspace (email, calendar, drive, sheets, docs, contacts)
HERMES_HOME=~/.hermes/profiles/<profile> $GSETUP --auth-url --services all --format json

This returns a JSON object with an auth_url field. Open that URL 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.

3d. Exchange the authorization code

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

HERMES_HOME=~/.hermes/profiles/<profile> $GSETUP --auth-code "PASTE_THE_URL_OR_CODE_HERE" --format json

3e. Verify it worked

HERMES_HOME=~/.hermes/profiles/<profile> $GSETUP --check

Should print AUTHENTICATED.

Step 4: Test it

GAPI="python ~/.hermes/profiles/helper/skills/productivity/google-workspace/scripts/google_api.py"

# Search unread emails
HERMES_HOME=~/.hermes/profiles/<profile> $GAPI gmail search "is:unread" --max 5

# List calendar events
HERMES_HOME=~/.hermes/profiles/<profile> $GAPI calendar list

Step 5: Repeat for each profile

Run Steps 3a–3e 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 (can be shared)
OAuth token ~/.hermes/profiles/<profile>/google_token.json Authenticated session (unique per profile)
Pending OAuth ~/.hermes/profiles/<profile>/google_oauth_pending.json Temporary during auth flow

Troubleshooting

Problem Fix
NOT_AUTHENTICATED Run Steps 3c–3e again
REFRESH_FAILED Token revoked or expired — redo Steps 3c–3e
HttpError 403: access_denied Add your Gmail address as a test user in Google Cloud Console → Audience
HttpError 403: Insufficient Permission Missing API scope — revoke and redo with broader --services
AUTHENTICATED (partial) New scopes needed — revoke and re-authorize
ModuleNotFoundError Run $GSETUP --install-deps
Advanced Protection blocks auth Workspace admin must allowlist the OAuth client ID

Revoking Access

To disconnect a profile's Gmail:

HERMES_HOME=~/.hermes/profiles/<profile> $GSETUP --revoke

Quick Reference: All Commands For One Profile

# Setup shorthands
PROFILE=james
GSETUP="python ~/.hermes/profiles/helper/skills/productivity/google-workspace/scripts/setup.py"
HH="HERMES_HOME=~/.hermes/profiles/$PROFILE"

# 1. Install client secret
$HH $GSETUP --client-secret ~/google_client_secret.json

# 2. Get auth URL
$HH $GSETUP --auth-url --services email,calendar --format json

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

# 4. Verify
$HH $GSETUP --check

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