# 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

```bash
# 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

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

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

### Configure via .env File

Create `~/.hermes/.env`:

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

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

```bash
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)

```bash
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)

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

### OpenAI Compatible

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

### Groq (Fast, Free Tier)

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

```bash
# 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

```bash
# 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

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

### API key not found

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

### Gitea connection failed

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