Skip to content

Hermes Reference

Complete guide to using the Hermes Agent with Preloop's Safety Layer.

Overview

Hermes is Nous Research's open-source autonomous coding agent. It supports MCP servers natively via its mcp_servers configuration block, which makes it a first-class citizen for Preloop onboarding.

Connecting Hermes to Preloop gives you:

  • Tool governance — Every Hermes tool call passes through the Preloop MCP Firewall.
  • Human approvals — Sensitive actions (writes, shell, money) can require approval from the Preloop dashboard, mobile, Slack, or email.
  • Runtime sessions — Each Hermes process gets a durable runtime credential and shows up in the Agents view.
  • Audit trail — Full request/response capture, attribution to a Hermes runtime principal, and exportable evidence.

Installation

Install Hermes from the upstream repository (see the Hermes docs for the latest options):

pipx install hermes-agent

hermes --version

Hermes stores its configuration at ~/.hermes/config.yaml.

The simplest path is to let the Preloop CLI find Hermes and rewrite its config so all MCP traffic flows through Preloop:

preloop agents discover

The CLI will:

  1. Detect a Hermes installation at ~/.hermes/ (it also recognises ~/.local/bin/hermes and an empty ~/.hermes/config.yaml).
  2. Back up ~/.hermes/config.yaml if one exists.
  3. Insert a Preloop entry into the mcp_servers: map pointing at your Preloop instance's /mcp/v1 endpoint with a bearer token bound to a freshly minted runtime session.
  4. Add a preloop.control block with control_ws_url, adapter_package, the durable bearer token, credential ID, managed agent ID, and runtime-session/source identity. The CLI can install and verify the runtime plugin with preloop agents install-plugin hermes; the loaded plugin owns the always-open WebSocket to /api/v1/agents/control/ws so mobile, watch, and web clients can contact the agent after onboarding.
  5. Register Hermes as a managed agent with agent_kind: hermes so it appears in the Agents view with the Hermes icon.

If Hermes does not yet have a config file, Preloop will create one for you — you do not need to bootstrap ~/.hermes/config.yaml manually before running discovery.

If your Hermes build has not yet implemented or loaded the Agent Control adapter, this preloop.control block is ignored safely. MCP firewall and model gateway routing still work, and preloop agents validate hermes reports control_config_written, control_plugin_installed, control_plugin_verified, and control_channel_configured separately from the core managed MCP validation. Agent Control is not enabled until the adapter is running inside Hermes. The reusable Python integration kit and exact hook contract live in Agent Control Runtime Adapters.

Install the Agent Control runtime plugin

Managed onboarding writes the Preloop config and attempts to install the Hermes runtime plugin through Hermes' own plugin manager when the hermes executable is available on PATH or in ~/.local/bin. You can also run preloop agents install-plugin hermes explicitly. If the native plugin installer is not available, the CLI starts Preloop's managed Agent Control sidecar as an actionable fallback so control readiness can still be verified. The standalone plugin package in the Preloop repository is preloop-hermes-plugin:

preloop agents onboard hermes
pip install preloop-hermes-plugin
# or, if Hermes wraps PyPI installs:
# hermes plugins install preloop-hermes-plugin
preloop agents validate hermes

If command -v hermes is empty but Hermes was installed by pipx or the upstream installer, add ~/.local/bin to PATH or invoke ~/.local/bin/hermes plugins install preloop-hermes-plugin directly. The package registers via the hermes_agent.plugins entry point. Validation reports the control channel as online after either the Hermes plugin or the managed sidecar is loaded and sending presence or heartbeat events.

Agent Control Runtime Expectations

Agent Control is the user-facing name for live operator contact with enrolled agents. The backend WebSocket and command endpoint are implemented, but Hermes must provide native runtime behavior before an operator command can affect a running local agent:

  • Read preloop.control.control_ws_url and connect with the durable bearer token.
  • Own reconnect/backoff and keep the WebSocket open while the Hermes session is available for operator contact.
  • Send heartbeat/status/presence envelopes so Preloop can show online state.
  • Receive send_message command envelopes from web, mobile, or watch surfaces.
  • Advertise whether the runtime supports new sessions, existing sessions, text, voice metadata, and interrupts.
  • Execute the command or inject it into the active Hermes session as a normal runtime action.
  • Treat each operator message as an auditable user/operator turn in the current Hermes session, not as a hidden system prompt or policy bypass.
  • Route any resulting tool calls and model calls through the configured Preloop MCP firewall and model gateway.

To preview without writing changes, pass the read-only flags to preloop agents discover (e.g. --dry-run).

Manual configuration

If you would rather wire Hermes by hand:

  1. Create an API key from Settings → API Keys in the Preloop dashboard.
  2. Edit ~/.hermes/config.yaml and add Preloop to the mcp_servers block:
mcp_servers:
  preloop:
    url: https://preloop.ai/mcp/v1
    headers:
      Authorization: Bearer YOUR_API_KEY_HERE
    enabled: true
  1. Verify the connection:
hermes mcp list

Preloop should appear in the list, and hermes mcp tools preloop should enumerate the tools your account exposes.

Usage

hermes "using preloop tools, pay alice@example.com $500"

Hermes will:

  1. Discover the pay_invoice tool through Preloop.
  2. Send the tool call to the Preloop MCP Firewall.
  3. Trigger any matching approval workflow (dashboard, Slack, mobile).
  4. Receive the tool result once approval is granted.

Every call shows up under the Hermes runtime principal in the Agents view, and the durable bearer token issued during onboarding ties tool usage and model spend back to that agent.

Configuration locations

Platform Path
macOS / Linux ~/.hermes/config.yaml
Project-scoped ./.hermes/config.yaml

Project-scoped configs override the user-level config. The Preloop CLI rewrites whichever config it discovers first (project-scoped takes precedence).

Troubleshooting

  • preloop agents discover does not find Hermes — Ensure either ~/.hermes/ or ~/.local/bin/hermes exists. You can also pass --include hermes to force-add the agent.
  • Tools are missing — Check that the API key used has the mcp:read and mcp:write scopes, and that no MCP server allowlist is restricting Hermes from your account.
  • Approval requests time out — Increase timeout_seconds on the matching approval workflow or wire up a webhook so the Hermes session blocks until approval lands.