MCPInstall

hermes-agent-optimization

by reason-machinesAI & Agents

Expert guide for deploying, configuring, and optimizing Hermes AI agents with multi-platform support, MCP integration, and production best practices

Installs
149
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/reason-machines/hermes-skills --skill hermes-agent-optimization
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads hermes-agent-optimization automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Hermes Agent Optimization

Skill by ara.so — Hermes Skills collection.

Hermes Agent is an autonomous AI agent framework that orchestrates LLM calls across 20+ platforms (Telegram, Discord, Slack, CLI, webhooks), integrates with MCP servers for tool access, supports multiple LLM providers (Anthropic, OpenAI, Google, local models), and includes durable execution features like Kanban boards and persistent goals.

This skill covers production deployment, multi-platform configuration, cost optimization, security hardening, skill creation, and troubleshooting based on the OnlyTerp/hermes-optimization-guide repository.

Installation

Quick Local Setup (5 minutes)

# Install Hermes (requires Node.js 18+)
npm install -g @nousresearch/hermes-agent

# Initialize config directory
hermes init

# Start interactive setup
hermes configure

Production VPS Setup (One Command)

For Debian 12 / Ubuntu 24.04:

curl -sSL https://raw.githubusercontent.com/OnlyTerp/hermes-optimization-guide/main/scripts/vps-bootstrap.sh | sudo bash

This installs Hermes, Node.js, Caddy reverse proxy, UFW firewall, fail2ban, creates a hermes user, sets up systemd services, and symlinks all guide skills.

Manual Installation

# Install dependencies
sudo apt update && sudo apt install -y nodejs npm git curl

# Install Hermes globally
npm install -g @nousresearch/hermes-agent

# Create hermes user (production)
sudo useradd -r -m -d /home/hermes -s /bin/bash hermes

# Initialize config
sudo -u hermes hermes init

Configuration Structure

Hermes config lives at ~/.hermes/config.yaml:

# Minimal working config
providers:
  anthropic:
    api_key: ${ANTHROPIC_API_KEY}
    default_model: claude-3-5-sonnet-20241022

gateways:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
    enabled: true

memory:
  provider: lightrag
  storage_path: ~/.hermes/memory

skills:
  directory: ~/.hermes/skills
  auto_load: true

security:
  redact_secrets: true
  approval_mode: auto

Environment Variables

Create ~/.hermes/.env:

# LLM Providers
ANTHROPIC_API_KEY=your_key_here
OPENAI_API_KEY=your_key_here
GOOGLE_API_KEY=your_key_here

# Platforms
TELEGRAM_BOT_TOKEN=your_bot_token
DISCORD_BOT_TOKEN=your_discord_token
SLACK_BOT_TOKEN=xoxb-your-slack-token

# Observability
LANGFUSE_SECRET_KEY=your_langfuse_key
LANGFUSE_PUBLIC_KEY=your_public_key
LANGFUSE_HOST=https://cloud.langfuse.com

# Optional: Cost optimization
DEEPSEEK_API_KEY=your_deepseek_key
CEREBRAS_API_KEY=your_cerebras_key

Key Commands

Starting Hermes

# Interactive TUI mode
hermes

# Headless daemon (production)
hermes daemon

# Web dashboard (runs on http://localhost:3000)
hermes dashboard

# Specific gateway only
hermes --gateway telegram

# Debug mode with verbose logging
DEBUG=hermes:* hermes daemon

Management Commands

# Update to latest version
hermes update

# Run skill curator (grade and clean skills)
hermes curator

# Backup configuration and data
hermes backup --output ~/hermes-backup-$(date +%F).tar.gz

# Test configuration without starting
hermes validate

# List active sessions
hermes sessions list

# Clear all memory (DESTRUCTIVE)
hermes memory clear

Systemd Service (Production)

# Install service
sudo cp /path/to/templates/systemd/hermes.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable hermes
sudo systemctl start hermes

# View logs
sudo journalctl -u hermes -f

# Restart after config changes
sudo systemctl restart hermes

Setting Up Platforms

Telegram Bot

  1. Create bot with @BotFather
  2. Get token and add to .env
  3. Configure in config.yaml:
gateways:
  telegram:
    enabled: true
    token: ${TELEGRAM_BOT_TOKEN}
    allowed_users:
      - 123456789  # Your Telegram user ID
    features:
      voice_enabled: true
      document_upload: true
      inline_mode: true

