Skip to main content

​
1. Overview

Hermes Agent is an open-source, self-hosted AI Agent from Nous Research, with terminal interaction, persistent memory, skills, and messaging integrations. Configure GravitexAI as a custom provider to use GPT, Claude, DeepSeek, and other models available to your account.

Persistent memory

Keep preferences and work context across sessions.

Reusable skills

Turn task experience into reusable Skills.

Multiple channels

Use the same Agent through the CLI or messaging gateway.

Multiple protocols

Select Responses, Anthropic Messages, or Chat Completions by model.
Updated against the official provider documentation reviewed on October 19, 2026. This page covers the CLI and configuration files. For GUI steps, see Hermes Agent Desktop App.

​
2. Environment

  • Linux, macOS, native Windows, or WSL2; see the official installation guide for current support.
  • The POSIX installer requires Git, curl, tar, and SHA-256 utilities; runtime dependencies are managed by the installer.
  • Android / Termux uses its separate installation guide, not the desktop/server script.

​
3. Prerequisites

Hermes requires at least 64,000 context tokens. Use the real limit of the model and channel; do not enter an inflated value to bypass this requirement.

​
4. Installation

Reopen your terminal, or reload your shell with source ~/.zshrc or source ~/.bashrc.
For an existing installation, run hermes update before configuring.

​
5. Configure GravitexAI

​
Step 1: Locate the active configuration

The default data directory is ~/.hermes/ on Linux/macOS and %LOCALAPPDATA%\hermes\ for the native Windows script installation. If you set HERMES_HOME or use another install method, use its actual directory. hermes config edit opens the active configuration.

​
Step 2: Save the API key

Replace the placeholder with your key:
This saves the key to the active data directory’s .env. The YAML below references it through key_env: GRAVITEX_API_KEY, so it need not be repeated inline.

​
Step 3: Add custom providers

Add or merge the following into config.yaml. If providers or model already exists, edit that block. Do not create duplicate top-level keys.
Model IDs are examples: replace them with models available to your account. Remove providers you do not need; if you remove the default one, update both model.provider and model.default.
The protocol must match the model. Claude’s native URL has neither /v1 nor /anthropic; do not put Claude in a Responses provider. The Hermes value for Responses is codex_responses.
New configurations use a providers mapping. Legacy custom_providers lists remain compatible and are migrated by the updater. Within a provider entry, use api for the endpoint (base_url is also accepted), default_model instead of model, and transport instead of api_mode. The main-model block still uses model.default.

​
Step 4: Explicitly select the default provider

Registering a provider does not automatically select it. If the main provider is still model.provider: auto, run:
For Claude as the default instead:
Check the original model block and clear stale base_url, api_mode, or api_key overrides pointing to another provider. Use the provider entry’s key_env for the key, save, and start a new session.

​
Interactive alternative

Run hermes model in a terminal, choose Custom endpoint, and supply the URL, key, model, and API mode from the table. Leave context length blank for detection; any explicit value must match the channel’s real window. hermes model adds/configures providers; /model inside a session switches already configured models. See Named Custom Providers.

​
6. Launch and verify

Send a short message first, check for authentication/model/protocol errors, then try a tool task. Switch configured providers and models inside the session with:
Success means the intended model is selected, messages receive replies, and a simple tool call works. hermes doctor checks configuration and dependencies; it does not replace a live API test.

​
7. Auxiliary models

Compression, vision, and title generation can use separate models. The default auto prefers the main model and is a good starting point. To select another configured provider, add:
Choose a model capable of the task; image analysis requires vision input. See Configuring Models.

​
8. Messaging platforms

After terminal verification succeeds, configure Telegram, Discord, Slack, or another platform:
run uses the foreground, useful for initial checks and WSL2. To install a background service on Linux/macOS:
Configure platform tokens and permissions through the wizard. See Messaging Gateway.

​
9. Common commands

For Skills, MCP, and execution backends, see Configuration. The terminal backend is set with terminal.backend.

​
10. Troubleshooting

Check that the active data directory’s .env contains a valid GRAVITEX_API_KEY and that the provider’s key_env matches exactly. Check key status and model permissions in GravitexAI.
GPT: codex_responses with https://api.gravitex.ai/v1. Claude: anthropic_messages with https://api.gravitex.ai. Chat Completions: chat_completions with https://api.gravitex.ai/v1. Do not append full request paths to the base URL.
Copy the exact model ID from the catalog. When changing protocols, switch both provider and model, not only the model name.
Confirm a real window of at least 64,000 tokens. If detection is wrong, set model.context_length or the provider’s per-model context_length to the actual channel limit. This is the context window, not the output-token cap.
Saving a key or providers entry alone does not select it. Replace auto with custom:gravitex-gpt or custom:gravitex-claude, set the matching model.default as in step 4, and start a new session.
Use hermes config edit to confirm the file, HERMES_HOME, and profile. Clear conflicting model.base_url or model.api_mode settings, select the provider with hermes model, and start a new session. Restart a running messaging gateway with hermes gateway restart.

​
11. Resources