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. 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.

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.