Install Hermes Agent: Deploy a Self-Improving AI [2026]

AI agents usually forget everything the moment you close the terminal. Hermes Agent creates skills from experience, improves them during use, and builds a deepening model of who you are across sessions – the agent you deploy today will be more capable in two weeks than it is right now. No code changes needed.

Think of it like muscle memory. A human assistant who’s worked with you for a month knows your preferences, common pitfalls, shortcuts you actually use. Hermes builds the same thing, except it writes executable Python skills instead of mental notes.

Deploying it? The official quickstart assumes you know what WSL2 is and why native Windows won’t work. Doesn’t explain why your 7B Ollama model keeps saying it “doesn’t have permission” (spoiler: it’s not permissions – it’s the 64K context requirement). And nobody mentions that the Termux install silently skips voice features because Android wheels don’t exist for faster-whisper.

This tutorial covers the install path that works, the platform gotchas before you hit them, and the Docker backend setup most guides skip.

System Requirements: What Matters

Hermes works on Linux, macOS, WSL2, and Android via Termux. Native Windows is not supported. Windows users: install WSL2 first. No workaround exists.

The installer handles Python, Node.js, ripgrep, and ffmpeg, but here’s what it won’t tell you:

• Python 3.11 or 3.12 only.Python 3.13 causes pathlib incompatibility and tiktoken pyo3 errors. The uv-based installer downloads Python 3.11 if it’s missing, but manual installs need to specify this.
• 64K context minimum.Models with smaller context windows cannot maintain enough working memory for multi-step tool-calling workflows and will be rejected at startup. Trips up Ollama users running default configs.
• RAM: 4GB minimum, 8GB recommended. Local models need more – 16GB if you’re running a 7B+ model via Ollama with 64K context.
• Disk: 2-5GB for the agent itself, plus model storage if running locally.

Pro tip:Run it on a $5 VPS or serverless infrastructure (Modal, Daytona) that costs nearly nothing when idle instead of tying it to your laptop. Talk to it from Telegram while it works on a cloud VM you never SSH into.

Installation: One Command, Three Gotchas

The official one-liner works on Linux, macOS, and WSL2:

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

The installer handles all dependencies (Python, Node.js, ripgrep, ffmpeg), the repo clone, virtual environment, global hermes command setup, and LLM provider configuration.

After it finishes, reload your shell:

source ~/.bashrc # or source ~/.zshrc

Three gotchas:

1. Android (Termux) installs a limited feature set.Hermes installs a curated [termux] extra because the full [all] extra currently pulls Android-incompatible voice dependencies. You get the core agent, messaging, and cron – but no voice mode (faster-whisper) or browser tools (WhatsApp bootstrap).

2. The installer may add ~/.local/bin to PATH but not apply it immediately.If source ~/.zshrc gives a permission denied error, check permissions with ls -la ~/.zshrc and fix with chmod 644 ~/.zshrc. Or just open a new terminal – PATH changes apply then.

3. Windows users: WSL2 is non-negotiable. No native Windows build, no Docker Desktop workaround, no Cygwin path. Install WSL2, then run the command inside your WSL2 terminal.

First-Time Configuration: Connect a Model

The installer launches the setup wizard. If it didn’t, or you want to reconfigure later:

hermes setup

Choose Quick setup to configure provider, model, and messaging in one flow. The wizard walks you through selecting an LLM provider:

• Cloud APIs: OpenRouter (200+ models), OpenAI, Anthropic, Google, Nous Portal
• Local models: Ollama, llama.cpp, or any OpenAI-compatible endpoint

Critical: Hermes requires a model with at least 64,000 tokens of context. Ollama? Set the context size:

ollama run llama3.1:8b --ctx-size 65536

Then configure Hermes to use it:

hermes model
# Select: Custom OpenAI-compatible endpoint
# Base URL: http://127.0.0.1:11434/v1
# Model name: llama3.1:8b

The wizard prompts for your API keys and writes them to ~/.hermes/.env. One-time setup.

Verify the Install Works

Run diagnostics:

hermes doctor

This checks Python environment, API keys, provider endpoints, directory structure (~/.hermes/), and terminal backend availability.

Check the install version:

hermes --version

Start your first conversation:

hermes

You’ll see a welcome banner with your configured model, available tools, and loaded skills. Type a message and press Enter. The agent has file operations, terminal commands, web search – all out of the box.

