Hermes Agent: install, setup and connecting any model

Install Hermes Agent with curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash on Linux, macOS or WSL2, or with iex (irm https://hermes-agent.nousresearch.com/install.ps1) in Windows PowerShell. Then run hermes model, choose Custom endpoint, and enter a base URL, an API key, a model name and a context size. That works with a local Ollama, a company gateway or any other OpenAI-compatible server. The examples below use Claudexia, because one key there reaches Claude, GPT and DeepSeek and can be paid for with a local card, SBP or crypto.

What Hermes Agent is

Nous Research builds it, and the code lives in the NousResearch/hermes-agent repository under the MIT license. On 10 November it had about 262,000 GitHub stars, and release v0.23.1 shipped that same day. You talk to it in a terminal UI, or from Telegram, Discord, Slack, WhatsApp and Signal through one gateway process.

What sets it apart is that it stays on. It keeps memory across sessions, turns repeated procedures into skills, runs isolated subagents in parallel and executes scheduled jobs. Commands run through one of six terminal backends: local, Docker, SSH, Modal, Daytona or Vercel Sandbox. The README pitches the result as an agent that lives on a $5 VPS while you message it from your phone.

Hermes ships without a model. The README lists Nous Portal, OpenRouter, OpenAI and your own endpoint among the options, and hermes model switches between them. Nous Portal is the project's own subscription (300+ models plus bundled tools). You do not need it when you already hold a key for an OpenAI-compatible endpoint, and Claudexia does not resell it.

Install on macOS, Linux, Windows and Docker

The script clones the source, bootstraps uv, and fetches Python 3.14, Node.js, ripgrep and FFmpeg on its own. It ignores a system Node and uv. Windows needs no administrator rights: everything goes under %LOCALAPPDATA%\hermes, and the installer brings its own Git if yours is missing. Because curl | bash runs someone else's script, open it in a browser and read it first.

Reload your shell afterwards (source ~/.bashrc or source ~/.zshrc) and run hermes. On Windows, open a fresh PowerShell window. The PATH change only reaches new sessions, so the old window will say the command does not exist.

Windows without WSL

Native Windows is fully supported: CLI, gateway, TUI, cron, MCP servers and the browser tool run without WSL. The terminal tool executes commands through Git Bash, the same trick Claude Code uses. Pick WSL2 only if you want a POSIX environment, and remember that its data lives in ~/.hermes instead of %LOCALAPPDATA%.

One thing from the README is worth knowing early. Antivirus software may quarantine uv.exe in the hermes\bin folder. The project calls it a false positive, since the binary belongs to Astral, and recommends excluding the folder rather than the file, because the hash changes with every release.

Servers and Docker

Run the setup wizard once, then start the gateway in the background:

docker run -d --name hermes --restart unless-stopped \
  -v ~/.hermes:/opt/data -p 8642:8642 \
  nousresearch/hermes-agent gateway run

Port 8642 exposes Hermes's own OpenAI-compatible API server and is only needed by the dashboard or external tools. The docs warn that any open port on an internet-facing machine is a risk, so skip the flag if Telegram is all you use. Docker installs cannot run hermes update; you update by pulling a new image.

First run and the setup wizard

On a fresh install hermes setup offers three modes. Quick Setup goes through Nous Portal. Full Setup walks through every provider and tool with your own keys. Blank Slate leaves only the provider, file operations and the terminal switched on. If the machine already holds ~/.openclaw, ~/.claude, ~/.codex or ~/.cursor, the wizard first offers to import settings from there.

For our purposes Full Setup or a direct hermes model is the way. Hermes keeps secrets in ~/.hermes/.env and other settings in ~/.hermes/config.yaml.

Mind one limit before choosing a model: Hermes wants a context window of at least 64,000 tokens and rejects smaller ones at startup. Hosted Claude, GPT and DeepSeek models clear that easily. A local model needs its window set explicitly.

Connect a model through one gateway key

The Hermes docs state that any server implementing /v1/chat/completions can be used as a custom provider. Claudexia is such a server: the base URL is https://api.claudexia.tech/v1, the key starts with sk_cdx_, and no Anthropic or OpenAI account is needed. You top up from $1 by card, SBP (Russia) or crypto (USDT, BTC, ETH, TON), and credits do not expire.

1. Sign up, add funds and create a key in the API keys section of the dashboard.
2. Run hermes model, choose Custom endpoint, and enter the base URL, the key and a model name. When asked about context, type a number instead of leaving it blank.
3. Or write the same thing into config.yaml yourself:

model:
  provider: custom
  default: gpt-6-astra
  context_length: 1000000
  base_url: https://api.claudexia.tech/v1
  api_mode: chat_completions
  api_key: sk_cdx_YOUR_KEY

4. Run hermes and ask for something you can check, such as "Summarize this repo in 5 bullets and tell me what the main entrypoint is". hermes doctor lists anything missing.

The same block works for any other OpenAI-compatible provider; only base_url, the key and the model name change. Instead of api_key you can write key_env: VARIABLE_NAME and let Hermes read the key from the environment. The model ID comes from GET /v1/models or the model catalog, and the same setup is described in our Hermes, OpenClaw and SDKs guide.

Our guide marks context_length as required. The Hermes docs and source show why. The window is looked up through a chain of sources (your config, a cache, the server's /models answer, OpenRouter, models.dev), and if none of them knows the model, Hermes falls back to a default window. In the v0.23.1 source that default is 256K, although the docs page still says 128K, and a model with a smaller real window then fails at the API. A value in config.yaml beats everything else and is labelled pinned.

api_mode: chat_completions works with the text models in the catalog, Claude included, so start there. Image and video models have their own endpoints (/v1/images/generations, /v1/videos) and do not go through chat completions. For Claude the guide also lists anthropic_messages, but we have not tested that mode, and we have not checked how the base URL should be written for it.

A detail that trips people up: the /model command inside a chat only switches between providers you have already configured. To add a new one, leave the session and run hermes model.

The config comes from the Claudexia guide, and the Hermes docs confirm that custom providers are supported. We did not run a live request on v0.23.1 for this article, so confirm the first reply yourself.

Pick a model for the job

Claudexia prices (Premium channel) as of 10 November 2026; the current numbers are on the model catalog page:

At those rates deepseek-v4.1-flash costs about 9 times less than claude-sonnet-5, on input and on output alike. An agent leans on tool calls (terminal, files, browser, search), so test a new model on a task with tools, not with a chat question. The full list of IDs is in the model lineup.

For a trial run the catalog has one zero-price model as of 10 November: deepseek-v4.1-flash-1017-free, with a 1M window. It is neither Claude nor GPT. Limits and conditions sit on the model page, and the tool-calling field is empty for it in the catalog, so treat an agent run on it as an experiment.

What an always-on agent costs, and where to cut

Chat Completions is stateless, so on every step the agent sends the model the system prompt, tool descriptions, skills, a memory snapshot and the history again. Memory itself is small: the docs cap MEMORY.md at 2,200 characters (about 800 tokens) and USER.md at 1,375 characters (about 500 tokens). The money goes elsewhere.

• History compression. It triggers at half the window by default (compression.threshold: 0.50). With context_length: 1000000 that is 500,000 tokens, and until then bulky tool output rides along in every request. The docs suggest trying proactive_prune_tokens: 48000, which collapses old tool results without calling a model. It is off by default.
• Background jobs. Session titles, compression, image analysis and the dangerous-command classifier run on your main model. The docs warn that on an expensive model this adds noticeable cost and show how to override each auxiliary.<task>.
• Subagents. They inherit the parent's model. By default up to 3 run in parallel at depth 1, but cost multiplies: at depth 3 and width 3 the tree can reach 27 leaf agents.
• A ceiling. agent.max_turns is unlimited by default. A number in the config caps the steps in one turn.

Pointing background jobs and subagents at a cheap model takes two blocks:

auxiliary:
  compression:
    model: deepseek-v4.1-flash
    base_url: https://api.claudexia.tech/v1
    api_key: sk_cdx_YOUR_KEY

delegation:
  model: deepseek-v4.1-flash
  base_url: https://api.claudexia.tech/v1
  api_key: sk_cdx_YOUR_KEY

Hermes turns on automatic prompt caching for Claude on native Anthropic, OpenRouter and Nous Portal. The docs say nothing about a custom endpoint, so do not budget for cache savings there. Watch spend with /usage and /insights --days 7, and create a separate gateway key for the agent so its usage shows up on its own line in the dashboard. General tricks for agents are collected in how to cut a Claude Code bill and why agent bills explode.

Hermes and OpenClaw

If you already run OpenClaw, Hermes can take your settings over. hermes import-agent openclaw --dry-run previews the move: the SOUL.md persona, memory entries, your own skills, the command allowlist and messaging settings. API keys travel only with --migrate-secrets. The same command accepts claude-code, codex and cursor. The two agents keep their data in separate directories, so you can try them side by side. For a broader view of coding agents, see the agent comparison and the list of Claude Code alternatives.

Safety defaults

Hermes checks commands against a list of dangerous patterns. approvals.mode: smart is the default: an auxiliary model rates the risk, harmless commands pass, dangerous ones are blocked, doubtful ones come to you for confirmation. manual always asks. off equals the --yolo flag and removes every check, so keep it for isolated environments such as a container.

For isolation set hermes config set terminal.backend docker. Messaging platforms get pairing and a user allowlist. What never to send to a model whatever the setup is covered in what not to send to an LLM.

When something does not work

If none of that fits, hermes doctor names what is missing, and hermes --continue resumes the last session so you can check that saving works.

FAQ

How do I install Hermes Agent on Windows?

Run iex (irm https://hermes-agent.nousresearch.com/install.ps1) in PowerShell; no administrator rights are needed. Open a new terminal window and run hermes. There is also the Hermes Desktop app, whose MSIX package needs Windows 11 22H2 or newer. For a POSIX environment, install inside WSL2 with the Linux command.

Is Hermes Agent free?

The agent is: the license is MIT and there is no subscription for it. You pay for model tokens. Nous Portal is a separate subscription from the project and is optional. The Claudexia catalog has one free model for testing, deepseek-v4.1-flash-1017-free, with limits listed on the model page.

How do I use my own API key or a custom model with Hermes Agent?

Run hermes model and choose Custom endpoint, or add a model block with provider: custom, base_url, api_key and context_length to ~/.hermes/config.yaml. A ready example for Claudexia is above. Changing the model inside one provider takes /model in a chat.

Can I run Hermes Agent on a server or VPS?

Yes. Docker is the easiest way: run setup interactively once, then gateway run in the background with the ~/.hermes:/opt/data volume. Connect Telegram with hermes gateway setup. Publish port 8642 only if you need the dashboard or external access to the API server.

Hermes Agent or OpenClaw: which one should I pick?

OpenClaw is a gateway that connects chats to an agent. Hermes is a personal-agent platform with a CLI, memory, skills and subagents. Run both on one small task with separate keys and compare behavior and token use. hermes import-agent openclaw --dry-run shows what would move if you switch.

How do I switch models in Hermes Agent?

If the provider is already configured, type /model in the chat. For a new provider, leave the session and run hermes model. Subagents and background jobs get their models separately, through the delegation and auxiliary blocks in config.yaml.