How to Install Hermes Agent: Step-by-Step Guide

Hermes Agent is an open-source AI agent you can install on your Mac, Linux, Windows, Docker container, or even your phone. This guide covers exact setup commands for every platform, post-install verification, and when managed hosting saves you time and money. Most installations complete in under two minutes.

System Requirements & Prerequisites

You need Python 3.11 or later, git, and curl. No admin password or cloud account is required for basic installation. These tools come pre-installed on most systems. Check your Python version with 'python3 --version' before you start.

Python 3.11 is non-negotiable because Hermes Agent uses async/await syntax that did not stabilize until 3.11. If you have Python 3.10 or older, your install will fail at the import step. Check your version now: open a terminal or PowerShell and type 'python3 --version'. If you see 3.11 or later, you are ready. If not, download Python from python.org or use Homebrew on macOS ('brew install python@3.11').

Git is required to clone the Hermes Agent repository. On macOS, install it via Homebrew: 'brew install git'. On Ubuntu or Debian: 'sudo apt update && sudo apt install git'. On Windows, download from git-scm.com. Curl is used to fetch dependencies and is almost always present on Unix-like systems. Windows users who choose the desktop installer skip the curl requirement entirely.

No sudo password, AWS keys, or OpenAI account are needed yet. You can install Hermes Agent with zero cloud dependencies. Provider setup, which connects to OpenAI, Anthropic, or a local Ollama instance, comes after installation in a separate step. This flexibility means you can test the installation before deciding which AI model to use.

Choose Your Installation Path

Hermes Agent ships four ways. Pick based on your comfort level and use case. Desktop app is the easiest for first-time users: one-click install, a GUI, no terminal commands. CLI via pip is the fastest for developers: one command, full control, works everywhere Python runs. Docker provides production-grade isolation: your Hermes Agent runs in a sealed container, independent of your system's Python or dependencies. Android/Termux is a mobile option for running Hermes Agent on your phone, though it is an advanced use case.

If you are installing this for the first time, pick Desktop. The app opens in 90 seconds. If you live in the terminal and already use Python tools, pick CLI; it takes two minutes after you paste one command. If you manage servers or want production isolation, pick Docker. Each path is detailed below with exact commands.

Install on macOS

On macOS, use the Desktop app for easiest setup or install via pip for developer-level control. The Desktop app takes 90 seconds and requires zero terminal commands. The CLI approach is one-liner: 'pip install hermes-agent' after ensuring Python 3.11 is active.

Via Desktop App (Recommended for Most Users)

Download Hermes Agent from the official website. You will get a.dmg file. Double-click it and drag the Hermes Agent icon into Applications. Open Spotlight by pressing Command + Space, type 'Hermes', and press Enter. Your first chat window opens immediately. No terminal, no configuration yet.

Via pip (One-liner for Developers)

First, ensure Python 3.11 is your default. If you have multiple Python versions installed via Homebrew, verify:

brew install python@3.11
python3 --version

Then install Hermes Agent with pip:

pip install hermes-agent

If you see a permission error, do not use sudo. Instead, ensure pip is installed for Python 3.11:

python3 -m pip install --upgrade pip
python3 -m pip install hermes-agent

After installation, reload your shell to update the command path:

exec zsh

Test that it works:

hermes --version

You should see a version number (e.g., 'Hermes v0.18'). If you see 'command not found', run 'exec zsh' again and retry.

Install on Linux & WSL2

On Ubuntu, Debian, or WSL2, the one-liner is 'pip install hermes-agent'. Installation takes under two minutes. After install, reload your shell.

Ubuntu / Debian (apt-based)

Update your package manager and install Python 3.11 if needed:

sudo apt update
sudo apt install python3.11 python3.11-venv curl

Verify Python:

python3.11 --version

Install Hermes Agent:

python3.11 -m pip install hermes-agent

Reload your shell:

exec bash

Test:

hermes --version

WSL2 (Windows Subsystem for Linux)

