Chapter 1: One-Click Install 🚀

⏱️ In just 5 minutes, you can have your own AI assistant!
Cuttlefish 🦑 can't wait to meet you. Let's get started!

1. Prerequisites Check 🔍

Before installing Hermes, let's make sure your system is ready. Don't worry — just a few things to check.

Supported Platforms

Platform	Support Status
macOS	✅ Fully supported
Linux	✅ Fully supported
WSL2 (Windows Subsystem for Linux)	✅ Fully supported
Android (Termux)	✅ Fully supported
Native Windows	❌ Not supported; please use WSL2

🪟 Windows Users Note

If you're on Windows, please install WSL2 first, then work within the WSL2 terminal. Open PowerShell and run:

bash

wsl --install

After installation, restart your computer and open Ubuntu from the Start menu.

Check Python Version

Hermes requires Python 3.10 or higher. Open your terminal and run:

bash

python3 --version

You should see output like:

Python 3.10.12

💡 Tip

If your Python version is below 3.10, please upgrade first:

macOS: brew install python@3.12
Ubuntu/Debian: sudo apt install python3.12
Other Linux: Refer to your distribution's package manager

Check curl

bash

curl --version

If you see a version number, you're good ✅

Check Git

bash

git --version

If you see a version number, you're good ✅

Extra Steps for macOS

If you're on macOS, you may also need to install Xcode Command Line Tools:

bash

xcode-select --install

Click "Install" in the popup, and continue once it's done.

Extra Steps for Linux

Ubuntu / Debian users may need to install build tools and virtual environment support:

bash

sudo apt update
sudo apt install -y build-essential python3-venv

2. One-Click Install ✨

Here's the command — copy and paste it into your terminal, then press Enter:

bash

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

Then sit back, grab a cup of coffee ☕, and let the script do the work.

What does this command do?

Step	Description
`curl -fsSL`	Silently downloads the install script (`-f` no HTML on error, `-s` silent, `-S` show errors, `-L` follow redirects)
Download `install.sh`	Fetches the install script from the official GitHub repository
`\| bash`	Pipes the script content directly to bash for execution

The script automatically performs the following:

