CCHPCCHPDocs
↑↓↵pagefind
Documentation

Chapter 4412 min read

Connect Hermes Agent

Install Hermes Agent on macOS, Linux, or Windows and connect it to the CCHP gateway with an LLM key. Add a custom endpoint with the hermes model wizard or the config file, enter the model ID and context length, and verify the connection.

Hermes Agent is an open-source AI agent from Nous Research that you can use in a terminal, a desktop app, and chat apps. It calls the CCHP gateway in the OpenAI-compatible Chat Completions format. After you install Hermes Agent, you need only the gateway URL, an LLM key, the model ID, and the model’s context length to connect it.

What you need#

  • LLM key: A full key with the status Active (not the masked key in the list). If you don’t have one yet, see Create an LLM key.
  • Network: The installation downloads the Hermes Agent code and the tools it needs, such as Python and Node.js, from GitHub and other sites. Make sure that your computer can reach github.com.

Already installed Hermes Agent? Skip to configuration.

Step 1: Install Hermes Agent#

Select your operating system and pick any installation method. The first method in each tab is the officially recommended one. Installing Hermes Agent with Homebrew, pip, or uv isn’t officially supported, so don’t use these methods.

When you run the install script in a terminal, the script opens the Hermes Agent setup wizard (titled Hermes Agent Setup Wizard) before it finishes, and the wizard recommends signing in to Nous Portal by default. You don’t need this wizard to connect to CCHP: when you see it, press Esc to exit, and the installation continues to completion. You configure CCHP in step 4.

System requirements: a Mac with Apple silicon (M series). Macs with Intel chips aren’t officially supported.

Official install script (recommended)

Open Terminal and run:

bash
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

The script installs the program to ~/.hermes/hermes-agent/ and the hermes command to ~/.local/bin/, and it automatically downloads the tools it needs, such as Python and Node.js, so you don’t need to install them first. The script needs Git: if your Mac doesn’t have the Apple command line developer tools yet, macOS opens an installation dialog. After you complete the installation as prompted, the script continues automatically.

When the installation finishes, the terminal shows Hermes Agent install complete. Run: hermes. Open a new terminal window or run source ~/.zshrc, and then use hermes. To update, run hermes update.

Hermes Desktop app