Discord Bot

  1. Create application at Discord Developer Portal
  2. Enable Message Content Intent
  3. Configure:
gateways:
  discord:
    enabled: true
    token: ${DISCORD_BOT_TOKEN}
    command_prefix: "!"
    allowed_roles:
      - "AI Assistant Users"
    allowed_guilds:
      - "1234567890123456789"

Slack App

gateways:
  slack:
    enabled: true
    bot_token: ${SLACK_BOT_TOKEN}
    app_token: ${SLACK_APP_TOKEN}
    signing_secret: ${SLACK_SIGNING_SECRET}
    socket_mode: true

CLI (Always Available)

# Direct CLI conversation
hermes chat "explain quantum computing"

# Pipe input
echo "summarize this" | hermes chat

# File processing
hermes chat "analyze this code" < script.py

Model Routing & Cost Optimization

Smart Router Configuration

models:
  router:
    enabled: true
    strategy: cost_optimized  # or: balanced, performance, local_first
    
  profiles:
    cheap:
      provider: cerebras
      model: llama-3.3-70b
      max_context: 8192
      cost_per_1m_tokens: 0.60
      
    balanced:
      provider: anthropic
      model: claude-3-5-haiku-20241022
      max_context: 200000
      cost_per_1m_tokens: 1.00
      
    premium:
      provider: anthropic
      model: claude-3-5-sonnet-20241022
      max_context: 200000
      cost_per_1m_tokens: 3.00
      
    local:
      provider: lm_studio
      model: qwen-2.5-coder-32b
      endpoint: http://localhost:1234/v1
      max_context: 32768
      
  routing_rules:
    - if: "token_count < 2000"
      use: cheap
    - if: "requires_code_execution"
      use: premium
    - if: "user_priority == high"
      use: premium
    - default: balanced

Provider Setup Examples

Anthropic (Claude):

providers:
  anthropic:
    api_key: ${ANTHROPIC_API_KEY}
    default_model: claude-3-5-sonnet-20241022
    max_tokens: 4096
    temperature: 0.7

OpenAI:

providers:
  openai:
    api_key: ${OPENAI_API_KEY}
    default_model: gpt-4o-2024-11-20
    organization: ${OPENAI_ORG_ID}

Google (Gemini):

providers:
  google:
    api_key: ${GOOGLE_API_KEY}
    default_model: gemini-2.0-flash-exp
    safety_settings:
      harassment: BLOCK_NONE
      hate_speech: BLOCK_NONE

Local LM Studio:

providers:
  lm_studio:
    endpoint: http://localhost:1234/v1
    default_model: qwen-2.5-coder-32b-instruct
    timeout: 300000

MCP Server Integration

MCP (Model Context Protocol) servers provide tools/resources to Hermes.

Configuration

mcp:
  servers:
    filesystem:
      command: npx
      args:
        - "-y"
        - "@modelcontextprotocol/server-filesystem"
        - "/home/user/projects"
      transport: stdio
      
    github:
      command: npx
      args:
        - "-y"
        - "@modelcontextprotocol/server-github"
      env:
        GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_TOKEN}
      transport: stdio
      
    brave_search:
      command: npx
      args:
        - "-y"
        - "@modelcontextprotocol/server-brave-search"
      env:
        BRAVE_API_KEY: ${BRAVE_API_KEY}
      transport: stdio
      
    postgres:
      command: docker
      args:
        - "run"
        - "-i"
        - "--rm"
        - "mcp/postgres"
      env:
        DATABASE_URL: ${DATABASE_URL}
      transport: stdio

Testing MCP Servers

# List available MCP tools
hermes mcp list

# Test specific server
hermes mcp test filesystem

# Interactive MCP inspector
npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /tmp

Creating Custom Skills

Skills live in ~/.hermes/skills/ as markdown files.

Skill Template

---
name: example-skill
description: Does something useful
triggers:
  - "how do I use example"
  - "explain example tool"
dependencies:
  - "example-npm-package"
---

# Example Skill

## What it does
Brief explanation.

## Usage

```bash
npm install example-npm-package

const example = require('example-npm-package');
example.doThing();

Common patterns

  • Pattern 1
  • Pattern 2

### Installing Skills from Guide

```bash
# Clone the optimization guide
git clone https://github.com/OnlyTerp/hermes-optimization-guide.git

