hermes gateway Command — Complete Reference & Examples

Overview

hermes gateway manages the unified messaging gateway that connects Hermes to Telegram, Discord, WhatsApp, Weixin, and other platforms. It supports both an interactive foreground mode and a managed background service.

hermes gateway <run|start|stop|restart|status|install|uninstall|list|setup|migrate-legacy|enroll>

Subcommands

run — Foreground mode (recommended for WSL, Docker, Termux)

hermes gateway run
hermes gateway run -v           # Increase stderr verbosity (-v INFO, -vv DEBUG)
hermes gateway run -q           # Suppress all stderr log output
hermes gateway run --replace    # Replace any existing gateway instance
hermes gateway run --force      # Start even when a service already supervises this profile

start / stop / restart — Service control

hermes gateway start
hermes gateway start --system   # Target the Linux system-level service
hermes gateway start --all      # Kill all stale gateway processes across all profiles first
hermes gateway stop
hermes gateway restart

status — Show gateway status

hermes gateway status
hermes gateway status --deep    # Deep status check
hermes gateway status -l        # Full, untruncated output
hermes gateway status --system  # Target the Linux system-level service

install / uninstall — Install as a service

hermes gateway install --start-now
hermes gateway install --system --start-on-login --run-as-user hermes
hermes gateway uninstall
hermes gateway uninstall --system

Flags: --force, --system, --run-as-user, --start-now, --no-start-now, --start-on-login, --no-start-on-login.

list — List all profiles and their gateway status

hermes gateway list

setup — Configure messaging platforms

hermes gateway setup

migrate-legacy — Remove legacy service units

hermes gateway migrate-legacy --dry-run
hermes gateway migrate-legacy -y

Stops, disables, and removes legacy hermes.service units left by older installs, without touching profile units or third-party services.

enroll — Enroll with a relay connector

hermes gateway enroll --token <TOKEN> --connector-url wss://connector.example.com/relay

Flags: --token, --connector-url, --gateway-id, --wake-url.

Common Scenarios

Run the gateway interactively

hermes gateway run

Install and start as a service

hermes gateway install --start-now --start-on-login
hermes gateway status

Restart after configuration changes

hermes gateway restart

Clean up legacy units

hermes gateway migrate-legacy --dry-run
hermes gateway migrate-legacy -y

Tips

• Prefer hermes gateway run for initial setup, WSL, Docker, and debugging; it shows errors directly.
• Use --force only when you understand that a second dispatcher can corrupt shared gateway state.
• start --all kills stale gateway processes across all profiles before starting the service.
• setup walks you through platform configuration (Telegram, Discord, WhatsApp, etc.).
• enroll writes relay credentials to ~/.hermes/.env; requires being logged in (via hermes setup).