Deploy Hermes Agent on WSL + Ubuntu in One Command – Get a Self‑Improving AI Assistant

Why Choose Hermes Agent?

Hermes Agent is an open‑source AI assistant that provides persistent cross‑session memory, automatic skill extraction, and access to over 200 large models via OpenRouter. It runs natively on Linux (Ubuntu) and is distributed under the MIT license.

Self‑evolving memory – remembers preferences across sessions.

Automatic skill extraction – frequently used commands become reusable skills.

Multi‑model support – OpenRouter aggregates 200+ models, including Chinese models.

Multi‑platform integration – Telegram, Feishu, WeChat Work, Discord.

Fully open source – MIT license, free to modify and redeploy.

Linux native – officially recommended on Ubuntu.

Prepare the Environment: WSL2 + Ubuntu

What is WSL?

WSL (Windows Subsystem for Linux) is Microsoft’s official layer that runs a native Linux environment directly on Windows.

Why use WSL instead of a VM?

Startup speed: seconds vs. 1‑3 minutes for VMware/VirtualBox.

Memory usage: dynamic allocation vs. fixed allocation.

File sharing: direct access to Windows files vs. shared‑folder setup.

Performance: near‑native vs. noticeable overhead.

System integration: seamless terminal integration vs. separate windows.

Install WSL2 (PowerShell as administrator)

# One‑click install WSL2 with default Ubuntu
wsl --install

⚠️ After installation you must restart the computer; Ubuntu will then prompt you to create a user name and password.

Verify the WSL environment

# Check WSL version (needs WSL2)
wsl --version
# Show Ubuntu version (22.04 LTS or newer recommended)
lsb_release -a
# Test network connectivity (required for later downloads)
ping -c 3 github.com

WSL version: 2.x.xxx.xx
Ubuntu version: 22.04 LTS or 24.04 LTS

💡 If you are unsure whether you have WSL 1 or WSL 2, run wsl -l -v to list distributions and their versions. Upgrade with wsl --set-version Ubuntu 2 if needed.

One‑Command Deployment of Hermes Agent

Step 1 – Install Git (the only manual prerequisite)

sudo apt update && sudo apt install -y git

Step 2 – Run the one‑line install script

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

The script automatically installs:

uv (latest) – Python package manager.

Python 3.11 – runtime.

Node.js v22 – front‑end toolchain.

ripgrep – fast file search.

ffmpeg – audio/video processing.

🔒 Security tip: the curl | bash command runs a remote script directly. To audit first, clone the repository with git clone https://github.com/NousResearch/hermes-agent.git and inspect scripts/install.sh before executing.

Step 3 – Refresh environment variables

source ~/.bashrc   # for bash
source ~/.zshrc    # for zsh

Step 4 – Verify installation

hermes doctor

✅ Python 3.11.x — OK
✅ Node.js v22.x — OK
✅ ripgrep — OK
✅ ffmpeg — OK
✅ Config file — created
⚠️ API Key — not configured

Configure API Keys – Bring Hermes to Life

Interactive setup wizard (recommended for new users)

hermes setup

The wizard asks four questions:

Select an LLM provider (OpenAI, Anthropic, Google, OpenRouter, custom).

Enter the corresponding API key.

Choose a default toolset.

Confirm where the configuration will be saved.

Manual configuration (advanced users)

# ~/.hermes/.env
OPENROUTER_API_KEY=sk-or-v1-yourrouter-key-here
OPENAI_API_KEY=sk-your-openai-key-here
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key-here
GOOGLE_API_KEY=your-google-api-key-here
NOUS_API_KEY=your-nous-key-here
DEEPSEEK_API_KEY=sk-your-deepseek-key-here

Start and Interact

Launch Hermes

hermes

On first launch Hermes loads the config, connects to the chosen LLM service, initializes the memory database, and enters interactive mode. Example output:

╔═══════════════════════════════════════╗
║     🐎 Hermes Agent v2.x.x           ║
║     Self‑improving AI Assistant      ║
╚═══════════════════════════════════════╝
模型：gpt-4o (via OpenRouter)
记忆状态：已就绪
技能数量：0（使用中将自动积累）
> 你好！我是 Hermes，你的自进化 AI 助手。

Practical scenarios

Scenario 1 – Code assistant

你：帮我写一个 Python 脚本，监控 Ubuntu 系统 CPU 使用率，超过 80% 时发送告警
Hermes：（生成完整代码 + 解释 + 使用方法）

Scenario 2 – Linux operations

你：我的 WSL Ubuntu 磁盘空间不够了，帮我分析哪些目录占用最大
Hermes：（调用系统命令分析磁盘占用，给出清理建议）

Scenario 3 – Learning assistant

你：用通俗易懂的方式解释 Linux 权限管理中的 setuid 和 sticky bit
Hermes：（结合生活类比 + 图文解释 + 示例演示）

Advanced Usage – Extend Hermes

Hermes supports modular extensions. Install the desired extras with pip:

pip install "hermes-agent[voice]"
pip install "hermes-agent[messaging]"
pip install "hermes-agent[browser]"
pip install "hermes-agent[image]"
pip install "hermes-agent[vector]"
pip install "hermes-agent[all]"

Integrate a Chinese model (DeepSeek)

# ~/.hermes/config.yaml
model:
  provider: "openai-compatible"
  model_id: "deepseek-chat"
  api_base: "https://api.deepseek.com/v1"
  api_key: "${DEEPSEEK_API_KEY}"

Add the key to ~/.hermes/.env and restart Hermes:

hermes

Connect to enterprise messengers (Feishu / WeChat Work)

Create a bot app on the Feishu Open Platform.

Obtain App ID and App Secret.

Configure event‑callback URL.

Enable the Feishu adapter in Hermes configuration.

Docker deployment (server scenario)

# Pull the official image
docker pull nousresearch/hermes-agent:latest
# Run the container
docker run -it \
  --name hermes \
  -v ~/.hermes:/root/.hermes \
  -e OPENROUTER_API_KEY=your_key_here \
  nousresearch/hermes-agent:latest

Common Troubleshooting (FAQ)

Q1: hermes: command not found

Cause: environment variables not loaded or PATH not set.

# Reload environment variables
source ~/.bashrc
# Verify installation location
which hermes
ls -la $(which hermes)

Q2: Python version error

Cause: Hermes requires Python 3.11.

# Force install correct Python version with uv
uv python install 3.11
uv venv .venv --python 3.11
source .venv/bin/activate

Q3: Connection timeout or API failure

Cause: Unstable access to overseas LLM services from China.

Set an HTTP proxy in .env (e.g., HTTPS_PROXY=http://your-proxy:port).

Use a domestic model such as DeepSeek.

Route through OpenRouter, which is often more stable.

Q4: Update to the latest version

# Update Hermes Agent
hermes update
# Or rerun the install script
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Q5: No microphone/camera in WSL

Cause: WSL2 has limited hardware support.

WSLg on Windows 11 can forward some devices.

Workaround: record audio on Windows and copy into WSL for processing.

Simplest: use text‑only interaction and skip voice features.

Q6: Where are memory and skill data stored?

All data resides in ~/.hermes/:

~/.hermes/
├── skills/        # auto‑accumulated skill files
├── memory/        # persistent memory database
├── personas/      # persona configurations
├── logs/          # runtime logs
├── .env           # API keys (keep secret!)
└── config.yaml   # main configuration file

⚠️ Backup the entire ~/.hermes/ directory regularly; losing it means losing Hermes’s “brain”.

Summary – Six Steps to Get Started

① Install WSL2 + Ubuntu      wsl --install
② Install Git                sudo apt install git
③ One‑click install Hermes  curl … | bash
④ Refresh env vars           source ~/.bashrc
⑤ Configure API key          hermes setup
⑥ Launch and use            hermes

Hermes Agent starts as a simple assistant and gradually learns user preferences, accumulates reusable skills, and becomes a personalized AI agent.