Quick Start

Prerequisites

• Python 3.10+ (3.11+ recommended)
• Git
• curl (pre-installed on most systems)
• At least 2GB RAM

Step 1: Install Hermes Agent

Option A: One-Line Script (Linux / macOS / WSL2)

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

China Mirror (Faster for users in mainland China)

curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

Option B: pip

pip install hermes-agent

Option C: Docker

docker pull nousresearch/hermes-agent:latest
docker run -it -v ~/.hermes:/root/.hermes nousresearch/hermes-agent:latest

Option D: From Source

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
pip install -e .

Step 2: Reload Shell

source ~/.bashrc    # Bash users
# OR
source ~/.zshrc     # Zsh users (macOS default)

Step 3: Verify Installation

hermes --version    # Should show v0.13.0+
hermes doctor       # Check dependencies and configuration

Step 4: Configure Your LLM

hermes model        # Interactive model configuration wizard

You’ll need an API key from one of the supported providers. Hermes Agent supports 20+ LLM backends:

Provider	Get API Key	Notes
DeepSeek	platform.deepseek.com	Great for China users
OpenRouter	openrouter.ai/keys	Access 100+ models
Anthropic	console.anthropic.com	Claude models
OpenAI	platform.openai.com	GPT-4o, GPT-4.1
Kimi (Moonshot)	platform.moonshot.cn	Good for Chinese tasks
Google Gemini	aistudio.google.com	Gemini 2.5 Pro
Groq	console.groq.com	Ultra-fast inference
Together AI	api.together.ai	Open-source models
Fireworks AI	app.fireworks.ai	Fast open-source inference
Mistral	console.mistral.ai	Mistral models
Cohere	dashboard.cohere.com	Command R+
Perplexity	perplexity.ai/settings	Online-augmented models
Azure OpenAI	Azure Portal	Enterprise OpenAI
AWS Bedrock	AWS Console	Claude, Llama on AWS
Ollama	Local	Run models locally
vLLM	Local	Self-hosted inference
LM Studio	Local	GUI local models
SiliconFlow	siliconflow.cn	China-based inference
Zhipu AI	open.bigmodel.cn	GLM-4 models
Qwen (Dashscope)	dashscope.aliyun.com	Qwen 3 models

💡 For users in China: DeepSeek, Kimi, SiliconFlow, Zhipu AI, and Qwen offer the best experience with no additional network configuration needed.

Manual Configuration

If you prefer to edit the config directly:

~/.hermes/config.yaml

llm:
  provider: openrouter
  model: anthropic/claude-sonnet-4-20250514
  api_key: sk-or-...

Step 5: Start Your First Chat

hermes chat

Try asking it something:

> Hello! Can you help me write a Python script to fetch weather data?

Step 6: Verify Your Session

After sending your first message, check that everything is working:

hermes doctor    # Re-run to confirm LLM connectivity

You should see:

• ✅ LLM connection successful
• ✅ Memory system active
• ✅ Skills directory ready

Try the Core Features

Terminal Commands Inside Chat

Type / to see available slash commands:

Command	What It Does
/help	List all commands
/model	Switch models mid-conversation
/memory	View or search agent memory
/skills	List learned skills
/save	Save current conversation
/clear	Clear conversation history
/cost	Show token usage this session
/export	Export conversation to file

Multi-Line Input

For longer prompts, use triple quotes:

> """
> Write a function that:
> 1. Fetches data from an API
> 2. Parses the JSON response
> 3. Handles errors gracefully
> 4. Returns a pandas DataFrame
> """

Or use the --multiline flag when starting:

hermes chat --multiline

Interrupting the Agent

If the agent goes off track or you want to stop mid-generation:

• Press Ctrl+C once to interrupt the current response
• Press Ctrl+C twice quickly to exit the chat
• The agent saves its state, so you can resume without losing context

File Operations

The agent can read, write, and edit files directly:

> Read the file src/main.py and add error handling to the database connection function

Web Search

> Search for the latest Python 3.13 release notes and summarize the key changes

Add the Next Layer

Once you’re comfortable with basic chat, here’s how to unlock Hermes Agent’s full power:

🤖 Connect to a Messaging Platform (Bot Mode)

herms chat --platform telegram    # Telegram bot
herms chat --platform discord     # Discord bot
herms chat --platform wechat      # WeChat (via wechaty)

See Platform Configuration for detailed setup guides.

⏰ Schedule Tasks with Cron

hermes cron add "0 9 * * *" "Summarize my unread emails"

See Cron Jobs for scheduling syntax and examples.

🐳 Deploy with Docker

docker-compose.yml

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    volumes:
      - ./hermes-data:/root/.hermes
    environment:
      - LLM_API_KEY=${LLM_API_KEY}

See Docker Deploy for production setup.

🎙️ Voice Mode

hermes chat --voice    # Enable voice I/O

See Voice Configuration for STT/TTS setup.

🧩 Install Skills

hermes skill install web-scraper    # From skill registry
hermes skill create my-skill        # Create your own

See Skills System for the full guide.

🔌 Connect External Tools (MCP / ACP)

Hermes Agent supports the Model Context Protocol (MCP) and Agent Communication Protocol (ACP) to connect external tools:

~/.hermes/config.yaml

mcp:
  servers:
    - name: filesystem
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]

See MCP Protocol and ACP Integration for details.

Common Failure Modes

Problem	Cause	Fix
command not found: hermes	Shell not reloaded	Run source ~/.bashrc or restart terminal
LLM connection failed	Invalid API key	Run hermes model to reconfigure
ModuleNotFoundError	Broken Python install	Reinstall: pip install --force-reinstall hermes-agent
Permission denied: ~/.hermes/	Wrong directory owner	sudo chown -R $(whoami) ~/.hermes/
Agent hangs without response	Network/firewall issue	Check proxy settings; try a different provider
Rate limit exceeded	Too many requests	Wait 60s or switch to a higher-tier API plan
Memory not persisting	Multiple instances writing	Ensure only one instance uses ~/.hermes/
Chinese text garbled in output	Terminal encoding	Set export LANG=en_US.UTF-8 or use a modern terminal

Recovery Toolkit

If something goes wrong, try these in order:

1. hermes doctor — Diagnose common issues automatically
2. hermes config reset — Reset configuration to defaults (keeps memory and skills)
3. hermes cache clear — Clear temporary caches
4. hermes session list — See active sessions; hermes session kill --all to clean up
5. Backup and clean start:

cp -r ~/.hermes ~/.hermes.backup    # Backup everything
rm -rf ~/.hermes                     # Nuclear option
hermes model                         # Reconfigure from scratch

Configuration File

All configuration is stored in ~/.hermes/:

~/.hermes/
├── config.yaml      # Main configuration
├── memory/          # Persistent memory storage
├── skills/          # Auto-generated and custom skills
├── sessions/        # Session history
└── logs/            # Runtime logs

⚠️ Important: Do not run multiple Hermes Agent instances writing to the same ~/.hermes/ directory simultaneously.

Next Steps

• Learning Path — Structured learning roadmap by role
• Install on Linux — Detailed Linux installation guide
• Connect to WeChat — Set up WeChat integration
• Skills System — Learn about the self-learning skill system