WSL2 on Windows 10 or later runs a real Ubuntu filesystem inside Windows. Follow the Ubuntu steps above inside your WSL terminal. After installation, your 'hermes' command works in the WSL terminal (not directly in Windows PowerShell, but you can run 'wsl hermes' from PowerShell to invoke it).

To access Hermes from PowerShell directly, set up a PowerShell alias in your profile:

echo 'Function hermes { wsl hermes @args }' | Out-File -Append $PROFILE
powershell -NoExit -Command ". $PROFILE"

Then type 'hermes' in PowerShell and it will call the WSL version.

Fedora / Red Hat (dnf-based)

sudo dnf install python3.11 python3.11-pip curl
python3.11 -m pip install hermes-agent
exec bash
hermes --version

Install on Windows (Native)

Windows users have two paths: Desktop app (easiest, click and go) or PowerShell with pip (one-liner). Desktop is recommended if you do not use PowerShell regularly. PowerShell is faster if you live in a terminal.

Via Desktop App (Easiest)

Download the Hermes Agent.msix installer from the official website. Double-click it. Windows will install it to your Start menu automatically. Open it like any Windows app. Your first conversation appears immediately.

Via PowerShell & pip

Download Python 3.11 from python.org. Run the installer. This step is critical: check the box 'Add Python to PATH' before clicking install. Without it, the 'pip' command will not be found.

Open PowerShell (right-click Start, choose 'Windows PowerShell' or search for 'PowerShell'). Verify Python:

python --version

Install Hermes Agent:

pip install hermes-agent

Test:

hermes --version

If you see 'hermes is not recognized as an internal command', Python was not added to PATH during installation. Uninstall Python, reinstall, and check 'Add Python to PATH' again.

Install Hermes Desktop (GUI Application)

The Desktop app is the easiest path for beginners. No terminal commands. A click-and-go installer on macOS (.dmg) and Windows (.msix). Your first chat appears in 90 seconds.

Hermes Desktop is a graphical application that runs the same CLI engine underneath but hides all the terminal complexity. You get a chat interface that feels familiar if you have used ChatGPT.

Why choose Desktop? No terminal knowledge required. Clear visual feedback on what your agent is doing. A built-in provider setup wizard that walks you through connecting OpenAI, Anthropic, or local Ollama. Best for testing Hermes Agent before committing to heavier setups.

Download from the official Hermes Agent website and click Download. Choose your platform. On macOS, you will get a.dmg file: drag it to Applications. On Windows, you will get an.msix file: double-click and Windows installs it automatically.

Launch the app from your applications menu. On first run, the provider setup wizard appears. Follow it to connect your AI provider (OpenAI, Anthropic, etc.). You can skip this and configure it later if you do not have a provider key yet.

Desktop is also ideal if you want to try Hermes Agent with a local model (Ollama) without managing Docker containers. The app can automatically detect Ollama running on localhost:11434 and use it.

Install with Docker

Docker provides complete isolation and is best for production. The one-liner: 'docker run -it --name hermes nousresearch/hermes:latest'. Your container is ready in 30 seconds. For persistence of chat history and configurations, use docker-compose with volume mounts.

Single Container (Quick Test)

If you have Docker installed, the fastest way to try Hermes Agent is:

docker run -it --name hermes nousresearch/hermes:latest

This downloads the official Hermes Agent image and starts an interactive session. You can chat immediately. When you close the session (type 'exit'), the container stops.

The issue with this approach: your chat history, provider keys, and settings disappear when the container stops. For real use, use docker-compose.

Docker Compose (Production Setup)

Create a file called 'docker-compose.yml':

version: '3.8'
services:
  hermes:
    image: nousresearch/hermes:latest
    container_name: hermes-agent
    volumes:
      -./hermes-config:/root/.hermes
      -./hermes-data:/root/hermes-data
    environment:
      - HERMES_PROVIDER=openai
      - HERMES_API_KEY=${HERMES_API_KEY}
    ports:
      - "8080:8080"
    restart: unless-stopped
    stdin_open: true
    tty: true

Create a.env file in the same directory:

HERMES_API_KEY=your-openai-api-key-here

Then start:

docker-compose up -d
docker-compose exec hermes hermes

This setup persists your config and data to./hermes-config and./hermes-data on your host machine. Your chat history survives container restarts.

To stop:

docker-compose down

To view logs:

docker-compose logs -f hermes

Connecting to Local Ollama (No API Keys)

If you run Ollama on your host machine on port 11434, the Docker container can reach it via the Docker host gateway. On macOS/Windows, set the base URL to host.docker.internal:11434. On Linux, use the container's gateway IP (usually 172.17.0.1:11434). Modify your docker-compose.yml environment section:

environment:
  - HERMES_PROVIDER=ollama
  - HERMES_OLLAMA_BASE_URL=host.docker.internal:11434

On Linux systems, replace host.docker.internal with 172.17.0.1:

environment:
  - HERMES_PROVIDER=ollama
  - HERMES_OLLAMA_BASE_URL=172.17.0.1:11434

Post-Installation: Verify & Configure

Run 'hermes doctor' to check your setup. Then configure your AI provider using 'hermes model wizard'. Test with 'hermes chat' and type a simple prompt. Success means you see a response in under 30 seconds.

Step 1: Verify Installation with hermes doctor

The 'hermes doctor' command checks your environment for missing dependencies and misconfigurations:

hermes doctor

You will see output like:

Checking Python version... OK (3.11.2)
Checking required packages... OK
Checking provider configuration... MISSING
Checking network connectivity... OK

If anything shows MISSING or FAILED, the output tells you exactly what to fix. Most common issue: the provider configuration is missing, which we handle in Step 2.

Step 2: Set Up Your AI Provider

Hermes Agent requires an AI provider to function. You have three main options.

OpenAI is the easiest and most stable. Get an API key from platform.openai.com. It costs money based on tokens used, typically $5-50/month for light use. You need at least 64K tokens of context window for Hermes to work well.

AnthropicClaude is an alternative. Get an API key from console.anthropic.com. Similar pricing to OpenAI. Claude handles long documents well.

Local Ollama is free and runs on your machine. Download Ollama from ollama.ai, run 'ollama pull mistral' or 'ollama pull llama2', and Hermes Agent will use it via localhost. No API keys, no charges, slower responses (2-5 seconds vs. 0.5 seconds for OpenAI), but completely private.

Launch the provider setup wizard:

hermes model wizard

This walks you through selecting a provider, entering your API key, and testing the connection. It will ask:

Which provider? (openai / anthropic / ollama / others)
Your API key (if not local)
Which model? (gpt-4, claude-3, mistral, etc.)

After setup, the wizard tests the connection by sending a small test message. If it succeeds, your provider is configured and ready to use.

Step 3: Test Your First Conversation

Start Hermes Agent:

hermes

You will see:

Hermes Agent v0.18 ready.
Type your message or 'help' for commands.
>

Type a simple test prompt:

> What files are in my current directory?

Hermes Agent will call the 'list files' tool and respond with the actual contents of your current directory. This proves the integration is working. Try another test:

> What time is it?

The agent will respond with the current time. If both tests return real data (not errors), your installation is complete and functional.

Run Your First Conversation

Start with 'hermes' from the terminal. Give it tasks that use files or information on your machine: 'Show me files in my Downloads', 'Summarize this document', 'What is my current directory'. Success means it returns actual data, not errors.

The power of Hermes Agent is that it can interact with your machine. Unlike ChatGPT, it can read files, list directories, execute local commands, and respond with real data about your system.

Sample Tasks to Test

After you have configured a provider and run 'hermes', try these conversations to verify everything works.

File browsing: Type 'What is in my home directory?' Hermes will use the file browsing tool and return actual file names from your system.

File reading: Create a test text file with some content. Then ask 'Summarize the file named [your-file].txt'. Hermes will read it and summarize it.

System information: Type 'How much disk space do I have left?' or 'What is my system uptime?'. Hermes will execute system commands and report real data.

Code assistance: Ask 'Create a Python script that prints hello world'. Hermes will generate code. You can ask it to save it, and it will write the file.

