--- title: "Deploy Hermes - WhatsApp" description: "Nous Research's Ai Agent Runtime WhatsApp Supervised Gateway" category: "AI/ML" url: https://railway.com/deploy/hermes-whatsapp --- # Deploy Hermes - WhatsApp Nous Research's Ai Agent Runtime WhatsApp Supervised Gateway **[Deploy Hermes - WhatsApp on Railway](https://railway.com/template/hermes-whatsapp)** Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/hermes-whatsapp/manifest.json - **Creator:** OpenSource Templates - **Category:** AI/ML ## Template content ### Hermes https://raw.githubusercontent.com/lobehub/lobe-icons/refs/heads/master/packages/static-avatar/avatars/nousresearch.webp - **Source:** OpenSource-Templates/Hermes ## Documentation # Deploy and Host Hermes Agent (WhatsApp) on Railway Hermes Agent is an autonomous, self-improving AI agent from Nous Research. This flavor connects it to **WhatsApp** via the built-in Baileys bridge (WhatsApp Web–style session, not the official Business Cloud API). Persistent state lives under `/data`, and the image defaults to `nousresearch/hermes-agent:latest`. [![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/hermes-whatsapp) ## About Hosting Hermes Agent on WhatsApp This template runs a single container using `nousresearch/hermes-agent:latest`. A volume at `/data` keeps Hermes home, sessions, and the WhatsApp pairing session across redeploys. WhatsApp is **not** a pure one-click platform like Telegram or Discord: 1. You set env vars and deploy. 2. You open **Railway SSH** and run `hermes whatsapp` to scan a QR code from your phone. 3. The session is saved under `/data` and reused on later restarts. There is no public HTTP port required for normal use. You talk to the agent from WhatsApp on an allowlisted number. **Important:** The Baileys bridge is unofficial. Meta can restrict or ban the linked number. Prefer a dedicated secondary number, not your primary personal WhatsApp. ## Common Use Cases - Personal AI agent reachable from WhatsApp on your phone - Private assistant without installing extra chat apps - Always-on agent with memory and tools, messaged from WhatsApp - Experimentation with Hermes + WhatsApp before moving to Telegram/Discord/Slack ## Dependencies for Hermes WhatsApp Hosting - **Hermes Agent image:** `nousresearch/hermes-agent:latest` - **One persistent volume** at `/data` (required — holds WhatsApp session) - **OpenRouter (or other) API key** for inference - **A phone with WhatsApp** to scan the QR code once - **Railway SSH** for the first-time pairing step Upstream: [Hermes WhatsApp docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp) · [GitHub](https://github.com/NousResearch/hermes-agent) · [Docker Hub](https://hub.docker.com/r/nousresearch/hermes-agent) ### Implementation Details | Item | Value | |------|-------| | Image | `nousresearch/hermes-agent:latest` | | Volume | `/data` | | Hermes home | `/data/.hermes` | | WhatsApp session | under `/data/.hermes` (platforms/whatsapp) | | Start command | `hermes gateway` (via entrypoint) | | Pairing command | `hermes whatsapp` (via Railway SSH, once) | ## Topology | Service | Role | Volume | Public | Notes | |---------|------|--------|--------|-------| | **hermes** | Agent + WhatsApp bridge | `/data` | No (worker) | Pair once via SSH; then message from WhatsApp | #### Volumes (drives) — what to mount | Mount path | What is stored | |------------|----------------| | `/data` | Hermes config, sessions, **WhatsApp Baileys session**, workspace, logs | Do **not** remove the `/data` volume. Losing it means re-scanning the QR and losing agent state. ## Quick Start 1. Click **Deploy on Railway** (or deploy from this template). 2. Confirm a volume is mounted at `/data`. 3. Set variables (minimum): ```env OPENROUTER_API_KEY=sk-or-... WHATSAPP_ENABLED=true WHATSAPP_MODE=bot WHATSAPP_ALLOWED_USERS=15551234567 ``` Phone numbers: **country code + number, no `+`, no spaces** (example: `15551234567` for a US number). 4. Deploy and wait until the service is running. 5. Open the service → **Settings** / shell → **Railway SSH**. 6. Run: ```bash hermes whatsapp ``` 7. On your phone: WhatsApp → **Settings** → **Linked devices** → **Link a device** → scan the QR in the terminal. 8. When pairing succeeds, leave SSH. Message the linked WhatsApp account from an allowlisted number. After the first successful pair, redeploys keep the session as long as `/data` is intact. ## Configuration ### Required variables | Variable | Default | Notes | |----------|---------|-------| | `OPENROUTER_API_KEY` | *(empty)* | Inference (or use another supported provider key) | | `WHATSAPP_ENABLED` | `true` | Must be `true` to enable the bridge | | `WHATSAPP_ALLOWED_USERS` | *(empty)* | Comma-separated phone numbers (country code, no `+`) | ### Recommended / optional | Variable | Default | Notes | |----------|---------|-------| | `WHATSAPP_MODE` | `bot` | `bot` or `self-chat` | | `HERMES_IMAGE_VERSION` | `latest` | Pin a release tag if you need a fixed version | | `AGENT_CACHE_MEMORY_HIGH_MB` | `750` | Optional memory budget for the agent cache | Allow-all (not recommended on a personal number): ```env WHATSAPP_ALLOWED_USERS=* # or WHATSAPP_ALLOW_ALL_USERS=true ``` ### Template-specific | Variable | Default | Description | |----------|---------|-------------| | `HERMES_HOME` | `/data/.hermes` | Persistent Hermes state | | `HERMES_WRITE_SAFE_ROOT` | `/data` | Safe write root | | `HOME` | `/data` | Process home | ## Pairing details (important) | Step | What happens | |------|----------------| | First deploy | Container starts; WhatsApp is enabled but not linked yet | | `hermes whatsapp` over SSH | Terminal shows QR; phone links as a “Linked device” | | Session saved | Stored under `/data` → survives restarts and redeploys | | Re-pair needed | If you wipe the volume, log out linked devices, or the session is invalidated | Tips: - Use a **dedicated** WhatsApp number when possible. - Keep the volume. Re-pairing after data loss is the usual failure mode. - If the QR expires, run `hermes whatsapp` again. ## Updating Hermes Do **not** run `hermes update` inside the container for upgrades. 1. Redeploy (with `HERMES_IMAGE_VERSION=latest` you get the newest image). 2. WhatsApp session stays on `/data` if the volume is still attached. 3. If the bridge stops working after an upgrade, re-run `hermes whatsapp` over SSH. ## Railway SSH commands ```bash hermes status hermes whatsapp # pair / re-pair hermes gateway status hermes config hermes pairing list ``` ## Traps **Ways this still fails:** - **No QR pairing** — Setting `WHATSAPP_ENABLED=true` alone is not enough. You must run `hermes whatsapp` once over SSH and scan the code. - **Missing `/data` volume** — Session and all Hermes state are lost; you must pair again and reconfigure. - **Wrong allowlist format** — Use `15551234567`, not `+1 555 123 4567` or spaces. - **Entrypoint platform check** — Some template builds only treat Telegram/Discord/Slack as “configured platforms.” If the container exits saying no platform is configured, either add a small entrypoint fix so `WHATSAPP_ENABLED` counts, or temporarily set another platform token. Prefer fixing the entrypoint for a clean WhatsApp-only template. - **Account ban / restriction** — Unofficial linked-device sessions can be limited by Meta. Avoid spam and bulk outbound; prefer a secondary number. - **Session invalidated** — Phone “log out of all devices,” long downtime, or corrupted volume data forces a new QR scan. View logs: service → **Deployments** → latest → **View Logs**. ## Why Deploy Hermes WhatsApp on Railway? Railway gives you a persistent volume, easy secrets, and SSH for the one-time QR step. You get an always-on Hermes agent on WhatsApp without managing a VPS, as long as you accept the pairing flow and the unofficial-bridge tradeoffs. --- **Template version:** Hermes Agent `nousresearch/hermes-agent:latest` · WhatsApp (Baileys) **Related flavors:** [hermes-telegram](https://railway.com/deploy/hermes-telegram) · hermes-discord · hermes-slack ## Similar templates - [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform. - [stella](https://railway.com/deploy/stella) — Self-host stella with web, API, Postgres, Redis, and object storage. - [Hermes Agent | OpenClaw Alternative with Dashboard](https://railway.com/deploy/hermes-agent-or-openclaw-alternative-wit) — Self-Hosted Hermes AI Agent for Telegram, Discord & Slack Open this page in a browser: https://railway.com/deploy/hermes-whatsapp