Google Services OAuth For Local Installs
This page explains how to connect Google Drive, Docs, Calendar, Sheets, Tasks, and Gmail on a paired local installation.
Paired installations use MindRoom's Google OAuth client, so you do not need a Google Cloud project, callback URLs, or a client secret.
Pair first with mindroom connect, or let mindroom run pair automatically on first run (see Hosted Matrix).
The provisioned client works only when MindRoom is opened on a loopback address (localhost, 127.0.0.1, or ::1).
For an unpaired install, a remote or public address, organization-specific Google policies, or your own consent-screen branding, set up a custom client instead (see Custom Google Cloud Setup).
That page also lists the scopes each Google tool requests and how to restrict which Google accounts may connect.
Choose Providers
Add only the Google tools your agents need.
Each Google Workspace tool has its own connection, and the Connections portal can connect all of an agent's Google Workspace tools with one sign-in.
Google Cloud tools such as google_bigquery use one Google Cloud connection instead; see Providers.
agents:
personal:
display_name: Personal
role: Help with my Google workspace
worker_scope: user_agent
tools:
- google_drive
- google_docs
- google_calendar
- google_sheets
- google_tasks
- gmail
worker_scope decides whose Google account the agent uses.
With user_agent, each Matrix user connects their own account for this agent.
With shared, everyone allowed to use the agent acts through one connected account and may receive its Google data in replies.
See Where Connections Are Stored for every scope.
Connect
- Ask the agent to do something safe with the Google tool, such as listing files or upcoming events.
If the account is not connected, the agent replies with a connect link.
When
config_managerhas just added the Google tool to an agent, use the connect link it returns instead. - Open the link in a browser on the computer where MindRoom runs, not on a phone or another computer, because the link points to
localhost. If you are chatting from another device, open the conversation on the MindRoom computer or copy the complete link into a browser there. - Choose a Google account and approve the scopes for that one service.
- Ask the agent to retry the request.
Without a connect link, open the dashboard Tools tab, choose the agent in the selector, and select Connect on the Google integration. Only agents with a worker scope appear in the selector; for an agent without one, keep Shared deployment credentials selected. The dashboard shows how Google data is handled before you continue. For personal connections from the dashboard, the dashboard must know your Matrix identity; see Connect An Account. Link lifetime, who may connect, disconnecting, and resetting a connection are covered in the OAuth Integration Framework.
Privacy
On a local installation, the provisioning service only supplies the OAuth client configuration. Google sends the authorization response straight to your MindRoom process, which exchanges and stores the tokens, so the provisioning service does not receive your authorization code, tokens, or Google API data. Google data an agent reads goes to your configured AI model provider and Matrix homeserver as part of the conversation. Anyone with administrative or filesystem access to the installation's storage may be able to read the stored credentials and data. See the Privacy Policy for the complete data-handling disclosure.
Troubleshooting
<Google service> needs its OAuth client saved in the MindRoom dashboard before it can connect: the install is not paired and has no custom client. Runmindroom connect, or configure a custom client.OAuth client configuration could not be resolved: MindRoom could not fetch its Google OAuth client, usually because the pairing was revoked or the provisioning service is unreachable. Runmindroom connectagain, or configure a custom client.- Google shows an unverified-app warning or blocks the Google Cloud connection:
cloud-platform.read-onlyis a sensitive scope, so an OAuth client that Google has not verified for it can be limited to test users. The provisioned client is not yours to change, so use a custom client instead, ideally one whose consent screen is Internal to your Google Workspace organization. On your own custom client, you can also add your account as a test user; see Production Verification Follow-up. The provisioned OAuth client is available only when MindRoom is opened on localhost...: open MindRoom onlocalhost, or configure a custom client for remote access.