# Symlink all guide skills
ln -s $(pwd)/hermes-optimization-guide/skills/* ~/.hermes/skills/

# Or individual skill
ln -s $(pwd)/hermes-optimization-guide/skills/mcp-filesystem.md ~/.hermes/skills/

Skill Curator

# Run curator to grade and clean skills
hermes curator

# Curator runs automatically every 7 days by default
# Configure in config.yaml:
curator:
  enabled: true
  schedule: "0 3 * * 0"  # Weekly Sunday 3am
  grade_threshold: 6  # Archive skills below this score
  review_provider: anthropic
  review_model: claude-3-5-haiku-20241022

Durable Execution Features

Kanban Boards (v0.13+)

tenacity:
  kanban:
    enabled: true
    boards:
      - name: development
        lanes:
          - todo
          - in_progress
          - review
          - done
        heartbeat_interval: 60
        retry_budget: 3
        
  checkpoints:
    enabled: true
    directory: ~/.hermes/checkpoints
    max_size_mb: 500
    pruning:
      enabled: true
      keep_last_n: 10

Usage:

User: "Add feature X to project Y and deploy"
Agent creates Kanban card → moves through lanes → reports status

Persistent Goals

/goal set "Deploy the new API endpoint to production"
/goal list
/goal pause goal_abc123
/goal resume goal_abc123
/goal clear goal_abc123

Goals persist across sessions and keep the agent focused until completion.

Cron Jobs (No-Agent Watchdogs)

cron:
  jobs:
    - name: disk_space_check
      schedule: "*/30 * * * *"  # Every 30 min
      command: "df -h | grep -E '9[0-9]%|100%'"
      no_agent: true  # Just run command, don't involve LLM
      alert_on: stderr
      
    - name: backup
      schedule: "0 2 * * *"  # Daily 2am
      command: "hermes backup --output /backups/hermes-$(date +%F).tar.gz"
      no_agent: true

Security Configuration

Production Security Settings

security:
  # Redact secrets in logs (default: true in v0.13+)
  redact_secrets: true
  
  # Approval modes: auto, manual, quarantine
  approval_mode: manual
  
  # Tool restrictions
  tool_allowlist:
    - read_file
    - write_file
    - execute_command
    - mcp_*
    
  tool_denylist:
    - dangerous_tool
    
  # Command execution sandbox
  sandbox:
    enabled: true
    allowed_directories:
      - /home/hermes/workspace
      - /tmp/hermes
    forbidden_commands:
      - rm -rf /
      - dd if=
      - mkfs
      
  # Rate limiting
  rate_limits:
    requests_per_minute: 60
    tokens_per_hour: 500000
    
  # Webhook signature verification
  webhooks:
    require_signatures: true
    allowed_ips:
      - 192.168.1.0/24

Platform-Specific Security

Telegram:

gateways:
  telegram:
    allowed_users:
      - 123456789
    block_groups: true  # Only allow DMs
    require_authorization: true

Discord:

gateways:
  discord:
    allowed_roles:
      - "Admin"
      - "Developer"
    allowed_guilds:
      - "1234567890"  # Specific server ID
    reject_dms: true

Webhooks:

gateways:
  webhook:
    port: 3001
    path: /webhook
    secret: ${WEBHOOK_SECRET}
    verify_signatures: true
    require_api_key: true
    api_keys:
      - ${WEBHOOK_API_KEY_1}

Observability & Monitoring

Langfuse Integration

observability:
  langfuse:
    enabled: true
    public_key: ${LANGFUSE_PUBLIC_KEY}
    secret_key: ${LANGFUSE_SECRET_KEY}
    host: https://cloud.langfuse.com
    trace_all: true
    capture_io: true
    
  logging:
    level: info  # debug, info, warn, error
    file: ~/.hermes/logs/hermes.log
    max_size_mb: 100
    max_files: 10

Prometheus Metrics

observability:
  prometheus:
    enabled: true
    port: 9090
    path: /metrics

Key metrics:

  • hermes_requests_total - Total requests by platform/status
  • hermes_tokens_used - Token consumption by model
  • hermes_cost_usd - Estimated cost
  • hermes_latency_seconds - Response times

Dashboard Analytics

Access at http://localhost:3000 after running hermes dashboard:

  • Real-time session view
  • Token/cost tracking
  • Model performance comparison
  • Platform activity charts
  • Skill usage statistics
  • Error rate monitoring

Troubleshooting

Common Issues

1. "Cannot find module '@nousresearch/hermes-agent'"

