What Hermes Agent is and why it matters

Install Hermes Agent

One-line install

Windows and Android notes

Quickstart

Pick a provider and model

Prove tool execution early

Configuration that scales

Where configuration and state live

Config precedence and keeping secrets out of config.yaml

Sandbox and execution backends

Skills, memory, and profiles

Typical workflow

A stable baseline

Daily usage that compounds

Messaging gateway for 24/7 access

Updates without drama

Troubleshooting and diagnostics

Fast triage commands

Common installation failures

Provider and model issues

Terminal backend and gateway issues

References Hermes Agent is a self-hosted, model-agnostic AI assistant that runs on a local machine or low-cost VPS, works through terminal and messaging interfaces, and improves over time by turning repeated tasks into reusable skills. It is very similar in functionality to OpenClaw, another self-hosted assistant stack built around tools, memory, and local control. If you want the wider picture of self-hosted assistants, retrieval, and local infrastructure around Hermes, this overview of AI systems ties those topics to the same problems Hermes is trying to solve. For deployment trade-offs and runtime choices, LLM Hosting in 2026: Local, Self-Hosted & Cloud Infrastructure Compared provides the hosting map, while LLM Performance in 2026: Benchmarks, Bottlenecks & Optimization covers the throughput and latency side once Hermes is running. My biased take: Hermes is most interesting when treated as infrastructure, not a tab you occasionally open. Once it runs as a service and has a stable home directory, your prompts start to look less like "chat" and more like "ops". Hermes Agent is an open-source AI agent built by Nous Research. It is designed to run persistently, use tools (terminal, files, web, and more), and improve its own behaviour over time with a skills and memory system. Two design choices are worth spelling out because they shape everything else in this guide. First, Hermes is not locked to a single model provider. The official setup flow supports multiple providers and any OpenAI-compatible endpoint, and switching is done via the hermes model command rather than code edits. Second, Hermes draws a hard line between "conversation" and "execution". The agent can talk all day, but when it needs to act, it does so through explicit tools and a configurable execution backend. That is where safety, reproducibility, and troubleshooting live. Cost and licensing are refreshingly boring. Hermes Agent itself is free software under the MIT licence. If you use hosted models, the ongoing cost is whatever your provider charges. If you run local models, you can avoid API fees entirely. Hermes has a fast install path for Linux, macOS, and WSL2. The official docs keep it intentionally simple. After installation, reload your shell and start the CLI. The installer is not just a thin wrapper. According to the installation guide, it sets up dependencies, the repo, a virtual environment, and the hermes command, then gets you to a first chat-ready state. Native Windows is not supported. The docs recommend WSL2 and running Hermes inside it. For Android, Hermes supports a Termux install path. It is designed to detect Termux and adapt its dependency and environment setup accordingly. The quickest first run is literally just hermes, but a meaningful quickstart means two extra decisions: which model provider to use and which tools should be enabled. Hermes exposes three complementary entry points: A minimal flow looks like this: In terms of what is actually supported, the official Quickstart lists a range of providers and also calls out that Hermes works with OpenAI-compatible APIs. That matters because it includes both hosted services and self-hosted endpoints. Before you build habits around Hermes, it is worth verifying that tool use works in your environment. The Quickstart explicitly suggests terminal usage as a first feature to try. In practice, a small "smoke test" prompt does two jobs: it checks the terminal tool and it validates permission prompts. If Hermes cannot run the terminal tool, skip ahead to Troubleshooting. Terminal backend misconfiguration is one of the most common causes, and the fix is usually obvious once you look at config. Hermes rewards people who understand where it stores state and how it resolves configuration. This is also where many "it worked yesterday" problems come from. Hermes stores its settings and state under ~/.hermes. The official configuration guide documents the layout, including config.yaml for settings, .env for secrets, auth.json for OAuth credentials, SOUL.md for identity, and folders for memories, skills, cron, sessions, and logs. This matters for two reasons. Hermes resolves configuration with a precedence order. At the top are CLI overrides, then config.yaml, then .env, with built-in defaults at the bottom. The nice detail is that hermes config set routes values to the right file: API keys to .env and non-secret settings to config.yaml. Hermes also supports environment variable substitution inside config.yaml via ${VAR_NAME} syntax. This is useful when you want to keep certain values in the environment while still referencing them in structured config. Hermes supports multiple terminal backends that define where shell commands actually run. The config guide lists local, docker, ssh, modal, daytona, and singularity. The opinionated but non-evangelical way to think about this is: A minimal Docker backend example: The docs also describe security hardening for the Docker backend, such as dropping capabilities and disabling privilege escalation. Hermes has two related mechanisms for compounding value. Skills are procedural memory. Hermes can create, update, and delete its own skills and can offer to save an approach as a skill after completing a complex task. Built-in memory is stored as files like MEMORY.md and USER.md under ~/.hermes, and Hermes can also use external memory providers for deeper recall. The memory docs list multiple provider plugins, and the memory providers guide documents an interactive setup flow. If you want multiple independent agents on the same machine, Hermes profiles provide isolation. Each profile gets its own directory with its own config, secrets, memories, sessions, skills, cron jobs, and gateway state. If you treat Hermes like an agent you will keep around, the workflow starts to look like service engineering. A baseline that tends not to rot is: Hermes has a terminal UI rather than a web UI, and it is designed for long sessions with slash commands, resumable sessions, and streaming tool output. In practice, a useful cadence is: The messaging gateway is the piece that makes Hermes feel like an assistant rather than a terminal app. The docs describe it as a single process that connects to multiple platforms, handles sessions, runs cron jobs, and delivers messages. Setup is invoked via hermes gateway setup, and the gateway can run in the foreground or as a user service. The CLI reference documents gateway subcommands like run, install, start, stop, status, and restart. Security for a tool-using bot matters. The gateway docs describe allowlists for specific platforms and a DM pairing flow that issues one-time pairing codes and requires approval via hermes pairing approve. Hermes updates are a first-class command. The updating guide documents hermes update, config migration checks, and a small post-update validation routine including hermes doctor and hermes gateway status. Most Hermes failures are not mysterious. They look mysterious because people only check the model layer and ignore the runtime layer. The CLI reference explicitly positions three commands as the core loop: For logs, hermes logs tails files stored under ~/.hermes/logs. The FAQ and troubleshooting guide lists several recurring problems and their fixes, including Python version issues, uv not found, and permission problems caused by mixing sudo installs with user installs. If you encounter these errors, the docs provide specific remediation steps such as upgrading Python, installing uv, and reinstalling Hermes without sudo. When API keys do not work, the FAQ recommends checking configuration, re-running hermes model, or setting a key directly via hermes config set. It also calls out a common gotcha: keys are provider-specific. For "model not found" problems, the FAQ points back to using hermes model to pick a valid identifier and shows both config and per-session overrides. Rate limiting and context length issues are also covered. The FAQ suggests waiting for 429 errors, switching providers or models, and reducing context pressure via compression or a fresh session. If terminal commands fail immediately, the configuration guide includes a "common terminal backend issues" section and points at the typical causes per backend, including Docker not running and missing SSH variables. It also notes that falling back to local is a valid debugging move when sandbox configuration is in question. For gateway problems, the messaging guide highlights allowlists and pairing as the safe defaults, which means many "bot is silent" incidents are actually authorisation doing its job. Templates let you quickly answer FAQs or store snippets for re-use. Hide child comments as well For further actions, you may consider blocking this person and/or reporting abuse