Per-Context Activation: Different Surfaces, Different Toolsets

+15 Mana ✨
Hermes Gateways Overview(DOCUMENTATION)

Introduction

The same Hermes binary serves a CLI, a Discord bot, a Telegram bot, and a web ACP gateway. Each of those is a different context with different trust assumptions. Per-context activation is how you load a different toolset on each surface without running multiple Hermes installs.

Key Concepts

  • Per-context toolset: A toolset associated with a specific surface (CLI, gateway platform, ACP).
  • Platform preset: A built-in toolset named hermes-<platform> (for example hermes-cli, hermes-telegram, hermes-discord). Defines the default tools for that surface.
  • Override: A configuration that replaces the default toolset for a specific context.

Real World Context

A developer runs Hermes locally with full dev capabilities. The same machine also runs a Telegram gateway exposed to a small group of friends. The local CLI should have terminal access. The Telegram gateway should not. Per-context activation makes that possible: the binary is the same, the config picks different toolsets for each surface.

Deep Dive

Hermes platform presets ship under names like hermes-cli, hermes-telegram, hermes-discord, hermes-slack, hermes-whatsapp, hermes-acp, and hermes-gateway. By default, most platform presets mirror hermes-cli (full dev), with a few exceptions:

  • hermes-acp drops several tools (clarify, cronjob, image_generate, send_message, text_to_speech, Home Assistant) to keep the ACP surface tight.
  • hermes-discord adds the discord and discord_admin toolsets.
  • hermes-feishu adds Feishu document and drive tools.
  • hermes-gateway is the union of all platform toolsets.

You configure per-context activation in config.yaml:

yaml
toolsets:
  - hermes-cli         # default loaded when running `hermes` interactively

# Per-platform override (only one shown for clarity)
platforms:
  telegram:
    toolsets:
      - safe           # narrow set for an untrusted-user surface
      - memory
  discord:
    toolsets:
      - hermes-discord # full platform preset for a trusted server

When Hermes runs in CLI mode, the top-level toolsets applies. When it runs as a Telegram gateway, the Telegram override applies, replacing the default. This is the single most important deployment lever in Hermes.

A few practical notes:

  • You can also override per session via the CLI flag: hermes chat --toolsets web,file. Useful for one-off tasks.
  • Skills (Course 6) can request additional tools at runtime within the bounds of what is loaded. They cannot smuggle in tools that the active toolset omits.
  • Deep-dive on per-platform restrictions belongs to Course 8 (Gateways). Here we keep it conceptual.

Common Pitfalls

  1. Forgetting to set per-platform toolsets: If you do not override, the global toolset applies. A Telegram bot accidentally has full terminal access. This is the most common deployment mistake.
  2. Using hermes-gateway for one-platform setups: It loads everything, including tools your platform does not need. Prefer the specific preset.

Best Practices

  1. Set the global to the strictest case: Then loosen per platform where the trust allows.
  2. Re-audit when adding a new platform: A new gateway is a new trust surface. Decide its toolset deliberately, not by inheritance.

Summary

  • Hermes can load different toolsets on different surfaces.
  • Platform presets (hermes-cli, hermes-telegram, ...) define defaults per surface.
  • Override the toolset per platform in config.yaml to match the surface's trust level.
  • This is the core deployment lever for matching capability to context.

Code Examples

yaml
# A practical config: tight default, loosened per platform
toolsets:
  - safe              # global default = read-only

platforms:
  cli:
    toolsets:
      - hermes-cli    # full dev capability for the local user
  telegram:
    toolsets:
      - safe          # remain read-only for chat users
      - memory        # plus memory across conversations
  discord:
    toolsets:
      - hermes-discord # full discord-aware preset for a trusted server
✓ Completed