Hermes Agent: Installation
Last updated: 2026-08-31
Installing Hermes Agent is like setting up a learning assistant on your computer — install it once, and it's always there ready to help.
💡 Tip: pip installation is recommended for the simplest and fastest setup. Docker is ideal for server deployments. The desktop version suits non-technical users.
📋 Prerequisites: Lesson 1 — Introduction and Core Features
1. What You Will Learn
| # | Content |
|---|---|
| ❶ | System requirements and environment check |
| ❷ | pip installation (recommended) |
| ❸ | Source code installation |
| ❹ | Docker installation |
| ❺ | Installation verification and troubleshooting |
2. Story
(1) Pain Point: Can't Get the Environment Working
Bob wants to try Hermes Agent, but the Python version is wrong, there are dependency conflicts, permission issues... he spent an afternoon and still can't run it.
(2) Solution: Three-Step Installation
Alice got it running in just three steps:
BASH
# 1. Check environment
python --version # Python 3.10+
# 2. One-command install
pip install hermes-agent
# 3. Initialize
hermes init
# Done! Start chatting
hermes chat
Bob followed along and was up and running in 5 minutes.
3. System Requirements
(1) Minimum Requirements
| Component | Minimum | Recommended |
|---|---|---|
| Python | 3.10 | 3.11+ |
| RAM | 4 GB | 8 GB+ |
| Disk | 2 GB | 10 GB+ |
| OS | Linux/macOS/Windows | Linux/macOS |
(2) Environment Check Script
BASH
# One-command environment check
curl -sSL https://hermes.dev/check-env.sh | bash
PYTHON
# Or check with Python
import sys
import platform
print(f"Python: {sys.version}")
print(f"Platform: {platform.system()} {platform.release()}")
print(f"Python >= 3.10: {sys.version_info >= (3, 10)}")
💻 Output:
TEXT
📖 Display only
Python: 3.11.5
Platform: Linux 6.1.0
Python >= 3.10: True
4. Installation Methods
(1) pip Installation (Recommended)
BASH
# Basic installation
pip install hermes-agent
# With all platform support
pip install hermes-agent[all]
# Only specific platforms
pip install hermes-agent[telegram,discord]
# With GPU acceleration (local model inference)
pip install hermes-agent[gpu]
CLI tools after installation:
BASH
hermes --version # Check version
hermes init # Initialize config
hermes chat # Start conversation
hermes serve # Start API server
hermes platform list # List available platforms
(2) Source Code Installation
BASH
# Clone repository
git clone https://github.com/nous-research/hermes-agent.git
cd hermes-agent
# Create virtual environment
python -m venv venv
source venv/bin/activate # Linux/macOS
# venv\Scripts\activate # Windows
# Install dependencies
pip install -e ".[dev]"
# Verify
hermes --version
(3) Docker Installation
BASH
# Pull official image
docker pull nousresearch/hermes-agent:latest
# Run (with interactive chat)
docker run -it \
-v ~/.hermes:/root/.hermes \
-e HERMES_MODEL=gpt-4o \
nousresearch/hermes-agent:latest \
hermes chat
# Using docker-compose
curl -O https://hermes.dev/docker-compose.yml
docker-compose up -d
YAML
# docker-compose.yml
version: "3.8"
services:
hermes:
image: nousresearch/hermes-agent:latest
volumes:
- ./hermes-data:/root/.hermes
environment:
- HERMES_MODEL=gpt-4o
- OPENAI_API_KEY=${OPENAI_API_KEY}
ports:
- "8080:8080"
restart: unless-stopped
5. Initialization
BASH
# Interactive initialization
hermes init
# Initialization will ask:
? Select default model: gpt-4o
? Enter OpenAI API Key: sk-...
? Select storage location: ~/.hermes
? Enable telemetry: No
? Create example skills? Yes
Directory structure after initialization:
~/.hermes/
├── config.yaml # Main config file
├── models.yaml # Model configuration
├── memory/ # Memory storage
│ ├── working/ # Working memory
│ ├── long_term/ # Long-term memory
│ └── user_models/ # User models
├── skills/ # Skill storage
│ ├── built_in/ # Built-in skills
│ └── custom/ # Custom skills
├── tools/ # Custom tools
├── plugins/ # Plugins
└── logs/ # Logs
6. Installation Verification
BASH
# Full verification
hermes doctor
# Output example:
# ✅ Python 3.11.5
# ✅ Hermes Agent v1.0.0
# ✅ Config file exists
# ✅ Memory system OK
# ✅ Skill engine OK
# ✅ Tools registered: 72
# ✅ Model connection: gpt-4o (OK)
# ✅ Storage space: 8.2 GB available
Try It: First Conversation
BASH
hermes chat
> Hello, I'm Hermes!
> I remember information about you (nothing yet, but I'll learn!)
> Try telling me your name and preferences.
me: I'm Alice, I'm a frontend developer, I like TypeScript and React
> Got it! From now on I'll remember:
> - Your name is Alice
> - Frontend developer
> - Prefer TypeScript + React
> What can I help you with?
7. Common Installation Issues
| Issue | Cause | Solution |
|---|---|---|
pip install fails |
Python version too low | Upgrade to Python 3.10+ |
| Permission denied | System directory permissions | Use --user or virtual environment |
| Dependency conflict | Other package version conflicts | Use venv for isolation |
| Docker won't start | Docker not installed/running | Install Docker Desktop |
| Invalid API Key | Key expired or wrong format | Check Key in config.yaml |
| Memory init fails | Directory permissions | chmod 755 ~/.hermes |
BASH
# Clean reinstall
pip uninstall hermes-agent -y
rm -rf ~/.hermes
pip install hermes-agent
hermes init
❓ FAQ
Q Can I install on Windows?
A Yes. Hermes supports Windows 10/11. WSL2 or PowerShell 7+ recommended. Some features (like Shell tools) work better in WSL2.
Q Do I need a GPU?
A No. GPU is only needed for local model inference (via Ollama/vLLM). Cloud API usage requires no GPU.
Q Can it coexist with other Python projects?
A Use a virtual environment (venv/conda) to avoid dependency conflicts. Hermes won't affect other project dependencies.
Q How to update to the latest version?
A
pip install --upgrade hermes-agent. Config files and memory data are preserved.Q How much space does it take?
A Base install ~200 MB, with dependencies ~500 MB. Memory and skill data grows with usage, typically 10-50 MB per month.
Q Can it run on Raspberry Pi?
A Raspberry Pi 4 (4GB) can run it, but only with cloud models. Local model inference requires stronger hardware.
📖 Summary
- Three installation methods: pip (recommended), source, Docker
- pip one-liner:
pip install hermes-agent[all] hermes initfor interactive setup, auto-creates directory structurehermes doctorverifies installation success- Virtual environments prevent dependency conflicts; Docker for server deployments
📝 Exercises
- Basic (⭐): Install Hermes Agent on your computer, run
hermes doctorand confirm all ✅. - Intermediate (⭐⭐): Deploy Hermes Agent using Docker with persistent storage, ensuring data survives restarts.
- Advanced (⭐⭐⭐): Write an automated installation script that detects environment, selects installation method, and auto-configures for one-click deployment.
