Toolset Archetypes: Read-Only, Web, Dev, Full

+15 Mana ✨
Hermes Toolsets Reference(DOCUMENTATION)

Introduction

Most real deployments cluster around a small number of toolset shapes. Calling these archetypes makes them easier to reason about. Whatever your situation, you are probably starting from one of four shapes: read-only, web-centric, dev (full developer capability), or full (everything Hermes ships with).

Key Concepts

  • Read-only archetype: No mutation. Examples: safe. Used for public-facing bots and research tasks.
  • Web archetype: Web search and extraction, possibly the browser. Used for research agents that do not need filesystem access.
  • Dev archetype: File operations, terminal, web. The local power-user setup. Used for CLI sessions.
  • Full archetype: Everything. Used by hermes-gateway when you want every surface available.

Real World Context

When a new user asks what should I load for my bot?, the answer is almost always one of these four. You very rarely need a custom shape from scratch. Naming them turns the question from which tools? to which archetype, and what is different about my case?.

Deep Dive

A closer look at each, with the actual Hermes toolsets that fit:

Read-only (the safe archetype):

Includes web_search, web_extract, vision_analyze, image_generate. No file writes, no terminal, no code execution. This is what you want for a public-facing bot where users you do not trust can send messages and you do not want any local-state surface exposed.

Web (research-focused):

Includes the web toolset (web_search, web_extract) and often the browser toolset. Used by agents whose job is to gather information from the web and report back. May or may not include vision_analyze depending on whether screenshots are part of the workflow.

Dev (developer power):

Includes file (read_file, write_file, patch, search_files), terminal (terminal, process), web (web_search, web_extract), and usually code_execution (execute_code). This is the local CLI default. The agent can read and write code, run tests, search the web for docs, and execute Python snippets for one-off tasks.

Full (everything):

The hermes-gateway preset loads the union of every platform toolset. Useful when you want a single agent that supports any surface (Discord, Telegram, web, CLI) and the deployment will figure out which platform sent each request.

Most real configurations are a small variation on one of these:

  • A research agent: web archetype plus memory for persistent notes.
  • A code-only assistant: dev archetype minus terminal (read-and-patch only).
  • A homelab bot: dev archetype plus homeassistant.

Common Pitfalls

  1. Picking dev for a public bot: Anyone with chat access can ask the agent to run terminal commands. Use safe or a narrow custom toolset instead.
  2. Picking safe for a CLI agent: The whole point of running Hermes locally is the filesystem and terminal. safe is too restrictive for development.

Best Practices

  1. Identify the archetype first, then trim: Name the archetype, then ask what to remove. That is faster than building from scratch.
  2. Document the choice next to the config: A one-line comment (# read-only archetype, no terminal exposed) saves future-you a lot of guessing.

Summary

  • Four common archetypes: read-only (safe), web, dev, full.
  • Most real configurations are small variations on these.
  • Start from the archetype that fits the surface, then trim or extend.
  • Document the archetype name in the config so the intent is visible.

Code Examples

yaml
# Read-only archetype: research-bot deployment
toolsets:
  - safe   # web_search, web_extract, vision_analyze, image_generate

# Dev archetype: local CLI
toolsets:
  - file
  - terminal
  - web
  - code_execution

# Full archetype: gateway daemon serving every platform
toolsets:
  - hermes-gateway
✓ Completed