Per-Surface Restrictions: Different Surfaces, Different Threats - Hermes Tools & Capabilities

Introduction

A local CLI session and a public Discord bot face very different threats. The CLI's main risk is your own typing speed. The Discord bot's main risk is whoever shows up in the channel. Per-surface restrictions let Hermes adapt to those threats without code changes: tighter toolsets and more aggressive approvals on exposed surfaces, looser ones where you are the only user.

Key Concepts

Surface: A specific entry point for the agent (CLI, Telegram, Discord, ACP, gateway aggregate).
Trust level: How much you trust the typical user of that surface. CLI is high (you), public bot is low (strangers).
Restriction: A combination of toolset choice, approval mode, and authorization that matches the trust level.

Real World Context

The canonical example: you run hermes locally with hermes-cli (full dev) because you are debugging your own code. You also run a Discord bot with hermes-discord plus a strict allowlist because that bot is in a server with people who are not on your engineering team. Both setups share the same Hermes install. The configuration handles the difference.

Deep Dive

The canonical platform presets and their typical use:

hermes-cli: full dev. For your local terminal. Trust level: high.
hermes-telegram, hermes-slack, hermes-whatsapp, hermes-signal, hermes-mattermost, etc.: messaging platform defaults. Approximately match hermes-cli unless you tighten them. Trust level: depends on who can DM you.
hermes-discord: adds the discord and discord_admin toolsets. Tightening recommended for public servers.
hermes-acp: tightened by default. Drops clarify, cronjob, image_generate, send_message, text_to_speech, and Home Assistant tools. Use when exposing Hermes via the ACP protocol.
hermes-gateway: the union. Use only if you really need every platform's tools available.

What per-surface restriction looks like in practice:

Pick the platform preset that fits. Start there.
Tighten if the surface is public. Replace the preset with safe plus a couple of capabilities you do need.
Set authorization for the platform. GATEWAY_ALLOWED_USERS, DM pairing, per-platform allowlists, depending on the platform.
Decide on approvals. manual is the default and the safest. smart uses an auxiliary LLM to filter low-risk commands. off (equivalent to --yolo) bypasses approvals entirely. Only off is wrong for public surfaces.

Notice that the lever is not one setting. It is a small set of decisions made per surface. That is the cost of per-surface restriction, and it is the right cost: matching capability to trust is the whole job.

Common Pitfalls

Copying a CLI config to a gateway: The CLI config is usually too loose for any surface where you do not control the user. Always re-evaluate when changing surfaces.
Trusting the default: Most platform presets mirror hermes-cli defaults. That is convenient for development. It is also why people accidentally expose terminal access to chat users.

Best Practices

Start from safe for any public surface, then add tools deliberately: Easier to add than to subtract.
Use DM pairing for new users: It gives you a clean approval flow without hardcoding IDs.

Summary

Each Hermes surface (CLI, gateway, ACP) has different threat assumptions.
Platform presets give you a starting point; tighten or extend per surface.
Trust level should drive the choice of toolset, approvals, and authorization.
Per-surface restriction is one of the most important deployment decisions you make.

Code Examples

yaml

# Three surfaces, three trust levels, three configurations
platforms:
  cli:
    toolsets: [hermes-cli]
    approvals:
      mode: smart        # me, low friction

  telegram:
    toolsets: [safe, memory]
    approvals:
      mode: manual       # me + a few friends, but conservative
    allowed_users: [me_id, friend_id]

  discord:
    toolsets: [safe]      # public server
    approvals:
      mode: manual
    allow_all_users: false
    # pairing system handles new users via DM