How Environment Variables Control Provider Routing and Model Selection in Hermes Agent

Hermes Agent uses six environment variables—HERMES_INFERENCE_PROVIDER, HERMES_MODEL, LLM_MODEL, OPENAI_MODEL, OPENAI_BASE_URL, and OPENROUTER_BASE_URL—to override configuration settings and dynamically select which inference provider and model handle your requests.

When deploying the NousResearch/hermes-agent across different environments, you often need to switch inference providers or models without editing config.yaml. The codebase implements a clear hierarchy of environment variables that take precedence over file-based configuration, enabling dynamic routing decisions at runtime according to the implementation in hermes_cli/runtime_provider.py and gateway/run.py.

Provider Routing Environment Variables

The agent determines which inference backend to use by evaluating specific environment variables in hermes_cli/runtime_provider.py and gateway/run.py.

HERMES_INFERENCE_PROVIDER

The HERMES_INFERENCE_PROVIDER variable explicitly sets the provider name and overrides any configuration file settings. According to the source code in hermes_cli/runtime_provider.py, the function resolve_requested_provider reads this variable, converts it to lowercase, and returns it immediately if present.

# hermes_cli/runtime_provider.py

env_provider = os.getenv("HERMES_INFERENCE_PROVIDER", "").strip().lower()
if env_provider:
    return env_provider  # Returns explicit provider like "nous" or "openrouter"

If this variable is empty or unset, the system falls back to "auto", which triggers the provider routing logic defined in your config.yaml under the provider_routing block. The gateway loads this configuration in gateway/run.py::_load_provider_routing, though the routing rules themselves are file-based, not environment-controlled.

Base URL Overrides for Custom Endpoints

Two variables control endpoint resolution when using OpenAI-compatible or OpenRouter providers:

• OPENAI_BASE_URL: Forces the OpenAI client to use a custom endpoint instead of the default. This affects the runtime_provider._resolve_openrouter_runtime logic, where the code checks for this variable first.
• OPENROUTER_BASE_URL: Specifies the endpoint when the resolved provider is OpenRouter. The default value is defined as https://openrouter.ai/api/v1 in hermes_constants.py.

# hermes_cli/runtime_provider.py excerpt

env_openai_base_url = os.getenv("OPENAI_BASE_URL", "").strip()
base_url = (
    explicit_base_url or
    env_openai_base_url or
    os.getenv("OPENROUTER_BASE_URL", OPENROUTER_BASE_URL)
)

Model Selection Environment Variables

While provider routing determines where requests go, three environment variables control which specific model processes the prompt.

HERMES_MODEL

The primary override is HERMES_MODEL. When set, it takes precedence over any model defined in config.yaml. The resolution chain appears in multiple files including gateway/run.py, cli.py, cron/scheduler.py, and agent/context_compressor.py.

# gateway/run.py excerpt

current = os.getenv("HERMES_MODEL") or os.getenv("LLM_MODEL") or "anthropic/claude-opus-4.6"

The default fallback when no environment variables are set is "anthropic/claude-opus-4.6", as specified in the resolution logic across the CLI and gateway components.

Legacy and Auxiliary Fallbacks

For backward compatibility and specific use cases, the codebase checks additional variables:

• LLM_MODEL: Consulted immediately after HERMES_MODEL if the primary variable is unset.
• OPENAI_MODEL: Used when pointing the CLI at custom OpenAI endpoints, checked after LLM_MODEL in the main resolution chain. Additionally, agent/auxiliary_client.py uses this variable to select auxiliary models for vision and web extraction tasks, with provider-specific defaults like gpt-4o-mini as fallbacks.

Practical Configuration Examples

The following examples demonstrate common routing and model selection scenarios using environment variables.

Force a Specific Provider

To route all requests through the Nous portal provider regardless of config.yaml settings:

export HERMES_INFERENCE_PROVIDER=nous
hermes chat -q "Summarize the latest news"

The resolve_requested_provider function in hermes_cli/runtime_provider.py captures this value and returns "nous" directly.

Override the Default Model

To use Claude Opus 4.6 explicitly:

export HERMES_MODEL=anthropic/claude-opus-4.6
hermes chat -q "Write a short poem"

Route to a Custom OpenAI Endpoint

When using a private OpenAI-compatible API:

export OPENAI_BASE_URL=https://my-private-openai.example.com/v1
export HERMES_INFERENCE_PROVIDER=openai
hermes chat -q "Explain quantum tunneling"

The runtime_provider._resolve_openrouter_runtime function evaluates OPENAI_BASE_URL before falling back to OpenRouter defaults.

Combine Provider and Model Selection

For OpenRouter with a specific open-source model:

export HERMES_INFERENCE_PROVIDER=openrouter
export HERMES_MODEL=mistralai/mistral-7b-instruct
hermes chat -q "Generate a bash script to backup ~/Documents"

The CLI resolves the provider first, then the model, passing both values to the AIAgent constructor as implemented in the gateway and CLI entry points.

Summary

• HERMES_INFERENCE_PROVIDER overrides the provider selection in hermes_cli/runtime_provider.py, accepting values like nous, openai, openrouter, or auto.
• HERMES_MODEL takes precedence over all other model configuration, with LLM_MODEL and OPENAI_MODEL serving as legacy fallbacks.
• OPENAI_BASE_URL and OPENROUTER_BASE_URL control endpoint resolution for custom or private inference servers.
• The resolution logic is centralized in hermes_cli/runtime_provider.py for providers and distributed across gateway/run.py, cli.py, cron/scheduler.py, and agent/auxiliary_client.py for model selection.

Frequently Asked Questions

What happens if I set both HERMES_MODEL and LLM_MODEL?

The system checks HERMES_MODEL first. Only if that variable is empty or unset does the code fall back to LLM_MODEL. This precedence chain is implemented consistently across gateway/run.py, cli.py, and cron/scheduler.py to ensure predictable behavior.

Can I use environment variables to configure provider routing rules?

No. While HERMES_INFERENCE_PROVIDER can be set to "auto" to enable automatic routing, the actual routing rules and priority logic are defined in the provider_routing block of config.yaml, loaded by gateway/run.py::_load_provider_routing. Environment variables control the final selection but not the routing algorithm itself.

How does Hermes Agent handle custom OpenAI-compatible endpoints?

Set OPENAI_BASE_URL to your custom endpoint URL and HERMES_INFERENCE_PROVIDER to openai. The runtime_provider.py module checks this base URL variable before defaulting to standard OpenAI or OpenRouter endpoints, allowing integration with private or self-hosted inference servers.

Which file contains the default model constant?

The fallback default model "anthropic/claude-opus-4.6" is hardcoded in the resolution logic found in gateway/run.py and cli.py, while auxiliary model defaults for vision tasks are managed in agent/auxiliary_client.py. The hermes_constants.py file contains the default OPENROUTER_BASE_URL constant.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}