Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Official Installer and Model Setup

2.1. Official Installer and Model Setup

The install command

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

If you want to inspect the script before running it (recommended for production environments):

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

A few useful options

install.sh --no-venv          # do not create a dedicated virtualenv
install.sh --skip-setup       # skip the interactive setup wizard, configure it yourself later
install.sh --branch main      # choose the git branch to install (default: main)
install.sh --dir <path>       # change the install directory (default: ~/.hermes/hermes-agent)

What happens during the install

The script builds Python 3.11 and Node 22 via uv, clones the source into ~/.hermes/hermes-agent, and then asks whether you want to install the gateway as a background service — if you agree, it automatically invokes the step equivalent to 2.6. It finishes with an interactive setup wizard to configure the model provider.

Notes

  • On environments without an interactive terminal (running via CI/CD, automation scripts), use --skip-setup and configure .env yourself afterwards — the script detects non-interactive mode and will remind you to run hermes gateway install manually later instead of asking on its own.
  • HERMES_HOME (~/.hermes) is the real data folder — know this path from the install step onwards so you can prepare the backup strategy in 1.6.
  • If installing on Android/Termux, note the installer’s specific warning: the system may kill background processes when Termux is suspended — not suitable for the always-on server role.

Initial model setup

After Hermes is installed, configure at least one model provider. The installer normally opens this setup wizard automatically. If you skipped it with --skip-setup, run:

hermes model

This is the interactive entry point for provider setup. Choose a provider, complete its authentication flow (OAuth or API key), and Hermes writes the result to ~/.hermes/config.yaml. The hermes model command configures providers; /model inside a chat session only switches between providers and models that are already configured.

Nous Portal — The Recommended Starting Point

One OAuth, everything included

hermes setup --portal

A single command: log in via OAuth, set Nous as the provider, and enable the Tool Gateway (web search, image generation, TTS, cloud browser — covered in chapter 8) at the same time — no individual API keys needed. This is exactly the choice recommended “if you only have time to set up one integration”.

Access 300+ models through one subscription

/model anthropic/claude-sonnet-4.6    # general purpose, best agentic
/model openai/gpt-5.5-pro             # strong reasoning + tool calling
/model google/gemini-3-pro-preview    # huge context window
/model deepseek/deepseek-v4-pro       # cost-efficient coder

Routing actually runs through OpenRouter underneath — meaning availability and failover mechanics are equivalent to a real OpenRouter API key, the only difference being that billing goes to the Nous subscription instead of per-provider credits.

It does not exclude other providers

If you already configured OpenRouter, Anthropic, or any other provider beforehand, Portal is just one additional option, not a replacement — switch back and forth with /model within a session or hermes model between sessions.

Notes

  • Always check hermes portal info if you suspect requests are not going through the subscription as expected — local configuration can “drift” to another provider without you noticing.
  • Because the Tool Gateway features (8.3, 8.6, 8.7) come bundled with Portal, this is the least-effort choice for newcomers — you avoid having to separately register for Firecrawl, FAL, Browser Use, and OpenAI, one account each.
  • For OpenRouter-specific features (routing preference, sticky sessions, advanced cache_control), note that these extensions are not guaranteed to work through Portal, because the serving backend is not always OpenRouter.

OpenAI Codex — Using Your Existing ChatGPT Subscription

Authentication via device-code OAuth

Hermes authenticates through ChatGPT’s OAuth device-code flow, stores credentials in ~/.hermes/auth.json, and can directly import existing Codex CLI credentials from ~/.codex/auth.json — no re-login needed if you have already used Codex CLI.

Limits to be aware of

The official documentation states clearly: it has not been specifically published which ChatGPT plans are eligible, and how usage through Hermes counts against that plan’s Codex limits — this is a gray area you need to check in practice when using it; there is no guaranteed number up front.

Notes

  • If you already have a ChatGPT subscription used with the Codex CLI, take advantage of the credential import instead of logging in from scratch — save a step.
  • Because usage limits are not clearly defined, closely monitor actual consumption over the first few sessions, especially if you plan to use it for heavy workloads (cron jobs running many turns per day).
  • For coding tasks that lean heavily on strong reasoning, this is the natural choice if you are already familiar with the OpenAI ecosystem — it pairs well with chapter 15 (Development).

Anthropic — Claude via API Key, or Conditional OAuth

Two separate paths, not one

  • OAuth (Claude Max): runs through Claude Code-style authentication, and only works with a Claude Max plan with additional usage credits purchased — the base Max allowance is not consumed by Hermes; only the extra credits/overage you purchase are used.
  • Claude Pro cannot use this OAuth path — instead you must use ANTHROPIC_API_KEY, billed pay-per-token at the standard API rates of the organization that owns the key.
hermes auth add anthropic    # set up OAuth
# or configure ANTHROPIC_API_KEY in .env for the API key path

Notes

  • Confirm exactly which Claude plan you have before choosing an authentication path — confusing Pro with Max is the common cause of OAuth failing for no clear reason.
  • If you only have Claude Pro (not Max), go straight to ANTHROPIC_API_KEY instead of trying OAuth — save debugging time.
  • Claude models via Anthropic directly have a different context window than through another provider (for example, claude-opus-4.6 is 1M on direct Anthropic but only 128K through GitHub Copilot) — always check the actual context length for the exact provider you are using, and do not assume it is fixed by model name.

