Hermes Google Workspace setup
The easiest useful business agent is not a public chatbot. It is a private operator that can see the same workspace you already use every day.
For most small teams, that workspace is Google Workspace: Gmail, Calendar, Drive, Docs, Sheets, and Contacts. Once Hermes can read those surfaces, it can help you summarize client email, draft replies, find files, prepare meeting notes, and route work into Discord.
This lesson shows the full Hermes agent Google Workspace setup: create a Google Cloud OAuth client, install or enable the google-workspace skill, authorize the account, then verify access with small read-only Gmail, Calendar, and Drive probes.
If you are still choosing the machine where the agent should run, start with the Codex CLI on a VPS guide before authorizing Workspace data. The Google OAuth layer is easier to reason about after the private server, repo workspace, and approval boundary are already boring.
Follow the Always-On Agents course path
Follow the complete public course path, install the skills as you go, and use DevelopJoy when you want the workflow wired into your actual VPS.
Where this fits in the course
Do the private runtime lessons first:
Now we are adding the business API layer. The goal is not to let an agent free-fire emails. The goal is to give Hermes enough authorized context to help you work, while keeping sending, scheduling, sharing, deleting, and document edits approval-gated.
If you need a new workspace
If you are setting this up for a new business or client-ops stack, start with Google Workspace here:
Use your own existing Workspace if you already have one. The important part for this course is that Hermes gets authorized against the Google account that owns the email, calendar, Drive files, and contacts you want it to help with.
What we are connecting
This setup gives Hermes access to:
- Gmail for search, reading, labels, drafts, replies, and sending after approval.
- Calendar for availability checks and meeting invites after approval.
- Drive for searching, reading metadata, uploads, downloads, folders, and sharing after approval.
- Docs for reading and creating briefs or SOPs after approval.
- Sheets for lightweight CRM, status, and reporting tables after approval.
- Contacts / People for stakeholder lookup and routing context.
Keep the first pass broad if you want to follow the whole series. If you only need email and calendar, authorize only those scopes.
Safety rules before auth
Write these down before you connect anything:
That one boundary keeps the system useful without turning it into an autopilot spam cannon.
Quick copy-paste snippets
If you already have a Google Cloud OAuth client JSON file on the Hermes server, this is the short version:
For a narrower Gmail + Calendar setup:
For a named Google account on a shared Hermes machine:
Official references
Keep these open while you set up the OAuth app:
- Google Cloud project selector: https://console.cloud.google.com/projectselector2/home/dashboard
- Google Cloud API Library: https://console.cloud.google.com/apis/library
- OAuth consent audience and test users: https://console.cloud.google.com/auth/audience
- OAuth credentials page: https://console.cloud.google.com/apis/credentials
- Gmail API overview: https://developers.google.com/gmail/api/guides
- Google Calendar API overview: https://developers.google.com/calendar/api/guides/overview
- Google Drive API overview: https://developers.google.com/drive/api/guides/about-sdk
- Google Docs API overview: https://developers.google.com/docs/api/how-tos/overview
- Google Sheets API overview: https://developers.google.com/sheets/api/guides/concepts
- People API overview: https://developers.google.com/people
- Hermes Agent repository: https://github.com/NousResearch/hermes-agent
Create the Google Cloud project
Open the Google Cloud project selector:
https://console.cloud.google.com/projectselector2/home/dashboard
Create a project with a boring name like:
If this is for a client, create a project that clearly belongs to that client or Workspace. Do not mix unrelated businesses into one OAuth project unless you mean to share the same consent configuration.
Enable the APIs
Open the API Library:
https://console.cloud.google.com/apis/library
Enable the APIs you plan to use:
- Gmail API
- Google Calendar API
- Google Drive API
- Google Docs API
- Google Sheets API
- People API
If you are following the full course path, enable all six now. If you only want email and calendar, enable Gmail API and Google Calendar API.
Configure the OAuth consent screen
Open the audience screen:
https://console.cloud.google.com/auth/audience
For a personal or internal operator, keep the app in testing while you are building. Add the Google account you will authorize as a test user.
This matters. If you skip the test user step, Google may return:
That usually means the account is not allowed to use the app yet.
Create the desktop OAuth client
Open credentials:
https://console.cloud.google.com/apis/credentials
Create credentials:
- Click Create Credentials.
- Choose OAuth client ID.
- Application type: Desktop app.
- Name it
Hermes Workspace Operator. - Download the JSON file.
Put the file somewhere safe on the machine where Hermes runs. On a VPS, I usually copy it to a temporary path first, authorize, then store it under the Hermes home directory with tight permissions. Do not commit the downloaded client secret JSON to your repo.
Install or enable the google-workspace skill
If you installed Hermes with the standard skills library, the google-workspace skill should already exist. Check from the machine where Hermes runs:
If the skill is missing, install or sync the current Hermes skills package before continuing. The setup commands below assume this path exists:
That is why searchers often phrase this step as “install google-workspace skill.” The OAuth setup only works after Hermes can find the skill scripts.
Run Hermes Google Workspace setup
On the server where Hermes runs:
If it says AUTHENTICATED, you already have a token. If not, point setup at the downloaded client secret file:
Then generate an authorization URL. For the full course path:
For only Gmail and Calendar:
Open the returned auth_url in the browser while signed into the Google account you want Hermes to use.
After approval, the browser will probably fail on a URL like:
That failure is expected. Copy the entire redirected URL from the browser address bar.
Exchange it on the server:
Then verify:
The goal is:
Verify with a read-only probe
Set the API helper:
Search for recent mail without sending anything:
Check the calendar without creating an event:
Search Drive without changing files:
If those work, Hermes has enough Workspace context for the next lesson.
Definition of done
You are done when:
- A Google Cloud project exists for the operator.
- Gmail, Calendar, Drive, Docs, Sheets, and People APIs are enabled, or you intentionally chose a narrower service set.
- The OAuth desktop client JSON exists on the Hermes machine.
- Hermes setup reports
AUTHENTICATED. - Read-only Gmail, Calendar, and Drive probes work.
- You have a written approval rule for sends, scheduling, sharing, deleting, and edits.
Next lesson
Next, use the connection manually before automating anything. Hermes should first become a safe email-aware work partner: read recent client messages, summarize what matters, check your calendar, and draft replies for approval.
Want this wired into your real Workspace?
The full setup is public. DevelopJoy can help connect Google Workspace, Hermes, Discord, and Linear while keeping sends and scheduling approval-gated.
Build it with us
Pair-programming lab
$100/moHave us build it