> For the complete documentation index, see [llms.txt](https://docs.avis.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.xyz/integrations/assistant/hermes-agent.md). # Hermes Agent This document explains how to integrate Hermes with the AVIS OpenAI-compatible API — both the **Hermes Agent CLI** and the **Hermes Desktop** app. ### What is Hermes Hermes is an open-source autonomous coding and task agent from Nous Research, available as: * **Hermes Agent (CLI)** — terminal-native, run via `hermes chat`, `hermes -z "..."`, or a TUI via `hermes --tui`. * **Hermes Desktop** — a native GUI app (macOS/Windows/Linux) that wraps the same Hermes Agent core: "same config, same API keys, same sessions, same skills, same memory." Both connect to any OpenAI-compatible model endpoint and drive tool-calling workflows (file edits, shell commands, etc.) against whichever model/provider is configured. AVIS is registered as a custom provider, configured as `provider: custom:avis` below — the same config works in both CLI and Desktop, since they read/write the same `~/.hermes/config.yaml`. The steps below (§1–5) set up AVIS once via the CLI; §6 covers using that same setup from Hermes Desktop. ### 1) Prerequisites * macOS or Linux shell * API key for AVIS Reference values used in this guide: * AVIS base URL: `https://api.avis.xyz/api/openai/v1` * AVIS API key: set via environment variable ### 2) Install Hermes Agent If Hermes is not installed yet: ```bash curl -fsSL https://get.hermes.nousresearch.com | bash ``` Verify installation: ```bash hermes --version ``` If `hermes` is not in `PATH`, run via full path: ```bash ~/.local/bin/hermes --version ``` ### 3) Set Environment Variables Set AVIS values in your current shell: ```bash export AVIS_BASE_URL="https://api.avis.xyz/api/openai/v1" export AVIS_API_KEY="" ``` Optional: persist in shell profile (`~/.zshrc` or `~/.bashrc`). ### 4) Configure Hermes Provider and Model Hermes config file: ``` ~/.hermes/config.yaml ``` Open it: ```bash open -a "Visual Studio Code" ~/.hermes/config.yaml ``` Add or update these blocks: ```yaml model: default: qwen3-7-plus provider: custom:avis providers: avis: name: Avis base_url: ${AVIS_BASE_URL} api_key: ${AVIS_API_KEY} discover_models: true model: qwen3-7-plus models: qwen3-7-plus: {} ``` Notes: * `provider: custom:avis` means Hermes will use provider key `avis` under `providers`. * Keep `model.default`, `providers.avis.model`, and `providers.avis.models.*` consistent. * If your AVIS server exposes a different model id, replace `qwen3-7-plus` with that value. #### Alternative: interactive setup Instead of hand-editing `config.yaml`, `hermes model` can walk through adding a custom endpoint interactively: ```bash hermes model # Select "Custom endpoint (self-hosted / VLLM / etc.)" # Enter: API base URL, API key, Model name ``` This writes the same `provider: custom:avis`-style block into `config.yaml`, so both approaches converge on the same file. #### Other optional provider keys Hermes' custom-provider schema supports a few more fields beyond what's in the block above — add them under `providers.avis` if needed: | Key | Purpose | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `context_length` | Total context window in tokens. Hermes requires **at least 64K** for agent use; set this explicitly if AVIS/the underlying model can't be auto-detected or defaults lower. | | `max_tokens` | Caps output tokens per response. | | `supports_vision` | Set `true` to enable native image routing if the AVIS model accepts image input. | | `headers` | Extra HTTP headers to send with each request. | | `extra_body` | Provider-specific fields merged into the request body. | | `key_env` | Name of an env var holding the API key (e.g. `key_env: AVIS_API_KEY`) — an alternative to inlining `api_key: ${AVIS_API_KEY}` if your Hermes version prefers indirection over shell-style expansion. | Auto-detection order for context length: config override → per-model provider setting → cached discovery → the server's `/v1/models` response → external registries → a hardcoded fallback. If AVIS's `/models` response doesn't advertise context size, set `context_length` explicitly to avoid Hermes silently under- or over-shooting it. ### 5) Run Hermes Chat Interactive chat mode: ```bash hermes chat ``` One-shot mode: ```bash hermes -z "hello from hermes" ``` If needed, run with explicit provider/model override: ```bash hermes --provider custom:avis -m qwen3-7-plus -z "ping" ``` Once `custom:avis` and another provider are both configured, switch between them mid-session without restarting: ``` /model custom:avis:qwen3-7-plus ``` Note the distinction: `hermes model` (outside a session) registers/edits providers in `config.yaml`; `/model` (inside a chat session) only switches between providers already configured there. To add a brand-new provider, exit the session, run `hermes model`, then start a new session. ### 6) Use AVIS in Hermes Desktop Hermes Desktop is a native GUI app that runs the same Hermes Agent core as the CLI and shares the same `~/.hermes/config.yaml` and credentials — there's no separate account or config store to sync. #### Install * Download the installer from the Hermes website, **or** * If the CLI is already installed (§2), just run: ```bash hermes desktop ``` #### If AVIS is already configured via the CLI (§1–4) Nothing else to do — Hermes Desktop reads the same `config.yaml`, so `custom:avis` will already appear as an available provider/model in the app's menus on first launch. #### If setting up AVIS for the first time in Desktop On first run, onboarding lets you pick **Choose provider later** to skip straight into the app, or configure a provider immediately. Either way, provider setup lives in the **Providers** settings pane — a dedicated screen for managing inference providers (accounts, API keys, custom endpoints). Add AVIS there using the same values as §1: * Base URL: `https://api.avis.xyz/api/openai/v1` * API key: your AVIS API key * Model: your AVIS model id (e.g. `qwen3-7-plus`) If the Providers pane doesn't expose a field you need (e.g. `context_length` or `key_env` from §4's optional-keys table), edit `~/.hermes/config.yaml` directly — Desktop picks up changes made outside the app since it's the same file. ### 7) Troubleshooting * `401 Unauthorized` * AVIS key is invalid or missing. * Re-check `AVIS_API_KEY` and Authorization behavior. * `404` or model not found * Model id in Hermes config does not exist on AVIS `/models`. * Align to a real model id returned by AVIS. * Connection refused / timeout * URL is wrong (`/api/openai/v1` must be included). * Network/firewall is blocking outbound access to `api.avis.xyz`. * `hermes: command not found` * Use `~/.local/bin/hermes`. * Or add it to `PATH`. * Agent behaves erratically, truncates context, or refuses long tool output * Hermes needs a minimum \~64K context window for agent use. * Set `providers.avis.context_length` explicitly (see §4) if AVIS/the underlying model isn't auto-detected at or above that. * Model outputs tool calls as plain text instead of executing them * The underlying model AVIS is proxying to may not have tool-calling enabled on its serving side (this is a known issue for self-hosted backends like vLLM/llama.cpp/SGLang, which need explicit tool-call-parser flags). * Confirm the AVIS backend/model advertises tool-calling support; this isn't something fixable from the Hermes config side. ### 8) Minimal End-to-End Checklist 1. `AVIS_BASE_URL` and `AVIS_API_KEY` are exported. 2. `~/.hermes/config.yaml` has `custom:avis` provider config. 3. `hermes chat` or `hermes -z "..."` returns model output. 4. (Desktop) `hermes desktop` launches and `custom:avis` shows up under Providers. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.avis.xyz/integrations/assistant/hermes-agent.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.