OpenRouter — One Key, Hundreds of Models

Why this is the popular choice for people who want to experiment

A single OpenRouter API key gives access to 400+ models from 70+ providers, with automatic failover for supported models — one provider having an incident does not interrupt your whole work session.

Minimum context requirement

Most configurations require a model with at least 64K tokens of context — models with a smaller window may be rejected at startup, because the system prompt plus the tool schema can already fill a small window, leaving no room for actual conversation.

Provider Routing — fine-grained control over which backend serves a request

provider_routing:
  sort: "throughput"        # "price" (default), "throughput", or "latency"
  only: ["anthropic"]       # only use these providers
  ignore: ["deepinfra"]     # skip these providers
  order: ["anthropic", "google"]  # try in exactly this order

Shorthand syntax: add :nitro to a model name to prioritize throughput, :floor to prioritize the cheapest price.

Notes

  • For models with low rate limits (free tier, around 20 req/min), multi-step tasks (agentic loops, the improvement loop in chapter 20) hit the ceiling very fast — switch to a provider with higher limits mid-session, or configure a fallback provider when you need heavy workloads.
  • Use data_collection: "deny" in provider_routing if you need to exclude providers that may store/train on your data — important for sensitive work.
  • For comparing many models under the same agent without wanting to manage multiple accounts, OpenRouter is the fastest way to experiment — one key, switch models with /model without any additional configuration.

Local Models — Running Fully On-Machine

The two main options: LM Studio and Ollama

LM Studio is supported as a first-class provider — with authentication, doctor checks, reasoning support, and automatic model listing via /models directly from the app. For other self-hosted endpoints (Ollama, or any OpenAI-compatible server), use custom configuration:

model:
  default: "qwen3.5:9b"
  base_url: "http://localhost:8080/v1"
  context_length: 131072   # set explicitly if the system cannot auto-detect

Why you need to declare context_length manually

The system auto-detects context length through multiple sources (Anthropic API, OpenRouter metadata, models.dev…), but for a self-hosted endpoint, none of those sources knows about your model — you must declare it explicitly to avoid Hermes applying the inaccurate 128K default fallback.

Notes

  • A local model is the right choice for data that must absolutely never leave your machine — consistent with the “keep the sensitive-data processing surface as small as possible” principle repeated in 11.3, 16.6, and 8.7.
  • For local models used for auxiliary tasks (vision, compression, 8.5 and below), carefully check the context window of the summary/compression model — if it is smaller than the main model, compressing context mid-long-conversation can silently fail, losing the middle of the conversation with no replacement summary.
  • Local models are usually not as strong as large cloud models for complex agentic tasks (multi-step tool calling) — consider using one as the main model for simple tasks, combined with a fallback to the cloud when higher accuracy is needed.

After setup: switching models and configuring fallbacks

Once one or more providers are configured, use /model inside a session to switch models:

On-the-Fly Switching

Three levels of switching, three different scopes of impact

/model <provider>/<model>            # change for the current session
/model <provider>/<model> --global   # write to config.yaml, applies to new + current session
/model <provider>/<model> --once     # change for one turn only, auto-restores the old model right after

--once is useful for “asking Opus just this once” (escalating a hard question to a stronger model) or “using a cheap model for a trivial question” — no need to remember to switch back. Note: a single --once switch breaks the prompt-cache prefix twice (switch out, then switch back in) — with a prefix-caching provider (Anthropic, OpenAI), the turn after restoration may be slower than usual because the cache has to be rebuilt.

Fallback providers — automatic switching when something goes wrong

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4
  - provider: nous
    model: anthropic/claude-sonnet-4.6

When the primary provider encounters an error (rate limit, overload, authentication failure, connection loss), Hermes automatically switches to a backup provider mid-session without losing the conversation. The chain is tried one entry at a time; activation happens only once per session — it does not keep retrying the whole chain continuously.

Auxiliary task routing — separating the auxiliary model from the main model

By default, auxiliary tasks (image analysis, web page summarization, context compression, session naming) route through exactly the main model you chose — convenient, but potentially expensive if the main model is a pricey reasoning type (Opus, MiniMax M2.7…). Explicitly set a cheap/fast model for these auxiliary tasks, independent of the main model:

auxiliary:
  vision:
    provider: openrouter
    model: google/gemini-flash
  compression:
    provider: openrouter
    model: google/gemini-flash

Notes

  • Configuring fallback providers should be mandatory for any production workload (especially cron jobs in 17.4/18) — a provider hitting its rate limit in the middle of the night should not break an important job.
  • Always check that the context window of the auxiliary compression model is at least equal to the main model — if it is smaller, the context compression command will fail and silently lose the middle of the conversation, exactly the risk mentioned above.
  • Use --once for the occasional questions that need an expensive model, instead of switching --global and forgetting to switch back — avoiding accidentally running the entire rest of the session on a more expensive model than necessary.

Installation checklist

  1. Install Hermes with the official script.
  2. Configure at least one model provider.
  3. Run hermes doctor after provider setup (see 2.4).
  4. Start a chat session and verify that the selected model can respond.
  5. Configure the long-lived service only after the installation works.