Installing Hermes Locally

This lesson walks through a clean Hermes install on macOS or Linux. You'll install uv, clone the repo, run the setup wizard, pick an LLM provider, and verify the runtime with a one-shot task.

Prerequisites

• Python 3.11+ (Hermes is 93%+ Python)
• uv for dependency management — the recommended installer
• An LLM provider: Nous Portal, OpenRouter (200+ models), Anthropic, OpenAI, or a local runtime like Ollama / vLLM
• ~500 MB disk space for the runtime and initial memory indexes

Step 1 — Install uv

uv is the fast, reproducible Python package manager Hermes depends on. One line:

curl -LsSf https://astral.sh/uv/install.sh | sh

Verify:

uv --version

Step 2 — Clone and Install Hermes

git clone https://github.com/nousresearch/hermes-agent.git
cd hermes-agent
uv sync

uv sync reads the lockfile and installs an isolated, deterministic environment. It takes around 60-90 seconds on a clean machine.

Step 3 — Run the Setup Wizard

uv run hermes setup

The wizard asks three questions:

1. Where should Hermes store its home directory? Default ~/.hermes/ — keep it.
2. Which LLM provider do you want to use? The wizard lists:
   • Nous Portal (recommended for getting started)
   • OpenRouter (access to 200+ models via a single API key)
   • Anthropic (Claude Opus / Sonnet / Haiku)
   • OpenAI (GPT-5 family)
   • Ollama (local, zero variable cost)
   • vLLM / custom endpoint
3. Do you want to enable Docker sandboxing by default? Choose yes if Docker Desktop is running. This is the safest default.

After the wizard, ~/.hermes/ contains:

~/.hermes/
├── config.toml          # provider, sandbox, keybindings
├── MEMORY.md            # long-term facts (starts empty)
├── USER.md              # user profile (starts empty)
├── sessions.db          # FTS5 session store
└── skills/              # your self-authored + installed skills

Step 4 — Set Your API Key

If you picked a cloud provider, Hermes prompts for the key. Paste it once — it's saved to ~/.hermes/config.toml with mode 0600 (owner-read-only).

To check:

ls -la ~/.hermes/config.toml
# -rw-------  1 you  staff  ... config.toml

Step 5 — Verify the Install

Run a one-shot task without entering the TUI:

uv run hermes run "print hello from hermes and exit"

You should see streaming output ending with hello from hermes. If this works, your provider is configured, sandbox mode is happy, and Hermes can round-trip to the model.

Then check the doctor:

uv run hermes doctor

This validates:

• Python + uv versions
• ~/.hermes/ permissions
• Provider connectivity
• Docker (if sandbox is enabled)
• Writable skills and memory directories

Any red check needs to be fixed before moving on.

Migrating From OpenClaw

If you already run OpenClaw, the setup wizard detects ~/.openclaw/ and offers:

uv run hermes claw migrate

This command:

• Copies your OpenClaw skill directories into ~/.hermes/skills/
• Translates the skill manifest to the agentskills.io spec
• Imports your local SQLite RAG index into the Hermes FTS5 session store (as a one-time bulk summarization)
• Leaves your original ~/.openclaw/ untouched — the migration is additive

Run hermes doctor again after migration to confirm the imported skills pass validation.

Common Install Problems

What's Next

You now have a working Hermes runtime. The next lesson walks you through your first full interactive session in the Terminal UI — multiline editing, slash commands, interrupt-and-redirect, and how to watch streaming tool output.