# Reinstall globally
npm uninstall -g @nousresearch/hermes-agent
npm install -g @nousresearch/hermes-agent

# Or use npx
npx @nousresearch/hermes-agent

2. Telegram bot not responding

# Check token validity
curl https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe

# Verify webhook isn't set (conflicts with polling)
curl https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/deleteWebhook

# Check logs
DEBUG=hermes:telegram hermes daemon

3. MCP server connection fails

# Test server directly
npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /tmp

# Check permissions
ls -la ~/.hermes/mcp-servers/

# Verify environment variables
env | grep -E 'GITHUB|BRAVE|DATABASE'

4. Out of memory errors

# Reduce context window
providers:
  anthropic:
    max_tokens: 2048  # Down from 4096
    
# Enable context compression
memory:
  compression:
    enabled: true
    target_tokens: 4000

5. High costs

# Check token usage
hermes stats

# Enable cost-optimized routing
models:
  router:
    strategy: cost_optimized

# Use local models for simple tasks
providers:
  lm_studio:
    default_model: qwen-2.5-coder-32b-instruct

6. Skills not loading

# Verify directory
ls -la ~/.hermes/skills/

# Check skill syntax
hermes validate ~/.hermes/skills/my-skill.md

# Force reload
hermes --reload-skills

Debug Mode

# Full debug output
DEBUG=hermes:* hermes daemon

# Specific subsystems
DEBUG=hermes:telegram,hermes:mcp hermes daemon

# Save debug logs
DEBUG=hermes:* hermes daemon 2>&1 | tee debug.log

Validation Commands

# Validate config
hermes validate

# Test provider connectivity
hermes test-providers

# Check MCP servers
hermes mcp list

# Verify skills
hermes skills validate-all

Real-World Patterns

Pattern 1: Multi-Model Routing

# Use cheap models for simple tasks, premium for complex
models:
  router:
    enabled: true
    rules:
      - if: "token_count < 1000 and !contains(user_input, 'code')"
        use: cerebras  # $0.60/1M tokens
      - if: "contains(user_input, 'write code')"
        use: claude_sonnet
      - if: "contains(user_input, 'analyze image')"
        use: gemini_flash
      - default: claude_haiku

Pattern 2: Secure Webhook Handler

gateways:
  webhook:
    enabled: true
    port: 3001
    path: /webhook
    secret: ${WEBHOOK_SECRET}
    handlers:
      github:
        events:
          - push
          - pull_request
        action: "trigger_skill:github-pr-reviewer"
      stripe:
        verify_signature: true
        action: "trigger_skill:payment-processor"

Pattern 3: Automated Code Review

cron:
  jobs:
    - name: review_prs
      schedule: "0 */2 * * *"  # Every 2 hours
      command: "hermes chat 'Review open GitHub PRs in repo org/project'"
      provider: anthropic
      model: claude-3-5-sonnet-20241022
      
skills:
  # Link github-pr-reviewer.md skill

Pattern 4: Cost-Optimized Local First

models:
  router:
    strategy: local_first
    fallback_on_error: true
    
providers:
  lm_studio:
    endpoint: http://localhost:1234/v1
    default_model: qwen-2.5-coder-32b-instruct
    timeout: 60000
    
  anthropic:  # Fallback for complex tasks
    api_key: ${ANTHROPIC_API_KEY}
    default_model: claude-3-5-haiku-20241022

Pattern 5: Multi-Platform Broadcast

# Send message to all platforms
hermes broadcast "System maintenance in 10 minutes"

# Platform-specific routing in config.yaml
gateways:
  telegram:
    broadcast_channels:
      - "@myteamupdates"
  discord:
    broadcast_channels:
      - "1234567890"  # Channel ID
  slack:
    broadcast_channels:
      - "#general"

Reference Architecture

Solo Developer Setup:

  • Hermes on local machine
  • Telegram bot for mobile access
  • LM Studio for local models
  • MCP filesystem + GitHub servers
  • Monthly cost: ~$10 (API only)

Small Team Setup:

  • Hermes on VPS (Hetzner CX22)
  • Telegram + Discord + Slack
  • Claude Haiku primary, Cerebras fallback
  • Langfuse for observability
  • Monthly cost: ~$50 (VPS + API)

Production Setup:

  • Hermes cluster behind load balancer
  • All platforms enabled
  • Multi-region model routing
  • Langfuse + Prometheus + Grafana
  • Redis session storage
  • Automated backups to S3
  • Monthly cost: $200-500 (infrastructure + API)

