Skip to content

part1-setup.md

Latest commit

 

History

History
199 lines (138 loc) · 5.66 KB

part1-setup.md

File metadata and controls

199 lines (138 loc) · 5.66 KB

Part 1: Setup (Stop Fumbling With Installation)

From zero to working agent in under 5 minutes. Covers what the docs don't.

The Install

One command. That's it.

Linux / macOS / WSL2

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Security tip: Piping scripts directly from the internet to bash executes them sight-unseen. If you prefer to inspect first:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh -o install.sh
less install.sh   # Review the script
bash install.sh

Windows users: Native Windows is not supported. Install WSL2 and run the command from inside WSL. It works perfectly.

What the Installer Does

The installer handles everything automatically:

  • Installs uv (fast Python package manager)
  • Installs Python 3.11 via uv (no sudo needed)
  • Installs Node.js v22 (for browser automation)
  • Installs ripgrep (fast file search) and ffmpeg (audio conversion)
  • Clones the Hermes repo
  • Sets up the virtual environment
  • Creates the global hermes command
  • Runs the setup wizard for LLM provider configuration

The only prerequisite is Git. Everything else is handled for you.

After Installation

source ~/.bashrc   # or: source ~/.zshrc
hermes             # Start chatting!

First-Run Configuration

The setup wizard (hermes setup) walks you through:

1. Choose Your LLM Provider

hermes model

Supported providers:

Provider Best For Env Variable
Anthropic (Claude) Highest quality, best at complex tasks ANTHROPIC_API_KEY
OpenAI (GPT-4.1/o3) Strong tool use, fast OPENAI_API_KEY
OpenRouter Access 100+ models from one key OPENROUTER_API_KEY
Cerebras Fast inference, good for simple tasks CEREBRAS_API_KEY
Groq Very fast, limited context GROQ_API_KEY
xAI (Grok) Good balance of speed/quality XAI_API_KEY
Google (Gemini) Huge context, cheap GEMINI_API_KEY

You can configure multiple providers with automatic fallback. If one goes down, Hermes switches to the next.

2. Set Your API Keys

hermes auth

This opens an interactive menu to add API keys for each provider. Keys are stored in ~/.hermes/.env — never committed to git.

Tip: You can also set keys manually:

echo "ANTHROPIC_API_KEY=<your-key-here>" >> ~/.hermes/.env
chmod 600 ~/.hermes/.env   # Restrict access to your user only

Important: Always run chmod 600 ~/.hermes/.env to prevent other users on the system from reading your API keys.

3. Configure Toolsets

hermes tools

This opens an interactive TUI to enable/disable tool categories:

  • core — File read/write, terminal, web search
  • web — Browser automation, web extraction
  • browser — Full browser control (requires Node.js)
  • code — Code execution sandbox
  • delegate — Sub-agent spawning for parallel work
  • skills — Skill discovery and creation
  • memory — Memory search and management

Recommendation: Enable core, web, skills, and memory at minimum. Add browser and code if you need automation or sandboxed execution.

Key Config Options

After initial setup, fine-tune with hermes config set:

Model Settings

# Set primary model
hermes config set model anthropic/claude-sonnet-4-20250514

# Set fallback model (used when primary is rate-limited)
hermes config set fallback_models '["openrouter/anthropic/claude-sonnet-4-20250514"]'

Agent Behavior

# Max turns per conversation (default: 90)
hermes config set agent.max_turns 90

# Verbose mode: off, on, or full
hermes config set agent.verbose off

# Quiet mode (less terminal output)
hermes config set agent.quiet_mode true

Context Management

# Enable prompt caching (reduces cost on repeated context)
hermes config set prompt_caching.enabled true

# Context compression (auto-summarize old messages)
hermes config set context_compression.enabled true

File Locations

Everything lives under ~/.hermes/:

~/.hermes/
├── config.yaml          # Main configuration
├── .env                 # API keys (never commit this)
├── SOUL.md             # Agent personality (injected every message)
├── memories/           # Long-term memory entries
├── skills/             # Skills (auto-discovered)
├── skins/              # CLI themes
├── audio_cache/        # TTS audio files
├── logs/               # Session logs
└── hermes-agent/       # Source code (git repo)

Important: SOUL.md is injected into every message. Keep it under 1 KB. Every byte costs latency and tokens.

Verify Your Setup

# Check everything is working
hermes status

# Quick test
hermes chat -q "Say hello and confirm you're working"

Expected output: Hermes responds with a greeting, confirming the model connection, tool availability, and session initialization.

Updating

hermes update

This pulls the latest code, updates dependencies, migrates config, and restarts the gateway. Run it regularly — Hermes ships frequent improvements.

What's Next