How to Set Up Hermes Agent as a WhatsApp Bot

Nous Research Hermes Agent is an open-source (MIT-licensed) AI agent with persistent memory, a skill system, scheduled automations, and a messaging gateway that connects to over 20 platforms from a single background process. WhatsApp is one of those platforms, and Hermes connects to it through a built-in bridge based on Baileys, a reverse-engineered WhatsApp Web client.

The bridge emulates a WhatsApp Web session rather than using the official WhatsApp Business API. That means you do not need a Meta developer account, a verified business, or a paid API subscription. You scan a QR code from your phone, and the gateway maintains the session from there.

WhatsApp has over 3.3 billion monthly active users as of early 2026, making it the most widely used messaging platform in the world. Running an AI agent on WhatsApp means you can interact with Hermes from any phone, anywhere, without installing a separate app or opening a terminal.

A few things to know upfront about the WhatsApp bridge:

• Messages stream progressively as the AI generates text
• Long responses split automatically at 4,096 characters per chunk
• Standard Markdown converts to WhatsApp's native formatting (bold, strikethrough, monospace)
• Incoming voice messages get transcribed using Whisper (local, Groq, or OpenAI)
• The gateway denies all incoming messages by default until you configure an allowlist

If you already have Hermes Agent installed, skip to the next section.

Install Hermes

Run the one-line installer, which works on Linux, macOS, WSL2, and Android (Termux):

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Reload your shell after installation:

source ~/.bashrc   # or source ~/.zshrc

Pick a Model Provider

Hermes needs a language model with at least 64,000 tokens of context. Run the provider selection wizard:

hermes model

This supports 25+ providers: Anthropic, OpenAI, Nous Portal, OpenRouter, DeepSeek, and local models through Ollama or any OpenAI-compatible endpoint. Pick whichever provider you already have an API key for.

Verify the Installation

Test that Hermes responds before configuring WhatsApp:

hermes

Send a simple message. If you get a response, the model connection works. Exit with Ctrl+C.

Hermes includes a setup wizard that handles all WhatsApp configuration. You need a phone with WhatsApp installed and a terminal at least 60 columns wide (for the QR code to render properly).

Run the WhatsApp Setup

hermes whatsapp

This launches the WhatsApp-specific wizard. It generates a QR code in your terminal. Open WhatsApp on your phone, go to Settings, then Linked Devices, then Link a Device, and scan the QR code. The bridge establishes a session and saves credentials to ~/.hermes/platforms/whatsapp/session.

You can also use the general gateway wizard, which walks through all platforms:

hermes gateway setup

Select WhatsApp when prompted, and it runs the same pairing flow.

Set Up Access Control

By default, the gateway rejects all incoming WhatsApp messages. You must explicitly allow users before anyone can talk to your bot. Add this to ~/.hermes/.env:

WHATSAPP_ALLOWED_USERS=15551234567

Use the full phone number with country code, without the + sign. To allow multiple users, separate with commas:

WHATSAPP_ALLOWED_USERS=15551234567,447700900123

To allow anyone (useful for testing, not recommended for production):

WHATSAPP_ALLOW_ALL_USERS=true

For unauthorized messages, you can control whether the bot responds with a pairing prompt or stays silent:

### In ~/.hermes/config.yaml
whatsapp:
  unauthorized_dm_behavior: ignore

Setting this to ignore is usually the better choice for a private number, since the bot will not respond to strangers at all.

Start the Gateway

hermes gateway

Send a WhatsApp message to the phone number you paired. If everything is configured, Hermes responds within a few seconds. The session persists across gateway restarts, so you will not need to re-scan the QR code unless you manually unlink the device.

Persist Hermes Agent files across WhatsApp sessions

Free 50 GB workspace with auto-indexing, semantic search, and an MCP endpoint your agent can write to directly. No credit card, no trial expiration.

Sign Up Free

Once the basic connection works, you can fine-tune how Hermes behaves on WhatsApp.

Reply Prefix

By default, Hermes adds a short prefix to each response. To disable it or set your own:

### In ~/.hermes/config.yaml
whatsapp:
  reply_prefix: ""

An empty string removes the prefix entirely. You can also include for line breaks in a custom prefix.

Voice Message Transcription

When someone sends a voice message to the bot, the gateway transcribes it automatically and feeds the text to Hermes. Three transcription backends are supported:

• Local faster-whisper: No API key needed, runs on your machine. Best for privacy.
• Groq Whisper: Set GROQ_API_KEY in ~/.hermes/.env. Fast cloud transcription.
• OpenAI Whisper: Set VOICE_TOOLS_OPENAI_KEY in ~/.hermes/.env. Standard OpenAI pricing.