Additional Resources

Quick Reference

# Essential commands
hermes                    # Start TUI
hermes daemon            # Start headless
hermes dashboard         # Start web UI
hermes update            # Update to latest
hermes curator           # Grade skills
hermes backup            # Backup data
hermes validate          # Check config

# Debugging
DEBUG=hermes:* hermes daemon
hermes test-providers
hermes mcp list
hermes sessions list

# Management
systemctl restart hermes
journalctl -u hermes -f
hermes stats

FAQ

What does the hermes-agent-optimization skill do?

Expert guide for deploying, configuring, and optimizing Hermes AI agents with multi-platform support, MCP integration, and production best practices

How do I install hermes-agent-optimization?

Run npx skills add https://github.com/reason-machines/hermes-skills --skill hermes-agent-optimization in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/hermes-agent-optimization/ (personal) or .claude/skills/hermes-agent-optimization/ (project).

Which AI agents can use hermes-agent-optimization?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is hermes-agent-optimization safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains hermes-agent-optimization?

It is published by reason-machines in reason-machines/hermes-skills. It has 149 recorded installs.

More from reason-machines/hermes-skills

View all →

hermes-agent-self-evolution

reason-machines/hermes-skills

Open the skill to read its SKILL.md instructions.

316 installs

hermes-webui-agent

reason-machines/hermes-skills

Open the skill to read its SKILL.md instructions.

262 installs

awesome-hermes-agent-ecosystem

reason-machines/hermes-skills

Open the skill to read its SKILL.md instructions.

232 installs

hermes-agent-framework

reason-machines/hermes-skills

Open the skill to read its SKILL.md instructions.

219 installs

hermes-workspace-ai-agent-ui

reason-machines/hermes-skills

Open the skill to read its SKILL.md instructions.

Frontend & Design213 installs

hermes-desktop-companion

reason-machines/hermes-skills

Open the skill to read its SKILL.md instructions.

206 installs

Popular ai & agents skills

View category →

google-agents-cli-publish

google/agents-cli

This skill should be used when the user wants to "publish an agent", "publish my ADK agent", "register an agent with Gemini", "publish to Gemini" (formerly Gemini Enterprise), or needs guidance on the agents-cli publish gemini command. Also use when the user wants to "manage agents in Agent Registry", "list/update/delete registered agents", or "register an MCP server". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).

AI & Agents513.9K installs

google-agents-cli-eval

google/agents-cli

This skill should be used when the user wants to "run an evaluation", "evaluate my agent", "evaluate my ADK agent", "write an eval dataset", "analyze eval failures", "compare eval results", "optimize agent", or needs guidance on the Gemini platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).

AI & Agents513.5K installs

skill-creator

anthropics/skills

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

OfficialAI & Agents416.4K installs

codex-pet

prime-skills/runcomfy-agent-skills

Codex Pet generator on RunComfy. Build a Codex-compatible Codex Pet spritesheet.webp + pet.json from a single reference image, drop it into ${CODEXHOME:-$HOME/.codex}/pets/ / and Codex picks it up as a custom Codex Pet next to the 8 built-ins. This skill produces the exact Codex Pet atlas Codex expects (1536x1872 PNG/WebP, 8 cols x 9 rows, 192x208 cells, 9 animation states — idle, running-right, running-left, waving, jumping, failed, waiting, running, review). Calls OpenAI GPT Image 2 edit ONCE via the local RunComfy CLI as runcomfy run openai/gpt-image-2/edit to produce a canonical Codex Pet pose, then assembles all 9 animation rows programmatically with ImageMagick micro-transforms — no Codex Pro, no $imagegen, no OPENAIAPIKEY required, only RUNCOMFYTOKEN. Triggers on "codex pet", "create codex pet", "make codex pet", "hatch codex pet", "/hatch image", "desktop pet codex", "codex pets", "spritesheet.webp", or any explicit ask to build a custom pet for OpenAI Codex.

AI & Agents402.1K installs

full-output-enforcement

leonxlnx/taste-skill

Overrides default LLM truncation behavior. Enforces complete code generation, bans placeholder patterns, and handles token-limit splits cleanly. Apply to any task requiring exhaustive, unabridged output.

AI & Agents401K installs

executing-plans

obra/superpowers

Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available

AI & Agents245.7K installs