Skip to main content

Hermes Agent

Status: 🟡 Documented, not yet verified end-to-end Hermes is the only client where helmdeck-as-LLM-gateway drops in cleanly today via the base_url config field. Promote to ✅ once a maintainer has walked the Phase 5.5 loop and confirmed the T607 success-rate panel ticks from a real Hermes run.

Topology​

Hermes Agent is Topology B — runs on the user's host alongside a local helmdeck stack. Connection is stdio bridge (Hermes' MCP config docs only show stdio shape), but Hermes is unique in this matrix: its base_url field in the model config is an explicit OpenAI-compatible escape hatch, so helmdeck can also serve as Hermes' LLM gateway — every chat completion Hermes issues lands in helmdeck's provider_calls table and shows up in the AI Providers → Model Success Rates panel.

host
├── helmdeck (docker compose stack on localhost:3000)
│     ├── /v1/chat/completions  (LLM gateway — sees Hermes' chat calls)
│     └── /api/v1/mcp/ws        (MCP server — exposes packs)
│
└── hermes-agent (binary in ~/.hermes)
      ├── LLM:  base_url=http://localhost:3000  → routes through helmdeck
      └── MCP:  spawns helmdeck-mcp stdio bridge → routes through helmdeck

Source: https://hermes-agent.nousresearch.com/docs/integrations/providers

Prerequisites​

  • Linux, macOS, or WSL2
  • Git (the only build prerequisite per Hermes docs)
  • A running helmdeck stack
  • An LLM provider API key (OpenRouter recommended; works with any OpenAI-compatible upstream)
  • For Phase 5.5: private GitHub repo + ssh-git Vault credential

1. Install Hermes Agent​

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Verify: hermes --version.

Source: https://hermes-agent.nousresearch.com/docs/getting-started/installation

2. Install the helmdeck-mcp bridge​

Tip: Helmdeck is on the official MCP Registry as io.github.tosin2013/helmdeck. The cross-client registry walkthrough is at Register helmdeck with your MCP client. Steps below are the Hermes-Agent-specific path.

brew install tosin2013/helmdeck/helmdeck-mcp
# or
go install github.com/tosin2013/helmdeck/cmd/helmdeck-mcp@latest

3. Configure Hermes — single YAML file​

Edit ~/.hermes/config.yaml. Two sections to add: the LLM provider (routed through helmdeck) and the MCP server (also helmdeck).

# Route Hermes' LLM calls through helmdeck so the T607 success-rate
# panel sees every chat completion. Helmdeck then dispatches to the
# real provider (OpenRouter, OpenAI, Anthropic, …) based on which
# provider key is registered in the keystore.
model: openrouter/minimax/minimax-m2.7
base_url: http://localhost:3000/v1
api_key: <your-helmdeck-jwt>

# MCP servers — helmdeck via the stdio bridge.
mcp_servers:
  helmdeck:
    command: helmdeck-mcp
    env:
      HELMDECK_URL: http://localhost:3000
      HELMDECK_TOKEN: <your-helmdeck-jwt>

Note: the same JWT works for both the LLM gateway and the MCP bridge — they share helmdeck's auth surface.

4. Load the agent skills​

Hermes' ~/.hermes/config.yaml accepts a system_prompt_file field. Pointing it at a checked-out copy of SKILLS.md keeps the agent's skill in sync with helmdeck pulls:

# Add to ~/.hermes/config.yaml alongside the model/mcp_servers blocks:
system_prompt_file: /path/to/helmdeck/docs/integrations/SKILLS.md

Or paste the contents inline if your config is checked into version control on the same machine where helmdeck doesn't live:

system_prompt: |
  <paste the contents of helmdeck/docs/integrations/SKILLS.md here>

Source: Hermes Agent configuration docs.

Verify: hermes "what helmdeck packs do you know about?" should rattle off the full catalog (browser, web, repo, github, fs, cmd, git, http, doc, slides, vision, language). If not, check the config-file path Hermes is actually reading (hermes --version or its docs).

Refresh after pulling a new helmdeck release — system_prompt_file re-reads on every Hermes invocation, so a git pull in the helmdeck checkout is enough; no Hermes restart needed.

5. Verify the LLM gateway path​

Run a one-shot Hermes prompt and watch helmdeck's provider_calls fill in:

hermes "What is 2 + 2? Reply in one word."

Then in another shell:

sqlite3 /root/helmdeck/helmdeck.db \
  'select provider, model, status, latency_ms from provider_calls order by ts desc limit 5'

You should see at least one openrouter | minimax/minimax-m2.7 | success row. Open the helmdeck UI's AI Providers panel and confirm the Model Success Rates section shows the row.

6. Walk the Phase 5.5 code-edit loop​

hermes "Use the helmdeck packs to:
  1. repo.fetch git@github.com:<me>/<fixture-repo>.git using vault credential gh-deploy-key.
  2. fs.list the clone for *.md files.
  3. fs.read the README and propose a one-line edit.
  4. fs.patch to apply the edit.
  5. cmd.run 'go test ./...' in the clone.
  6. git.commit with message 'chore: helmdeck integration smoke'.
  7. repo.push back to origin."

Pass criteria:

  • Commit lands on the remote branch.
  • Helmdeck Audit Logs panel shows one entry per pack call.
  • Helmdeck AI Providers → Model Success Rates panel shows multiple successful rows for openrouter/minimax/minimax-m2.7 (one per LLM round trip during the loop).
  • SSH private key never appears in Hermes' chat transcript.

If all four hold, this is the strongest end-to-end validation in the matrix because helmdeck observes both layers (LLM dispatches AND MCP tool calls). Update the status banner ✅ and flip the matrix row.

Troubleshooting​

  • provider_calls empty after a Hermes prompt — Hermes is bypassing helmdeck. Confirm base_url is http://localhost:3000/v1 (note the /v1 path) and that helmdeck has the openrouter provider registered (curl -H "Authorization: Bearer $JWT" http://localhost:3000/v1/models should list it).
  • helmdeck-mcp: command not found — bridge not on PATH. Pin the absolute path in the command field.
  • OpenAI-shape response shape mismatch — helmdeck's /v1/chat/completions is OpenAI-compatible; if Hermes complains, check the model id matches provider/model (e.g. openrouter/minimax/minimax-m2.7, not just minimax-m2.7).

References​