Hermes Agent Intro: Install, Chat & Custom OpenAI Endpoint

Hermes Agent is an open-source AI agent from NousResearch. It does not just answer single questions; it can also chain conversations, tools, memory, skills, and subtasks into longer workflows. For someone new to agents, it helps to think of it first as "a chat interface with a working directory and tools": start by having it complete a small, verifiable task, then gradually add long-term memory, scheduling, or messaging platforms.

This article was verified against the official documentation and official version page as of 2026-09-21, and uses Hermes Agent 0.21.3 as the reference version. So that the examples can be switched to a different endpoint, the steps below do not rely on the login flow of any particular model service. Instead, they use gemini-3.8-flash, which was found in the public model list.

1. What is Hermes Agent, and what problem does it solve?

A typical chat tool focuses on question and answer. An agent, by contrast, repeatedly reads files, uses terminal tools, organizes context during a single task, and then decides the next step. Hermes Agent is positioned as this kind of agent for long-running work: it has a CLI, TUI, Gateway, persistent sessions, memory, and skills, and can also hand larger tasks off to sub-agents.

This design suits three kinds of work:

• Development work that requires reading and writing project files, running commands, and reporting results.
• Research or organization work that needs context preserved across many turns.
• Workflows you want to use locally first, then connect to a messaging platform or a resident Gateway when needed.

It still needs a working model endpoint, though. A successful installation does not mean the model is connected; the minimum verification is to have it complete a short task whose result is easy to check.

2. Installation and a minimal working example

The official installer handles the dependencies Hermes needs, including Python, Node.js, ripgrep, and ffmpeg. Linux, macOS, WSL2, or Android/Termux can use the shell installer; native Windows uses the PowerShell installer:

# Linux / macOS / WSL2 / Android (Termux)
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# Windows PowerShell
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

After installation, reload your shell and start the TUI first:

source ~/.bashrc   # for zsh, use source ~/.zshrc
hermes --tui

If you only want to run the classic CLI, just run hermes. For the first prompt, you can use "Check the current directory, list the three most important files, and explain your reasoning." This is easier to confirm than a large task, because it verifies that the model, terminal tools, and reply flow all work. The official quickstart also recommends getting plain chat working first before adding Gateway, cron, skills, or delegation.

Hermes Agent currently requires the model to have at least 64K context. If a custom endpoint has less context, long conversations or tool loops may fail at startup or when compressing context.

3. Main configuration: pointing to a custom OpenAI-compatible endpoint

Hermes keeps non-secret settings in ~/.hermes/config.yaml and keys in ~/.hermes/.env. When connecting a custom endpoint, use a named provider and provider settings:

# ~/.hermes/.env
BAZAARLINK_API_KEY=<your key>

# ~/.hermes/config.yaml
model:
  default: gemini-3.8-flash
  provider: bazaarlink
  context_length: 1000000
providers:
  bazaarlink:
    api: https://api.bazaarlink.ai/v1
    key_env: BAZAARLINK_API_KEY
    default_model: gemini-3.8-flash
    transport: chat_completions

The gemini-3.8-flash here is the actual ID found in BazaarLink's public model list on 2026-09-21. Do not rewrite the display name into a different name yourself. transport: chat_completions uses the OpenAI-compatible Chat Completions interface.

Do not rename this key to OPENAI_API_KEY. Testing of Hermes Agent v0.21.3 on 2026-09-21 showed that it gates credentials by host for custom endpoints: OPENAI_API_KEY is not sent to hosts other than openai.com, and for custom endpoints it sends no-key-required, which results in HTTP 401 Invalid or disabled API key. Make sure key_env explicitly points to BAZAARLINK_API_KEY.

After making the change, you can check the configuration Hermes actually reads with the commands below, then open a new session:

hermes config get model --json
hermes status
hermes --tui

Other fields can stay at their defaults for now. Once the main model can complete a round of conversation, you can consider setting an auxiliary model for compression, vision, or delegation. Each of these fields also accepts provider, model, and base_url, so there is no need to change everything at the start.

Tested 2026-09-21 (minimal replay): Hermes's bazaarlink provider calls POST https://api.bazaarlink.ai/v1/chat/completions using the chat_completions transport and Authorization: Bearer. Plain text conversation returned 200 with finish_reason=stop and normal text. Requests with tools and tool_choice: auto also returned 200, with finish_reason=tool_calls, returning get_weather and {"city":"Taipei"}. This confirms the standard finish reason for tool calls.

stream: true returned 200, with 5 SSE chunks in total, ending with [DONE]. Adding the standard top-level reasoning_effort: "low" returned 200, but this response only contained role and content, with no structured reasoning field; so it can only be said that the request field was accepted, not that reasoning output has been fully interoperable. Image input with a image_url data URI also returned 200, and the model did read the image and answered with its color; this image input shape was verified on 2026-09-21.

GET https://api.bazaarlink.ai/v1/models returned 200, and the list includes gemini-3.8-flash. Generation requests with a fixed default do not need to rely on the list to carry this known model ID; however, Hermes's model picker, capability discovery, or /model custom without a model name may still query the endpoint's /models, and the official settings provide discover_models to control this. Separately, calling /v1/messages with the Anthropic Messages shape and x-api-key returned 200, with type=message in the response; this is another path after explicitly switching api_mode, and tool and streaming interoperability in Anthropic format has not yet been verified.

4. Common problems

hermes not found

Reload your shell first; the official per-user installation usually puts the launcher at ~/.local/bin/hermes. If it still can't be found, check whether that directory is in PATH, and do not replace the launcher by running the Python file in the source directory directly.

401 / Invalid or disabled API key

If you get HTTP 401 or Invalid or disabled API key, first confirm that ~/.hermes/.env uses BAZAARLINK_API_KEY=<your key>, and that key_env: BAZAARLINK_API_KEY is set in config.yaml; do not use OPENAI_API_KEY. This host-level credential gating behavior was confirmed by testing on Hermes Agent v0.21.3 (2026-09-21).

Model does not exist or responses fail quickly

First confirm that default exactly matches the id in the public model list, and also confirm that the current config.yaml is not being overridden by another profile or an environment variable.

Why didn't my chat change after I edited the settings?

Hermes keeps the original model for a session that is already running; configuration files usually take effect in the next session. To switch the current conversation, use /model inside the chat, or close and reopen the TUI.

The tool workflow is still unstable

First narrow the task and confirm the model can respond to tool calls normally, then check whether the context is at least 64K. If a custom endpoint has its own limits on tool fields, streaming, or reasoning, follow the endpoint's actual responses; do not guess from the model name alone.

The response is almost empty and finish_reason is length. What should I do?

This model thinks by default; if max_tokens is too small, reasoning tokens may use up the budget first, leaving little or no visible text. Raise max_tokens; in testing, output only became normal after raising it from 16 to 400.

5. Connecting to BazaarLink

If you want to connect this setup to BazaarLink, keep the provider: bazaarlink settings above, and fill in the key as BAZAARLINK_API_KEY=<your key>; confirm the model ID from the public model list first. The minimal request shapes for plain text, tool calls (finish_reason=tool_calls), a 5-chunk SSE stream, and image input (the model reads the image and answers with its color) were verified on 2026-09-21. Tool and streaming in Anthropic format, as well as the complete Hermes session, channel, and skill workflows, have not yet been verified. For more endpoint configuration, see the SDK documentation.

TWD billing · Taiwan invoices · leading AI models · OpenAI-compatible API