Session persistence: Your conversation history is saved. Close Hermes with 'exit', restart it with 'hermes', and type 'What did I ask you about earlier?'. The agent remembers the session.

Understanding the Output

When you ask Hermes a question, you will see several steps. The agent's thinking appears first (if verbose mode is on), showing which tools it is deciding to use. Tool execution comes next: it calls something like 'ls', 'cat', or an API. Tool result shows the output of that action. The agent response is the final answer based on the tool output.

If the tool result shows an error (e.g., 'File not found', 'Permission denied'), that is real feedback from your machine, not a bug. Fix the actual problem (file name spelling, permissions) and try again.

Troubleshooting Common Installation Errors

The most common errors are: 'command not found' (shell not reloaded after pip install), missing Python 3.11 (install via python.org or your package manager), antivirus blocks (Windows/Mac security), and API key errors. Exact fix commands are below.

Error: 'hermes: command not found'

Cause: Your shell has not reloaded the PATH after pip install.

Fix:

exec bash

Or if you use zsh:

exec zsh

Then test again:

hermes --version

Error: 'Python 3.11 not found' or 'ModuleNotFoundError'

Cause: Python 3.11 is not installed, or pip installed Hermes Agent to a different Python version.

Fix: Check which Python version is active:

python3 --version

If it shows 3.10 or older, install 3.11.

macOS (Homebrew):

brew install python@3.11
brew link python@3.11

Linux (Ubuntu/Debian):

sudo apt install python3.11 python3.11-venv python3.11-pip

Windows: Download from python.org, install, and check 'Add Python to PATH'.

Then reinstall Hermes Agent using the correct Python version:

python3.11 -m pip install hermes-agent

Error: Windows Antivirus Blocks Installation

Cause: Windows Defender or third-party antivirus flags the pip install or binary download as suspicious.

Fix: Temporarily disable Windows Defender (Settings > Virus & Threat Protection > Manage settings, toggle 'Real-time protection' off), install Hermes Agent, then re-enable it.

Or add an exception: Settings > Virus & Threat Protection > Manage settings > Add exclusions > Exclude the folder where pip stores packages (usually 'C:\Users[YourName]\AppData\Local\Programs\Python\Python311\Scripts').

Error: 'API key invalid' or 'Authentication failed'

Cause: Your provider API key is not configured, expired, or has extra spaces/characters.

Fix: Check your key has no leading or trailing spaces:

hermes model wizard

The wizard will prompt you again. Paste your key carefully. If you use OpenAI, verify your key starts with 'sk-'.

If your key is correct but still fails, it may have expired. Regenerate it in your provider's dashboard (platform.openai.com for OpenAI, console.anthropic.com for Anthropic).

Error: 'Docker image not found'

Cause: Docker cannot pull the official Hermes Agent image.

Fix: Verify Docker is running:

docker ps

If it says 'Cannot connect to Docker daemon', start Docker Desktop (macOS/Windows) or restart the Docker service (Linux).

Then pull the image explicitly:

docker pull nousresearch/hermes:latest

Then run:

docker run -it nousresearch/hermes:latest

Should You Use Managed Hosting Instead?

Self-hosting (DIY) is free but requires ongoing maintenance, provider key management, and your machine must stay on. Managed hosting saves ops time and guarantees uptime, but costs money. Choose managed hosting if you want to run Hermes Agent 24/7 without thinking about it.

DIY Installation (What You Just Did): Pros and Cons

Pros: Free, no hosting costs. Full control: you choose the provider, model, and all settings. Privacy: your conversations stay on your machine (unless you use a cloud provider like OpenAI). Learning opportunity: you understand how Hermes Agent works end-to-end.

Cons: Maintenance burden. You handle updates, dependency conflicts, and security patches. Uptime depends on your machine. If your laptop sleeps or restarts, Hermes Agent goes offline. Provider key management: you are responsible for storing and rotating API keys securely. No SLA: if something breaks, there is no support contract.

Managed Hosting: Pros and Cons

Managed Hermes Agent hosting removes the ops burden. Opsily offers hosted Hermes Agent in the EU with uptime guarantees and zero ops overhead.

