kugetsu/docs/hermes-setup.md

Hermes Setup Guide

Overview

Hermes is the primary orchestrator and gateway in the Kugetsu system. It handles:

• Spawning and managing subagents
• Message passing between agents
• Repository access via Git API
• Task delegation and parallelization

Key Constraint: The delegate_task function has a hard limit of 3 concurrent tasks.

---

Installation via Curl Script

Prerequisites

• Linux/macOS environment
• curl, git, and basic build tools installed
• LLM provider API key (for cloud providers)

Installation Steps

# Clone the Hermes repository
git clone https://git.example.com/shoko/hermes.git ~/repositories/hermes

# Run the installation script
cd ~/repositories/hermes && ./install.sh

# Verify installation
hermes --version

# Initialize with non-interactive mode (if config exists)
hermes init --non-interactive

Alternative: Direct Download

curl -L https://git.example.com/shoko/hermes/releases/latest/download/hermes -o ~/.local/bin/hermes
chmod +x ~/.local/bin/hermes
export PATH="$HOME/.local/bin:$PATH"
hermes --version

---

Programmatic Configuration

If you already have an API token, configure Hermes entirely via files and commands.

Directory Structure

mkdir -p ~/.hermes/skills ~/.hermes/cache

Configure via .env File

Create ~/.hermes/.env:

ANTHROPIC_API_KEY=sk-ant-...
OPENROUTER_API_KEY=sk-or-...
GITEA_TOKEN=your_token
HERMES_DEFAULT_MODEL=openrouter/anthropic/claude-sonnet-4

Configure via config.yaml

hermes:
  name: kugetsu-orchestrator
  log_level: info
  max_parallel_tasks: 3
  task_timeout: 3600

gitea:
  instance: https://git.example.com
  owner: shoko
  repo: kugetsu
  token_env: GITEA_TOKEN

agents:
  default_model: openrouter/anthropic/claude-sonnet-4
  temperature: 0.7
  thinking_enabled: true

Automate Configuration with hermes config set

Set configuration programmatically:

hermes config set agents.default_model "openrouter/anthropic/claude-sonnet-4"
hermes config set agents.temperature 0.7
hermes config set gitea.instance "https://git.example.com"
hermes config set gitea.owner "shoko"
hermes config set gitea.repo "kugetsu"
hermes config set opencode.managed_by "hermes"
hermes config set opencode.default_mode "agent"
hermes config list

LLM Providers with API Key Only

These providers work with just an environment variable or API key:

OpenRouter (Recommended)

export OPENROUTER_API_KEY="sk-or-..."
hermes config set agents.default_model "openrouter/anthropic/claude-sonnet-4"

Supports: Anthropic, OpenAI, Mistral, Llama, Gemini, and more.

Anthropic (Direct)

export ANTHROPIC_API_KEY="sk-ant-..."
hermes config set agents.default_model "anthropic/claude-sonnet-4"

OpenAI Compatible

export OPENAI_API_KEY="sk-..."
hermes config set agents.default_model "openai/gpt-4o"

Groq (Fast, Free Tier)

export GROQ_API_KEY="gsk_..."
hermes config set agents.default_model "groq/llama-3.1-70b"

OpenCode Integration

OpenCode can be managed by Hermes as an orchestrator-controlled coding agent.

Setup

# Install OpenCode
curl -L https://opencode.ai/install.sh | sh

# Configure Hermes to manage OpenCode
hermes config set opencode.managed_by "hermes"
hermes config set opencode.binary_path "~/.opencode/bin/opencode"
hermes config set opencode.default_mode "agent"

Usage

OpenCode runs as a subagent under Hermes:

Task: Write a Python script
Agent: opencode
Model: openrouter/anthropic/claude-sonnet-4

Benefits

• Orchestrated: Hermes manages task routing to OpenCode
• Consistent Context: Shared cache and session management
• Unified Logging: All agent activity flows through Hermes

Verification

# Check version
hermes --version

# List configuration
hermes config list

# Test Gitea connection
hermes doctor

# Run a test task
hermes task status

Troubleshooting

Config not loading

hermes --config ~/.hermes/config.yaml config list

API key not found

export $(cat ~/.hermes/.env | xargs)
hermes config list

Gitea connection failed

curl -H "Authorization: token $GITEA_TOKEN" https://git.example.com/api/v1/user