202 lines
4.2 KiB
Markdown
202 lines
4.2 KiB
Markdown
# 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
|
|
```
|