If the agent is taking too long, just type a new message and press Enter – it interrupts the current task and switches to your new instructions. Ctrl+C also works.

Docker Backend Setup (Sandboxed Execution)

By default, Hermes runs terminal commands on your machine (the local backend). Six terminal backends are available: local, Docker, SSH, Daytona, Singularity, and Modal. Daytona and Modal offer serverless persistence – your agent’s environment hibernates when idle and wakes on demand, costing nearly nothing between sessions.

Self-hosters use Docker for isolation. Here’s the setup:

1. Install Docker (if not already running):

# macOS: Install Docker Desktop
# Linux:
sudo apt install docker.io
sudo usermod -aG docker $USER
# Log out and back in for group changes to apply

2. Configure Hermes to use Docker:

hermes config set terminal.backend docker

Verify it worked:

hermes config show | grep -A2 terminal

You should see backend: docker.

3. Test execution:

hermes chat -q "Run 'uname -a' and tell me what OS the sandbox is using"

The agent will execute the command inside a Docker container, not your host machine. Docker sandboxes Hermes terminal operations with a read-only root filesystem (configurable), dropped Linux capabilities, and namespace isolation, limiting potential damage if the agent executes a compromised command.

Persistent volumes (e.g., project directories):

# In ~/.hermes/config.yaml
terminal:
 backend: docker
 docker_volumes:
 - "/home/user/projects:/workspace/projects" # read-write
 - "/home/user/datasets:/data:ro" # read-only

Local vs. Docker vs. serverless: the choice depends on trust and cost. Local is fast but risky if you’re testing sketchy prompts. Docker adds ~200ms latency but isolates damage. Modal/Daytona cost pennies per hour of actual compute but add cold-start delay (3-8 seconds) after idle periods. Pick based on your paranoia level and whether you’re paying per-token or per-hour.

Common Install Errors & Fixes

Before posting in Discord or opening a GitHub issue:

# 1. Check version
hermes --version

# 2. Run diagnostics
hermes doctor

# 3. Check logs
hermes logs

Upgrade from OpenClaw

Switching from OpenClaw? Hermes can import your settings, memories, skills, and API keys. The setup wizard (hermes setup) detects ~/.openclaw and offers to migrate before configuration begins.

Manual migration:

hermes claw migrate --dry-run # Preview what would be migrated
hermes claw migrate # Run the migration

The --dry-run flag shows you exactly what will be copied without making changes. Use --preset user-data to migrate settings and memories without API keys, or --overwrite to replace existing Hermes configs.

Uninstall / Cleanup

All Hermes data lives in ~/.hermes/:

• config.yaml – agent configuration
• .env – API keys and secrets
• state.db – session history (SQLite with FTS5)
• skills/ – auto-generated and installed skills
• memories/ – persistent memory files
• logs/ – agent and error logs

To remove Hermes completely:

# Remove the agent binary
rm ~/.local/bin/hermes

# Remove all data (this deletes skills, memory, sessions)
rm -rf ~/.hermes/

# Remove the cloned repo (if you installed manually)
rm -rf ~/hermes-agent/

To keep your data but remove just the binary, only delete ~/.local/bin/hermes. You can reinstall later and your skills/memory will still be there.

Can I run Hermes Agent on native Windows?

No. Native Windows is not supported. Install WSL2 and run the command inside your WSL2 terminal.

Why does my Ollama model keep saying it “doesn’t have permission”?

This is not a permission issue – it is a capability limitation. Models under 7B parameters have low success rates in Tool Calling scenarios. Use 7B+ models or cloud APIs. Also verify your context window is set to at least 64K. I spent 20 minutes debugging this before realizing my llama3:7b was running with the default 2K context – turns out “doesn’t have permission” is Ollama’s way of saying “I literally can’t hold enough information in working memory to call a tool.”

Do I need to keep the terminal open for Hermes to work?

For CLI conversations, yes. For 24/7 operation (Telegram bot, scheduled tasks), run the gateway in the background:

# macOS (launchd)
hermes gateway install

# Linux (systemd user service)
hermes gateway install

# Linux (system-wide, survives reboot)
sudo hermes gateway install --system

The service auto-restarts if it crashes and starts at boot.

Configure your first messaging gateway (Telegram, Discord, Slack) or check the GitHub repo for advanced features like MCP integration, cron scheduling, and multi-agent delegation.