# How to set up Hermes Agent on Google Chat

> Connect Hermes through a Google Chat app and Pub/Sub pull subscription, restrict users and optionally enable native file uploads.

Canonical: https://hermeswatcher.com/learn/hermes-agent-google-chat-setup  
Section: Learn · Messaging & the gateway  
Last reviewed: Oct 29, 2026  
Basis: Explained from the official Hermes Agent docs and repository (Nous Research). Steps follow the linked official sources.

## What you need

Hermes receives Google Chat events through a Pub/Sub pull subscription and sends replies through the Chat API. Pub/Sub is the Google message queue; pull means Hermes connects out to collect events. This documented route needs no public callback URL or tunnel.

Native Windows on ARM64 is not supported: the Google Chat dependency (google-cloud-pubsub/grpcio) has no build for that platform.

If you enable optional file access, complete the [Google OAuth consent configuration](https://developers.google.com/workspace/guides/configure-oauth-consent) before creating its Desktop client. Follow Google's instructions for your app's audience and test users.

- Hermes Agent installed with a model provider configured.
- A Google Workspace account with access to Chat and permission to configure an app. A Gmail-only account is not the account type described by the Hermes setup.
- A Google Cloud project where you can enable APIs, create a service account and manage topic and subscription permissions.
- A computer that remains on and connected while you want Hermes to answer.

The [Google Pub/Sub quickstart](https://developers.google.com/workspace/chat/quickstart/pub-sub) lists a Business or Enterprise Workspace account and a Cloud project with billing enabled. The Hermes page describes broader Workspace availability and small-volume free usage. Confirm your edition and billing requirements before proceeding; this guide makes no free-service promise.

## Create the Cloud project and service account

At [Google Cloud Console](https://console.cloud.google.com), create or choose the intended project and record its project ID. Under APIs & Services → Library, enable Google Chat API and Cloud Pub/Sub API.

Under IAM & Admin → Service Accounts, create hermes-chat-bot. A service account is an application identity, separate from the people chatting with the bot. Skip broad project-level Pub/Sub roles; the permissions below belong on individual resources.

- Open the service account, then Keys → Add key → Create new key. Select JSON and download the key file.
- Place the key on the Hermes host in a private location, such as ~/.hermes/google-chat-sa.json. Only the account running Hermes should be able to read it. Keep it out of Git, chat messages and screenshots.
- If key creation is blocked by organization policy, ask the administrator to review the requirement. Do not weaken organization policy as a routine setup fix.

The [Google service account key guide](https://docs.cloud.google.com/iam/docs/keys-create-delete) documents the JSON key flow and organization restrictions. This key authenticates Hermes to Google; it does not authorize a human to operate the agent.

On Linux or macOS, restrict the downloaded service-account key with `chmod 600 ~/.hermes/google-chat-sa.json`.

## Create the topic, pull subscription and permissions

- Under Pub/Sub → Topics, create a topic with ID hermes-chat-events.
- Create a subscription for that topic with ID hermes-chat-events-sub, delivery type Pull and message retention of 7 days, following the Hermes page.
- On the topic, grant Pub/Sub Publisher to chat-api-push@system.gserviceaccount.com. This is the publisher documented for a Chat app that is not a Workspace add-on.
- On the subscription, grant your own service account Pub/Sub Subscriber and Pub/Sub Viewer. Viewer is needed for the Hermes startup reachability check.
- Record the full subscription name: projects/<your-project>/subscriptions/hermes-chat-events-sub. Replace the project placeholder with your project ID.

Keep the resources distinct: Google Chat publishes to the topic, while Hermes reads the subscription. The current Google quickstart has separate add-on and non-add-on instructions. Use its [Chat apps that are not add-ons](https://developers.google.com/workspace/chat/quickstart/pub-sub#chat-apps-that-arent-add-ons:-build-a-google-chat-app-with-pubsub) section with this Hermes route.

## Configure the Chat app for a private first conversation

Open APIs & Services → Enabled APIs & Services → Google Chat API → Configuration. The current Google instructions for a standalone Chat app say to clear Build this Chat app as a Google Workspace add-on and confirm Disable if that option is enabled.

- Enter the app name, a public avatar image URL and a short description.
- Enable Join spaces and group conversations. The Hermes page also says to enable Receive 1:1 messages where that setting is shown.
- For Connection settings, choose Cloud Pub/Sub and enter projects/<your-project>/topics/hermes-chat-events with your actual project ID.
- Under Visibility, make the app available to specific people and groups in your domain and include your own Workspace email. Keep the first conversation restricted.
- Save the configuration. This guide does not require a public Marketplace listing.

Follow the [Google non-add-on configuration instructions](https://developers.google.com/workspace/chat/quickstart/pub-sub#publish-app) for the current console layout. Do not mix its generated add-on publisher identity with the standalone route above.

## Choose who can talk to it and connect Hermes

Run the wizard and select Google Chat, or add these variables to your active profile .env. Use an absolute path to the service account JSON that the Hermes process can read.

The platform docs use `~/.hermes/.env` for the default profile on Linux, macOS and WSL. Native Windows normally uses `%LOCALAPPDATA%\hermes\.env`. If you use a custom Hermes home or another profile, edit that profile's file instead. Replace every example value before starting.

Use your own Workspace email in `GOOGLE_CHAT_ALLOWED_USERS` first. Separate additional permitted emails with commas. App visibility and resource permissions do not replace this sender list. An allowlist is the list of people permitted to use the agent. Authorize only people you trust with its enabled tools and files. Keep `GATEWAY_ALLOW_ALL_USERS` unset or false and review existing global allowlists and pairing approvals, which can also grant access. Do not expect an unknown sender to receive a pairing code when an allowlist is set.

Setup wizard:

```
hermes gateway setup
```

Profile .env, manual alternative:

```
GOOGLE_CHAT_PROJECT_ID=my-chat-bot-123
GOOGLE_CHAT_SUBSCRIPTION_NAME=projects/my-chat-bot-123/subscriptions/hermes-chat-events-sub
GOOGLE_CHAT_SERVICE_ACCOUNT_JSON=/home/you/.hermes/google-chat-sa.json
GOOGLE_CHAT_ALLOWED_USERS=you@yourdomain.com
```

Use your actual project ID consistently in both resource names. Native Windows needs a real Windows path to the JSON file, rather than the Linux example.

For multiple Hermes profiles, put each profile's Google Chat settings in its own .env. The official docs say secondary profiles do not inherit another profile's project, subscription or service account.

The optional `GOOGLE_CHAT_HOME_CHANNEL` uses a Chat space resource such as spaces/AAAA... for scheduled delivery. Set a real destination where the app is installed before relying on it.

## Prepare dependencies and send a first message

For a source or local install, the official Hermes page gives this maintained dependency installer. Use the [PM-prepared source environment](https://hermes-agent.nousresearch.com/docs/reference/package-management#developer-workflow), then reactivate it before starting the gateway. PM is the Hermes package manager.

Activated Hermes source checkout:

```
python -m plugins.platforms.google_chat.oauth --install-deps
```

Foreground gateway, after reactivation:

```
hermes gateway
```

The docs say published Docker images include the Google Chat extra. Their environment is read-only and on-demand dependency installation is disabled, so the installer is not a way to modify those images.

Look for [GoogleChat] Connected in the gateway logs. In Google Chat, sign in with the Workspace account included in Visibility, choose New chat, search for the app and open its DM. Send Hello from the email in your Hermes allowlist.

The official docs describe a posted working-state marker that is edited into the answer. Confirm the actual reply in Chat. If the app does not appear, revisit Visibility before changing Hermes credentials.

## What it can do

- The official comparison table lists images, files, threads and a typing indicator. It does not list voice, emoji reactions or streaming for Google Chat.
- The working-state indicator is a real Chat message edited into the final response. It does not indicate that text is being streamed as it is generated.
- Replies inside an existing Chat thread stay in that thread and use a separate Hermes session. The documented message limit is 4,000 characters, with longer replies split.
- Basic delivery includes text, inline images by URL and download cards for audio, video and documents. Native Chat file widgets require the optional user authorization below. Native voice notes are not documented as supported.
- The platform page describes Card v2 buttons two ways: its formatting table says Card v2 buttons are unsupported, while its Clarify section describes multiple-choice Card v2 buttons with a text fallback. Card interactions may differ, so keep the text fallback available.

## Optional: enable native file attachments

The Google Chat native file upload requires user credentials, rather than the bot service account. OAuth is the consent flow that lets Hermes upload as the user requesting the file. Start with text chat; add this only if native attachments are needed.

Create a Desktop app OAuth client in the same project. The Hermes page uses APIs & Services → Credentials → Create credentials → OAuth client ID. The current [Google credential instructions](https://developers.google.com/workspace/guides/create-credentials#desktop-app) place this under Google Auth platform → Clients → Create Client → Desktop app. Download its JSON and move it privately to the Hermes host.

Register the client in the default profile, from the prepared source environment:

```
python -m plugins.platforms.google_chat.oauth \
    --client-secret /path/to/client_secret.json
```

Named profile, optional file-access registration:

```
hermes -p <profile> python -m plugins.platforms.google_chat.oauth --client-secret /path/to/client_secret.json
```

In your own DM with the bot:

```
/setup-files
/setup-files start
```

Replace the JSON path before running the command. Each Hermes profile needs its own client registration. Keep the client secret and stored user tokens private.

Open the OAuth URL from the bot and review the consent request. The official flow requests chat.messages.create. After consent, the browser is expected to fail at `http://localhost:1/` with a code in the address bar. Copy that URL or code back only into your own bot DM as `/setup-files <PASTED_URL>`. Do not share the URL elsewhere.

Each user completes this flow in their own DM. Later uploads use that user's token. `/setup-files revoke` removes that user's token without deleting other users' tokens.

## Keep it running

The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep.

After your first message succeeds, stop the foreground gateway with Ctrl+C. For a normal host installation, the official gateway docs give these service commands:

Install, start and inspect the host service:

```
hermes gateway install
hermes gateway start
hermes gateway status
```

Linux uses systemd, macOS uses launchd, and Windows uses a Scheduled Task at logon. On a headless Linux host using a user service, the docs give `sudo loginctl enable-linger $USER` to keep it available after logout. Windows Task Scheduler does not restart a gateway that crashes after its launcher exits.

In a container, use the documented container startup and restart policy instead of installing a host user service. For hosting choices, see [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md).

## If it doesn't answer

- App is missing from search: confirm your Workspace account is included in the Chat API Visibility settings and that you selected the standalone app configuration.
- No events reach the subscription: check the exact topic path and the topic Publisher grant for chat-api-push@system.gserviceaccount.com.
- Undelivered messages build up: check the service account JSON path, its subscription Subscriber and Viewer permissions, and whether the gateway is running. Retention is not a promise that every offline message will become an agent reply.
- Configuration validation fails: read the specific variable named in the gateway log. Make sure the selected profile has its own credentials.
- Repeated Pub/Sub stream died messages: check whether credentials were rotated or the subscription was removed. An outbound 403 can mean the bot was removed from its Chat space.
- Text replies work but native uploads do not: finish `/setup-files` for the requesting user. The service account alone cannot perform that upload.
- See [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) for the wider gateway checklist.

## Official docs

Reviewed Oct 29, 2026 against the official Hermes docs.

[Official Hermes Google Chat docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/google_chat)

## Related guides

- [All messaging platforms](https://hermeswatcher.com/messaging.md)
- [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md)
- [How to set up Hermes Agent on Slack](https://hermeswatcher.com/learn/hermes-agent-slack-setup.md)
- [How to set up Hermes Agent on Microsoft Teams](https://hermeswatcher.com/learn/hermes-agent-microsoft-teams-setup.md)
- [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md)

## Related tools

- [Google Workspace: connect everyday work with explicit scopes](https://hermeswatcher.com/tools/google-workspace.md)
- [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md)
- [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md)
- [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md)

## Sources

- [Hermes Agent: Google Chat](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/google_chat)
- [Google: Chat apps behind a firewall with Pub/Sub](https://developers.google.com/workspace/chat/quickstart/pub-sub)
- [Google: create and protect service account keys](https://docs.cloud.google.com/iam/docs/keys-create-delete)
- [Google: desktop OAuth credentials](https://developers.google.com/workspace/guides/create-credentials#desktop-app)
- [Package management: source checkout workflow](https://hermes-agent.nousresearch.com/docs/reference/package-management#developer-workflow)
- [Messaging gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)
- [Gateway authorization source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/authz_mixin.py#L660-L772)
- [Native Windows settings paths](https://hermes-agent.nousresearch.com/docs/user-guide/windows-native)
- [pyproject.toml](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/pyproject.toml)

---

HermesWatcher is an independent guide. It is not affiliated with or endorsed by Nous Research. The [official Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs) and [repository](https://github.com/NousResearch/hermes-agent) from Nous Research are the authority; each page here lists the official sources it was written from. If this site and the official docs disagree, trust the official docs. Index for agents: https://hermeswatcher.com/llms.txt