Pros: 99.9% uptime SLA. Opsily guarantees availability; your traffic does not affect it. EU data residency: your conversations and data stay in Europe (GDPR-compliant). Zero ops: Opsily handles updates, backups, and patching. You focus on using the agent. Always-on: no need to run a local machine. Opsily scales for you. Integrated provider setup: Opsily simplifies API key management and billing. Security: ISO 27001-certified data centers.

Cons: Monthly cost (pricing varies based on usage and workload). Less control: you cannot customize every detail of the deployment, though Opsily supports most use cases. Vendor dependency: you depend on Opsily for availability and support.

Decision Framework

Choose DIY if: you are testing Hermes Agent and do not need 24/7 uptime. You want to learn how it works. You have technical ops capacity in-house. You do not have a compliance requirement for EU data residency.

Choose managed hosting if: you need Hermes Agent running 24/7 without managing a machine. Your company operates in the EU and has GDPR requirements. You want automatic updates and patching without thinking about it. You need a support contract and SLA guarantee. You want to avoid the burden of managing provider keys and API usage.

For managed options, check Opsily's /hosting/hermes-agent page for current pricing, SLA details, and deployment options.

Frequently Asked Questions

Q: Can I run Hermes Agent on a $5/month VPS?

Yes, but barely. A $5 VPS (512MB RAM, 1 CPU) will run Hermes Agent but will be slow, especially with larger language models. For under 5 conversations per hour, it works. For production use (100+ daily messages), upgrade to at least 2GB RAM ($10-15/month) or use managed hosting.

Q: Which AI provider should I start with?

OpenAI (GPT-4) is the most stable and fastest if you pay. Anthropic (Claude) is also excellent. If you want free, use Ollama locally with Mistral or Llama 2. Ollama responses are slower (2-5 seconds vs. 0.5 seconds for OpenAI) but require no API keys or costs. See our /hosting/hermes-agent/best-model-for-hermes-agent guide for detailed comparison.

Q: Can I switch AI providers later?

Yes, instantly. Run 'hermes model wizard' again and select a different provider. Your chat history stays intact. This is useful for testing different models without reinstalling.

Q: Does Hermes Agent need internet?

Only if you use a cloud provider (OpenAI, Anthropic, Claude). If you use local Ollama, Hermes Agent works completely offline.

Q: How do I uninstall Hermes Agent?

Via pip: 'pip uninstall hermes-agent'. Via Desktop app: uninstall like any application (macOS: drag from Applications to Trash; Windows: Control Panel > Programs > Uninstall). Via Docker: 'docker rm hermes' to delete the container, 'docker rmi nousresearch/hermes:latest' to delete the image.

Q: Can I run multiple Hermes Agent instances?

Yes. Each CLI instance is independent. For Docker, create multiple containers with different names: 'docker run --name hermes-2 nousresearch/hermes:latest'. Each has its own config and chat history.

Q: Is Hermes Agent secure?

Local installation is as secure as your machine. If you use a cloud provider, your API key is sent to that provider (e.g., OpenAI). Store keys in environment variables, not plain text files. For production, use a secrets manager. Managed hosting like Opsily handles key management for you.

Q: What is the difference between CLI and Desktop?

Desktop is a GUI. CLI is a terminal interface. They run the same engine underneath. Pick Desktop if you prefer visual menus; pick CLI if you live in the terminal or need scripting.

The Bottom Line

Installing Hermes Agent is straightforward: pick your platform (Desktop, CLI, Docker), run one command, configure your AI provider, and start chatting. The process takes under two minutes for Desktop or pip, 30 seconds for Docker.

The tradeoff is real: DIY hosting is free but requires you to manage updates and keep a machine on. If you want always-on Hermes Agent with uptime guarantees and EU data residency, /hosting/hermes-agent managed hosting removes the ops burden.

Start with the Desktop app if you are new to command-line tools. Switch to CLI if you want faster setup and more control. Use Docker or managed hosting if you need production-grade reliability and uptime guarantees.