Chapter 2: Source Install

Cuttlefish says: 🦑 "Want to experience the latest features? Want to free-dive through the code? Follow me and build your own Hermes Agent from source!"

Why Install from Source?

The one-click install method covered in Chapter 1 is simple and fast, suitable for most users. However, source installation is a better choice in the following scenarios:

• Get the latest features — The source repository contains the newest features and fixes not yet published to PyPI, keeping you on the cutting edge.
• Contribute — If you want to submit bug reports, feature suggestions, or code contributions to Hermes Agent, source installation is the first step.
• Custom modifications — You can freely modify the source code to customize Agent behavior for your workflow.
• Learn and explore — Reading and debugging the source code is the best way to deeply understand the project architecture.

TIP

If you just want to get started quickly with Hermes Agent, the one-click install from Chapter 1 is perfectly sufficient. Source installation is primarily aimed at developers and advanced users.

Prerequisites

Before you begin, make sure your system has the following tools:

Tool	Minimum Version	Check Command	Description
Git	2.0+	git --version	For cloning and updating the repository
Python	3.10+	python3 --version	Hermes Agent runtime environment
pip	Latest	pip --version	Python package manager
venv	Built-in	python3 -m venv --help	Virtual environment management (included with Python)

Quick check script:

# One-command check for all prerequisites
echo "Git:    $(git --version)"
echo "Python: $(python3 --version)"
echo "pip:    $(pip --version)"
echo "venv:   $(python3 -m venv --help >/dev/null 2>&1 && 'OK' || 'MISSING')"

If you're missing Git, visit git-scm.com to download and install. If your Python version is below 3.10, go to python.org to upgrade.

Clone the Repository

First, clone the Hermes Agent source repository locally:

# Clone the repository
git clone https://github.com/NousResearch/hermes-agent.git

# Enter the project directory
cd hermes-agent

After cloning, your directory structure should look roughly like this:

hermes-agent/
├── README.md
├── requirements.txt
├── setup.py
├── pyproject.toml
├── src/
│   └── hermes/
├── tests/
└── docs/

Create a Virtual Environment and Install Dependencies

To avoid polluting your system Python environment, using a virtual environment is strongly recommended.

Create and Activate a Virtual Environment

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# Linux / macOS:
source venv/bin/activate

# Windows (PowerShell):
.\venv\Scripts\Activate.ps1

# Windows (CMD):
.\venv\Scripts\activate.bat

Once activated successfully, you'll see the (venv) prefix in your terminal prompt.

Install Dependencies

There are two ways to install dependencies — choose as needed:

Option 1: Editable mode install (recommended)

pip install -e .

The -e flag installs in "editable" mode. Any changes you make to the source code take effect immediately without reinstallation. Ideal for developers who need to modify code.

Option 2: Install from requirements

pip install -r requirements.txt

This method only installs runtime dependencies and doesn't register the package with pip. Suitable for users who just want to run (not modify) the code.

WARNING

Each time you open a new terminal window, you need to reactivate the virtual environment (source venv/bin/activate). If you find this tedious, you can add it to your shell configuration file (e.g., ~/.bashrc or ~/.zshrc).

Verify Installation

After installation, run the following commands to verify everything is working:

# Check version
hermes --version

# View help information
hermes --help

If you can see the version number and help information, congratulations — installation successful! 🎉

You can also quickly confirm that editable mode is working:

# Verify in Python
python -c "import hermes; print(hermes.__file__)"

The output path should point to the source files under your cloned hermes-agent/ directory, confirming editable mode is working properly.

After installation, configuration files are still stored at ~/.hermes/.env, consistent with the one-click install method. Detailed configuration steps will be covered in Chapter 3.

Keeping Up to Date

One characteristic of source installation is that you need to manually sync with the upstream repository to get updates.

Regular Update Workflow

# Enter the project directory
cd hermes-agent

# Activate virtual environment
source venv/bin/activate

# Pull latest code
git pull origin main

# Update dependencies (if changed)
pip install -e .

View What Changed

# View recent commits
git log --oneline -10

# View differences since last pull
git log HEAD@{1}..HEAD --oneline

Cuttlefish Tip 🦑

We recommend running git pull regularly (e.g., weekly) to stay in sync with upstream. If you go too long without updating, you may encounter dependency conflicts or feature incompatibilities.

One-Click Install vs Source Install Comparison

Feature	One-Click Install (pip)	Source Install (git)
Installation difficulty	⭐ Easy	⭐⭐⭐ Moderate
Installation steps	1 step	4-5 steps
Latest features	Must wait for release	✅ Get in real-time
Custom modifications	❌ Not supported	✅ Complete freedom
Contributing	❌ Inconvenient	✅ Ready out of the box
Update method	pip install --upgrade	git pull
Dependency management	pip handles automatically	Must sync manually
Disk usage	Smaller	Larger (includes .git)
Target audience	Regular users	Developers / Advanced users
Config file location	~/.hermes/.env	~/.hermes/.env
hermes command	✅ Available	✅ Available

INFO

Both installation methods ultimately provide the same hermes command, and configuration file locations are identical. You can switch between them at any time.

Acceleration Guide for Users in China

Due to network conditions, users in China may experience slow speeds or connection failures when accessing GitHub and PyPI. Here are some practical acceleration options.

GitHub Clone Acceleration

Option 1: Use mirror sites

# Accelerate cloning using a GitHub mirror (using ghfast.top as an example)
git clone https://ghfast.top/https://github.com/NousResearch/hermes-agent.git

Common GitHub mirror sites (choose one that's currently available):

Mirror Site	Usage
ghfast.top	https://ghfast.top/https://github.com/...
ghproxy.cn	https://ghproxy.cn/https://github.com/...
hub.gitmirror.com	https://hub.gitmirror.com/https://github.com/...

WARNING

Mirror sites may be unstable. If one isn't working, try another. For production environments, use official URLs with a proxy.

Option 2: Configure Git proxy

If you have an HTTP proxy (like Clash, V2Ray, etc.), you can configure Git directly:

# Set HTTP proxy (replace with your proxy address and port)
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

# Use proxy only for GitHub
git config --global http.https://github.com.proxy http://127.0.0.1:7890

# Remove proxy settings
git config --global --unset http.proxy
git config --global --unset https.proxy

Option 3: Use SSH + proxy

# Clone via SSH
git clone git@github.com:NousResearch/hermes-agent.git

# Configure proxy in ~/.ssh/config
Host github.com
  ProxyCommand nc -X 5 -x 127.0.0.1:7890 %h %p

pip Install Acceleration

Use a Chinese PyPI mirror to accelerate dependency installation:

# Temporarily use Tsinghua mirror
pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

# Permanently configure mirror
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

Common Chinese PyPI mirrors:

Mirror	URL
Tsinghua University	https://pypi.tuna.tsinghua.edu.cn/simple
Alibaba Cloud	https://mirrors.aliyun.com/pypi/simple
USTC	https://pypi.mirrors.ustc.edu.cn/simple
Douban	https://pypi.douban.com/simple

---

Summary

In this chapter we learned how to install Hermes Agent from source. Let's review the key steps:

1. Confirm prerequisites — Git, Python 3.10+, venv are all essential
2. Clone the repository — git clone to get the source code
3. Create virtual environment — python3 -m venv venv to isolate dependencies
4. Install dependencies — pip install -e . or pip install -r requirements.txt
5. Verify installation — hermes --version to confirm everything's working
6. Keep updated — Regularly git pull to sync with upstream

In the next chapter, we'll proceed to Chapter 3: Initial Setup Wizard to configure your first AI model API and bring the cuttlefish truly "to life"! 🦑