📋 Detects your OS and Python version
📦 Creates an isolated Python virtual environment (doesn't pollute system environment)
📥 Installs Hermes Agent and its dependencies from PyPI
🔧 Configures the PATH environment variable to make the hermes command globally available
🏗️ Initializes the configuration directory ~/.hermes/

🔒 Security Note

If you're uncomfortable piping a remote script directly to bash (totally reasonable!), you can download and review it first:

bash

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh -o install.sh
cat install.sh    # Review the script content
bash install.sh   # Execute once you've confirmed it's safe

🌏 Network Acceleration for Users in China

If you're in mainland China, downloads may be slow due to network conditions. Set a proxy before installing:

bash

export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

🚀 Proxy Tips

Replace 127.0.0.1:7890 with your own proxy address and port. Common ones include:

Clash: http://127.0.0.1:7890
V2RayN: http://127.0.0.1:10809
Shadowsocks: http://127.0.0.1:1080

To avoid setting it manually every time, add the two export lines to your ~/.bashrc or ~/.zshrc.

3. Post-Install Steps 🔄

After the install script finishes, you need to let your terminal know where the new command is.

Refresh Environment Variables

Run the appropriate command for your shell:

bash

# macOS default shell (zsh)
source ~/.zshrc

# Linux default shell (bash)
source ~/.bashrc

🤔 Not sure which shell you're using?

Run this command to check:

bash

echo $SHELL

Output /bin/zsh → use source ~/.zshrc
Output /bin/bash → use source ~/.bashrc

Verify Installation

bash

hermes --version

If you see a version number, congratulations — installation successful! 🎉

hermes 0.x.x

🦑 Cuttlefish says: Seeing the version number feels like unboxing a package — so satisfying!

4. First Launch 🎮

Time for the cuttlefish to make its debut! In the terminal, type:

bash

hermes

On first run, Hermes will:

📁 Create the configuration directory structure under ~/.hermes/
🎨 Launch the interactive interface
🤖 Wait for your first command

You'll see a welcome screen — Cuttlefish 🦑 is ready to serve you!

What does the configuration directory look like?

~/.hermes/
├── config.yaml      # Main configuration file
├── history/         # Conversation history
└── plugins/         # Plugin directory

Try asking anything, for example:

Hello, Cuttlefish! What can you do?

To exit Hermes, press Ctrl + C or type /exit.

5. Quick Health Check 🩺

Hermes has a built-in "doctor" command that checks if everything is working properly:

bash

hermes doctor

It checks the following items:

Check Item	Description
✅ Python environment	Python version and virtual environment status
✅ Network connectivity	Whether it can reach API services
✅ Configuration files	Whether configuration is complete
✅ Dependency integrity	Whether all required dependencies are installed

If all items show ✅, everything is fine and you're ready to go!

If any item shows ❌, hermes doctor will provide repair suggestions.

6. Common Issues & Troubleshooting 🔧

Don't panic if you run into problems — let's solve them one by one!

❌ permission denied

Symptoms:

Permission denied: '/usr/local/bin/hermes'

Solution:

bash

# Option 1: Add write permission to the install directory
sudo chmod +x /usr/local/bin/hermes

# Option 2: Re-run the install script (installs to user directory)
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

💡 Option 2 is recommended

The install script defaults to the user directory and generally doesn't need sudo. If you encounter permission issues, prefer re-running the install script.

❌ Python version too old

Symptoms:

Error: Python 3.10+ is required, found 3.8.x

Solution:

Install a newer version of Python:

bash

# macOS
brew install python@3.12

# Ubuntu / Debian
sudo apt update
sudo apt install python3.12 python3.12-venv

# Verify after installation
python3.12 --version

Then re-run the install script.

❌ Network connection failure

Symptoms:

Failed to connect to raw.githubusercontent.com
# or
Could not fetch URL https://pypi.org/...

Solution:

bash

# 1. Check if network is reachable
ping -c 3 github.com

# 2. If not, set a proxy
export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890

# 3. Try installing again
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

❌ Proxy settings issue

Symptoms:

Connection timed out
# or
curl: (7) Failed to connect to 127.0.0.1 port 7890

Solution:

bash

# 1. Confirm proxy software is running

# 2. Confirm proxy port is correct (check in proxy software)

# 3. Test if proxy is working
curl -x http://127.0.0.1:7890 https://www.google.com

# 4. If you no longer need the proxy, unset it
unset http_proxy https_proxy

❌ command not found: hermes

Symptoms:

hermes: command not found

Solution:

bash

# 1. Confirm installation completed successfully
ls ~/.local/bin/hermes

# 2. Confirm PATH includes the install path
echo $PATH

# 3. Reload shell configuration
source ~/.bashrc    # Linux
source ~/.zshrc     # macOS

# 4. If it still doesn't work, manually add to PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc   # Linux
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc    # macOS
source ~/.bashrc    # or source ~/.zshrc

❌ Still not working?

If none of the above solutions resolve your issue:

Run hermes doctor to see detailed diagnostic information
Search or submit an issue at GitHub Issues
When filing an issue, include the output of hermes doctor so maintainers can help you faster

✅ Summary

Great job! 👏 In this chapter, we:

✅ Checked system prerequisites
✅ Installed Hermes Agent with a single command
✅ Verified the installation was successful
✅ Completed the first launch
✅ Ran a health check with hermes doctor

Cuttlefish 🦑 has made its home in your terminal! Next, let's explore another installation method.

👉 Next Chapter: Chapter 2: Source Install

Chapter 1: One-Click Install 🚀 ​

1. Prerequisites Check 🔍 ​

Supported Platforms ​

Check Python Version ​

Check curl ​

Check Git ​

Extra Steps for macOS ​

Extra Steps for Linux ​

2. One-Click Install ✨ ​

What does this command do? ​

🌏 Network Acceleration for Users in China ​

3. Post-Install Steps 🔄 ​

Refresh Environment Variables ​

Verify Installation ​

4. First Launch 🎮 ​

5. Quick Health Check 🩺 ​

6. Common Issues & Troubleshooting 🔧 ​

❌ permission denied ​

❌ Python version too old ​

❌ Network connection failure ​

❌ Proxy settings issue ​

❌ command not found: hermes ​

❌ Still not working? ​

✅ Summary ​

Chapter 1: One-Click Install 🚀

1. Prerequisites Check 🔍

Supported Platforms

Check Python Version

Check curl

Check Git

Extra Steps for macOS

Extra Steps for Linux

2. One-Click Install ✨

What does this command do?

🌏 Network Acceleration for Users in China

3. Post-Install Steps 🔄

Refresh Environment Variables

Verify Installation

4. First Launch 🎮

5. Quick Health Check 🩺

6. Common Issues & Troubleshooting 🔧

❌ permission denied

❌ Python version too old

❌ Network connection failure

❌ Proxy settings issue

❌ command not found: hermes

❌ Still not working?

✅ Summary