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)

bash

# 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:

bash

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

bash

# 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

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

bash

# 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

bash

# 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

bash

# 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)

bash

# 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

Create bot with @BotFather
Get token and add to
```
.env
```
Configure in
```
config.yaml
```
:

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

Create application at Discord Developer Portal
Enable Message Content Intent
Configure:

yaml

gateways:
  discord:
    enabled: true
    token: ${DISCORD_BOT_TOKEN}
    command_prefix: "!"
    allowed_roles:
      - "AI Assistant Users"
    allowed_guilds:
      - "1234567890123456789"

Slack App

yaml

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)

bash

# 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

yaml

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):

yaml

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

OpenAI:

yaml

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

Google (Gemini):

yaml

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:

yaml

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

yaml

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

bash

# 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

markdown

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

javascript

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

bash

# 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+)

yaml

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)

yaml

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

yaml

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:

yaml

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

Discord:

yaml

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

Webhooks:

yaml

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

yaml

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

yaml

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'"

bash

# 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

bash

# 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

bash

# 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

yaml

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

5. High costs

bash

# 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

bash

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

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

# Force reload
hermes --reload-skills

Debug Mode

bash

# 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

bash

# 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

yaml

# 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

yaml

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

yaml

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

yaml

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

bash

# 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

bash

# 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

hermes-agent-optimization

NPX Install

Tags

SKILL.md Content

Hermes Agent Optimization

Installation

Quick Local Setup (5 minutes)

Production VPS Setup (One Command)

Manual Installation

Configuration Structure

Environment Variables

Key Commands

Starting Hermes

Management Commands

Systemd Service (Production)

Setting Up Platforms

Telegram Bot

Discord Bot

Slack App

CLI (Always Available)

Model Routing & Cost Optimization

Smart Router Configuration

Provider Setup Examples

MCP Server Integration

Configuration

Testing MCP Servers

Creating Custom Skills

Skill Template

Common patterns

Skill Curator

Durable Execution Features

Kanban Boards (v0.13+)

Persistent Goals

Cron Jobs (No-Agent Watchdogs)

Security Configuration

Production Security Settings

Platform-Specific Security

Observability & Monitoring

Langfuse Integration

Prometheus Metrics

Dashboard Analytics

Troubleshooting

Common Issues

Debug Mode

Validation Commands

Real-World Patterns

Pattern 1: Multi-Model Routing

Pattern 2: Secure Webhook Handler

Pattern 3: Automated Code Review

Pattern 4: Cost-Optimized Local First

Pattern 5: Multi-Platform Broadcast

Reference Architecture

Additional Resources

Quick Reference