Requires macOS 12 or later.

  1. Go to the Hermes website, hermes-agent.nousresearch.com, and click Download desktop app in the Mac OS column to download Hermes-Setup.dmg.
  2. Open Hermes-Setup.dmg, run the installer in it, and follow the prompts to complete the installation. The installer installs Hermes Agent (including the hermes command) and then builds the desktop app, which takes a few minutes.
  3. The first time you open the desktop app, it asks you to choose a model provider. Click the link that skips this step (I'll choose a provider later in the English UI). You configure CCHP in step 4.

If you already installed Hermes Agent with the install script, you don’t need to download the installer: run hermes desktop in a terminal to build and open the desktop app.

After the installation, open a new terminal window and run:

bash
hermes --version

Result: The first line of the output starts with Hermes Agent v, followed by the version number. If you use Docker, run docker run --rm nousresearch/hermes-agent --version to check. If hermes can’t be found, make sure that you’re in a terminal window that you opened after the installation finished. If you run into problems installing or running Hermes Agent, run hermes doctor, which lists the missing components and how to fix them.

After installation: Configure CCHP#

Recommended: Use Magpie or CC Switch to configure CCHP through a graphical interface. Once you verify the connection in that guide, you can start using the client without following the manual steps on this page.

Configure manually: Start at step 2 to get the gateway URL and model details, then use the Hermes Agent wizard or edit the config file yourself. Verify the connection in step 5.

Step 2: Get the gateway URL#

In the sidebar, click API Keys, then copy the URL in the OpenAI row of the API base URLs card at the top of the page, for example https://api.cchp.example.com/v1. Hermes Agent uses this URL, which ends with /v1.

If the page doesn’t show this card, your admin hasn’t set the gateway public URL yet. Ask your admin for the gateway URL, and add /v1 at the end.

Step 3: Choose a model#

In the sidebar, click Models & Pricing, find the model you want to use in Hermes Agent, and note two things:

  • Model ID: the monospace text under the model name, for example claude-opus-5-5. Click the card to open the details, then click the model ID to copy it.
  • Context length: Ctx on the model card, or Context length in Overview in the details, for example 1M.

Hermes Agent requires a context length of at least 64,000 tokens, and it rejects smaller models at startup. Hermes Agent can’t read the context length from CCHP. If you don’t enter it, Hermes Agent can only estimate it from the model name, and the estimate may not match the actual value, so you enter it manually in step 4. Hermes Agent relies on tool calls to complete tasks, so choose a model with the Function calling capability badge.

To find models, see View available models.

Step 4: Configure Hermes Agent#

You can use the Hermes Agent setup wizard or edit the config file directly. Pick either one. If you installed Hermes Agent with the desktop app, you also complete this step in a terminal.

Hermes Agent saves its config in the data directory: the key in the .env file, and the other settings in config.yaml.

  • macOS, Linux, WSL2, and Docker: ~/.hermes/
  • Windows: %LOCALAPPDATA%\hermes\

Run the command below in a terminal, not in a Hermes Agent conversation. If a conversation is open, enter /quit to exit it first. If you use Docker, run docker run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent model.

bash
hermes model

In the provider list, select Custom endpoint (enter URL manually), then fill in the prompts:

  1. API base URL: Paste the gateway URL from step 2, for example https://api.cchp.example.com/v1.
  2. API key: Paste the LLM key. The characters you enter appear as *.
  3. The wizard uses this key to request the gateway’s model list. A line that starts with Verified endpoint via https://api.cchp.example.com/v1/models means that the URL and the key work. If a line that starts with Warning: could not verify this endpoint appears, press Ctrl+C to cancel, check the URL and the key, and run the command again.
  4. Select API compatibility mode: Enter 2 to select Chat Completions.
  5. Select the model: The wizard lists the models that this key can call. Enter the number in front of a model, or enter the model ID from step 3 directly. If only one model is listed, the wizard asks whether to use it. Press Enter to confirm.
  6. Context length in tokens: Enter the context length from step 3 as an integer, for example 1000000 for 1M and 200000 for 200K.
  7. Display name: Enter CCHP. The next time you run hermes model, the provider list shows this name.

Result: The wizard shows Default model set to: claude-opus-5-5 (via https://api.cchp.example.com/v1). The key is saved in the .env file in the data directory, and the other settings are saved in config.yaml.

Step 5: Verify the connection#

In a terminal, run hermes to start Hermes Agent. If you use Docker, run docker run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent.

Result: The welcome banner shows the model and the context length you configured, for example claude-opus-5-5 · 1M context. If you used the config file, (pinned) also appears after the context length.

Send a message, for example “Introduce yourself in one sentence.” If Hermes Agent replies normally and you can continue the conversation over several turns, the connection works. The desktop app and the command-line version share the same config, so new conversations in the desktop app also use this model.

In CCHP’s Call Records, you can see these requests and the cost of each one. Hermes Agent’s auxiliary tasks, such as title generation and context compression, also use this model by default, so Call Records may show more requests than the messages you sent. To check the costs, see Provider groups and your final price.

Switch to another model#

  • If you use the setup wizard: Run hermes model again, select Custom endpoint (enter URL manually) again, and enter the same gateway URL and key. Then select the new model and enter its context length.
  • If you use the config file: Change default and context_length in config.yaml.

Frequently asked questions#

What if Hermes Agent says at startup that the context window is below 64,000?#

The message is Model ... has a context window of ... tokens, which is below the minimum 64,000 required by Hermes Agent. Hermes Agent can’t use a model with a context length below 64,000 tokens, so switch to a model with a larger context. If the model’s actual context length is 64,000 or more, the value in the config is too small. Correct context_length with the value you found in step 3, or run the setup wizard again.

What if requests return 401 invalid LLM token?#

The key that Hermes Agent sends is invalid. Check the following:

  • Whether you copied the whole key and its status is Active. If the key is disabled, expired, or revoked, see Create an LLM key.
  • If you use the config file, whether the value of key_env exactly matches the variable name in .env. If the names don’t match, Hermes Agent can’t read the key.

What if requests return 403 this client is not allowed for the organization or team?#

Your organization or team has turned on Client restriction, which allows calls only from specific clients. When Hermes Agent connects to a custom endpoint, its requests by default carry nothing that identifies Hermes Agent, so CCHP can’t recognize it as Hermes Agents. To fix this:

  1. Ask your organization admin or team admin to allow Hermes Agents in Client restriction. See Manage teams.

  2. Add the two lines below to the model section of config.yaml, keep the other settings as they are, and then restart Hermes Agent:

    config.yamlyaml
    model:
  default_headers:
    User-Agent: hermes-agent

What if a model appears in Models & Pricing but calls to it return 403 or 404?#

Usually, the model isn’t in the key’s Model whitelist, or the model ID has a spelling or letter-case error. To troubleshoot based on the returned message, see View available models.

Related pages#