Hermes can also respond with text-to-speech audio, delivered as MP3 attachments in the chat.

Debugging Connection Issues

If messages are not getting through, enable WhatsApp debug logging:

WHATSAPP_DEBUG=true

This writes raw message events to bridge.log, which helps diagnose pairing failures, message delivery issues, or access control misconfigurations.

If the session goes stale (common after long network interruptions), the gateway handles reconnection automatically for brief blips. For longer outages, re-pair by running hermes whatsapp again.

Run as a Background Service

Running hermes gateway in a terminal works for testing but is not practical long-term. Install the gateway as a service so it starts automatically:

### macOS (launchd agent)
hermes gateway install

### Linux (systemd user service)
hermes gateway install

### Linux (system-wide, starts at boot)
sudo hermes gateway install --system

Use hermes gateway status to check whether the service is running, and hermes gateway stop to shut it down.

Hermes generates files during conversations: PDFs, images, code, data exports. On WhatsApp, those files live on the host machine's filesystem. If the server restarts, the disk fills up, or you want to share a file with someone who is not on WhatsApp, the files are effectively stranded.

This is the gap most WhatsApp bot guides skip. The bot works, but the outputs are locked inside a single machine.

Local Filesystem Limitations

Files saved to the host filesystem are only accessible if you SSH into the server or set up a separate file-sharing mechanism. There is no built-in way to browse, search, or share them with a team. If you run Hermes in Docker, the files disappear when the container is removed unless you mount a volume.

Cloud Storage Options

You can point Hermes at cloud storage to make files persist and stay accessible:

• S3 or GCS buckets: Durable and cheap, but no built-in search, no sharing UI, and files need manual organization.
• Google Drive or Dropbox: Familiar interfaces, but no semantic search, no agent-specific access controls, and API rate limits can bottleneck automated workflows.
• Fast.io: Workspaces designed for agent output. Files are auto-indexed for semantic search when Intelligence Mode is enabled, shareable through branded links, and accessible through a MCP server with 19 consolidated tools. The free tier includes 50 GB of storage, 5,000 AI credits per month, and 5 workspaces with no credit card required.

Why Fast.io Fits This Workflow

When Hermes generates a report, analysis, or any file during a WhatsApp conversation, you want that file to be findable later without remembering the exact filename or date. Fast.io's Intelligence Mode auto-indexes uploaded files, so you can search by meaning rather than filename. A teammate who was not part of the WhatsApp conversation can find the file by asking "What was the Q2 revenue analysis?" in the workspace chat.

The Fast.io MCP server exposes workspace operations through Streamable HTTP at /mcp, which means Hermes can upload files, create shares, and organize workspaces programmatically. The ownership transfer feature lets the agent build and organize a workspace, then hand full control to a human while keeping admin access for future updates.

Files stay versioned, auditable, and accessible from any device, not just the machine running the gateway.

Running a WhatsApp bot through a third-party bridge is not officially supported by Meta. The Baileys library reverse-engineers the WhatsApp Web protocol, which means your account could face restrictions if WhatsApp detects automated behavior. The practical risk is low for personal use, but worth understanding before you deploy.

Use a Dedicated Phone Number

Do not run the bot on your personal WhatsApp number. If the account gets flagged, you lose access to all your personal conversations. Get a cheap prepaid SIM or use a VoIP number that supports WhatsApp registration. Keep your personal number separate.

Protect Session Credentials

The session directory at ~/.hermes/platforms/whatsapp/session contains encryption keys and device credentials. Anyone with access to these files can impersonate your WhatsApp account. Lock down permissions:

chmod 700 ~/.hermes/platforms/whatsapp/session

Never commit the session directory to version control. Add it to .gitignore if you track your Hermes configuration in a repository.

Minimize Automated Outbound Messages

WhatsApp's anti-spam systems flag accounts that send unsolicited messages at scale. Stick to responding to incoming messages rather than proactively messaging contacts. Avoid bulk sends, marketing blasts, or automated outreach to people who have not messaged the bot first.

Access Control Best Practices

Always configure WHATSAPP_ALLOWED_USERS with specific phone numbers rather than using WHATSAPP_ALLOW_ALL_USERS=true. The wildcard setting means anyone who messages the number gets a response, which could expose your agent's capabilities (and API costs) to strangers. Hermes has access to tools including terminal commands, so restricting who can interact with the bot is a real security concern, not just a preference.

Log Hygiene

Hermes partially redacts phone numbers in logs, but review your log retention policy before deploying. Gateway logs can contain message content, timestamps, and user identifiers that may be subject to privacy regulations depending on your jurisdiction.