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.

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:

You set env vars and deploy.
You open Railway SSH and run hermes whatsapp to scan a QR code from your phone.
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 · GitHub · Docker Hub

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

Click Deploy on Railway (or deploy from this template).
Confirm a volume is mounted at /data.
Set variables (minimum):

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).

Deploy and wait until the service is running.
Open the service → Settings / shell → Railway SSH.
Run:

hermes whatsapp

On your phone: WhatsApp → Settings → Linked devices → Link a device → scan the QR in the terminal.
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):

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.

Redeploy (with HERMES_IMAGE_VERSION=latest you get the newest image).
WhatsApp session stays on /data if the volume is still attached.
If the bridge stops working after an upgrade, re-run hermes whatsapp over SSH.

Railway SSH commands

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 · hermes-discord · hermes-slack