Sókrates Wiki

Hermes Gateway Service Management

3 min read

Hermes Gateway Service Management

Summary

The Hermes Gateway is the primary I/O component of the Hermes Agent, responsible for maintaining persistent connections to messaging platforms like Telegram, WhatsApp, Slack, and Discord. It provides a CLI-driven lifecycle management system for installing the gateway as a background service on Linux (via systemd) and macOS (via launchd), supporting both single-user and system-wide deployments.

Details

The Hermes Gateway acts as the bridge between external messaging channels and the internal agent logic. While the Sokrates project primarily deploys Hermes as a NixOS systemd service via the nix-hermes module, the hermes CLI provides a robust set of commands for managing the gateway in development environments (sokrates-dev) and on non-NixOS systems.

Configuration and Setup

The gateway is configured using an interactive wizard invoked via hermes gateway setup. This tool allows users to select messaging platforms using an arrow-key interface, input necessary API tokens or credentials, and verify which platforms are currently active. Once configured, the gateway can be run in the foreground for debugging using hermes gateway or installed as a persistent background process.

Service Installation on Linux (systemd)

On Linux systems, Hermes supports two primary installation modes:

  • User Service: Installed via hermes gateway install. This creates a systemd unit scoped to the current user. It is ideal for development machines and laptops.
  • System Service: Installed via sudo hermes gateway install --system. This creates a boot-time service that runs as the specified user but does not require the user to be logged in or for “systemd linger” to be enabled. This is the preferred method for VPS or headless host deployments.

The CLI provides standard management wrappers:

  • hermes gateway start [--system]
  • hermes gateway stop [--system]
  • hermes gateway status [--system]

Logs for systemd installations are typically accessed via journalctl --user -u hermes-gateway -f for user services or journalctl -u hermes-gateway -f for system services.

Service Installation on macOS (launchd)

On macOS, the gateway is installed as a launchd agent. The installation process generates a property list (plist) file located at ~/Library/LaunchAgents/ai.hermes.gateway.plist.

A critical aspect of the macOS installation is environment variable persistence. The generated plist captures the user’s full shell PATH at the time of installation, along with VIRTUAL_ENV and HERMES_HOME. This ensures that the gateway can locate necessary subprocess dependencies, such as Node.js or ffmpeg (required for the WhatsApp bridge), which might be installed via Homebrew or version managers like nvm. If the system PATH changes (e.g., after installing new tools), the service must be re-installed using hermes gateway install to refresh the plist configuration.

Multi-Tenancy and HERMES_HOME

Hermes supports running multiple isolated instances on a single machine. This is managed through the HERMES_HOME environment variable, which defaults to ~/.hermes.

When multiple installations exist, the service management system prevents naming collisions by appending a unique hash or suffix to the service name (e.g., hermes-gateway-<hash> on Linux or ai.hermes.gateway-<suffix> on macOS). The hermes gateway commands automatically detect the current HERMES_HOME and target the corresponding service unit. The system also includes safety checks to warn users if both a user-level and system-level service are detected for the same installation, preventing ambiguous state management.

Graph View

Backlinks