Skip to main content

Hermes Gateway Platform Configuration

Use when changing gateway platform or channel behavior. Use when a request is about how the gateway behaves on a chat platform — mention gating, which channels reach the agent, home channel, DM handling, allowed users/channels, reaction triggers. Applies to Slack, Discord, Telegram, Matrix, and the other adapters, which share the same config shape.

The bundled hermes-agent skill maps the CLI and file layout. This skill carries the end-to-end procedure: find the real setting name, set it, prove the running gateway will read it, and apply it without killing yourself.

When to Use​

Load this when the user asks to:

  • chat in a channel without tagging the bot, or the reverse (force a tag somewhere)
  • change which channels, DMs, or users the agent responds to
  • set or move a platform's home/default channel
  • change any platforms.<platform>.* setting, or diagnose "I changed the config and nothing happened"
  • restart or reload the gateway to apply such a change

Procedure​

  1. Read the current platform config before changing anything.

    hermes config get platforms.<platform>

    Settings live under the top-level platforms: key in config.yaml. hermes config get gateway.platforms.<platform> also resolves, so a successful read there is not evidence of where the value is stored — always write with hermes config set platforms.<platform>.<key>.

  2. Find the real setting name in the adapter, not by guessing. Each adapter declares its YAML→env bridge table in one place; grep it rather than inventing a key:

    grep -n "_YAML_BRIDGE" -A 15 <hermes-src>/plugins/platforms/<platform>/adapter.py

    That table is the authoritative list of supported keys and their PLATFORM_* env equivalents. Adapters that live in gateway/platforms/ instead of plugins/platforms/ follow the same shape.

  3. Prefer the narrowest key that expresses the intent. Adapters ship per-channel exemption lists precisely so a global flag is not needed; flipping the global gate changes behavior in every channel, which is almost never what the user asked for. See references/chat-platform-gating-keys.md for the Slack gating matrix and the equivalent concepts on other adapters.

  4. Back up, set, read back.

    cp "${HERMES_HOME:-$HOME/.hermes}/config.yaml" "${HERMES_HOME:-$HOME/.hermes}/config.yaml.bak-$(date +%Y%m%d-%H%M%S)"
    hermes config set platforms.<platform>.<key> <value>
    hermes config get platforms.<platform>

    Never hand-edit config.yaml — a stray indent corrupts the live gateway's config.

  5. Prove the gateway's own loader sees it, not just that the YAML changed. The YAML→env bridge runs inside config loading, so load it the way the gateway does:

    cd <hermes-src> && source venv/bin/activate && python3 -c "
    from gateway.config import load_gateway_config
    import os
    cfg = load_gateway_config()
    for p, pc in cfg.platforms.items():
        if '<platform>' in str(p).lower():
            print(p, pc.enabled, pc.extra)
    print('ENV:', os.environ.get('<PLATFORM>_<KEY>'))"

    A key present in pc.extra and bridged to its env var is the real confirmation. A value that appears in config.yaml but not in pc.extra means the key name is wrong or the adapter has no bridge row for it.

  6. Verify identifiers against the platform API before trusting a channel ID. Read the bot token out of .env in-process and resolve the name → ID mapping (Slack: conversations.list with types=public_channel,private_channel), and confirm the bot is actually a member (is_member). A correct setting on the wrong channel ID fails silently with no error anywhere. Never print or echo the token.

  7. Apply the change — see the restart section below — then verify live, and tell the user what to expect during the drain.

Restarting the gateway from inside the gateway​

A turn running inside the gateway process cannot run hermes gateway restart|stop; the command is blocked because SIGTERM propagates to the child and would kill the command mid-flight. Do not report this as a failure and do not ask the user to run it manually by default — detach the restart from the gateway's process tree:

cat > "${TMPDIR:-/tmp}/gateway_reload.sh" <<'EOF'
#!/bin/bash
sleep 20
systemctl --user reload hermes-gateway
EOF
chmod +x "${TMPDIR:-/tmp}/gateway_reload.sh"
systemd-run --user --unit=hermes-deferred-reload --description="deferred gateway reload" "${TMPDIR:-/tmp}/gateway_reload.sh"
  • systemd-run --user starts the job in its own unit, outside the gateway's cgroup, so the gateway's own exit cannot cancel it.
  • The sleep lets the current turn's reply be delivered before the drain begins.
  • systemctl reload maps to SIGUSR1, which the gateway handles as a drain-and-relaunch, not an in-process config reload. Active turns finish first; there is still a short unresponsive window. Say that to the user.
  • Configuration is read at gateway startup — there is no hot reload. Any platform/channel change is inert until the restart lands, so never report the change as live before it.
  • Verify after the restart: re-check hermes gateway status for a fresh start time, and confirm the new behavior with a real message. A queued reload is a scheduled action, not a verified outcome — report it as such if the session ends before it can be confirmed.

Reporting to the user​

  • Lead with the answer ("Yes — and it's configured"), then the exact key set, then what was verified.
  • State the blast radius explicitly: what changed for the target channel, and what stayed the same for every other channel, DMs, and other users. Channel-gating changes are easy to over-read as global.
  • Mention the inverse/adjacent keys (force-mention list, ignore list) as follow-ups, so the user knows the dial exists without being asked.

Support files​

  • references/chat-platform-gating-keys.md — which key answers which "who can talk to the bot where" question, per adapter.

Supporting files: this skill's supporting files are held in the docsite at docs/15-skills/_support/operations/hermes-gateway-platform-configuration/ — fetch them fresh from jknash/docsite main alongside this page. Source: jknash/hermes-shared-skills · branch hermes-jkdev001 @ 1d0d545c3970 · skills/operations/hermes-gateway-platform-configuration/ · view source · Imported 2026-10-04. Supporting files (references, scripts) remain in the source repository.

version 1.0.0 · author Hermes Agent · license MIT.

Published by Muse · 2026-10-04.