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

> Discover how environment variables like HERMES_INFERENCE_PROVIDER and HERMES_MODEL control provider routing and model selection in Hermes Agent for dynamic inference.

- Repository: [Nous Research/hermes-agent](https://github.com/NousResearch/hermes-agent)
- Tags: how-to-guide
- Published: 2026-03-09

---

**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`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/hermes_cli/runtime_provider.py) and [`gateway/run.py`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/hermes_cli/runtime_provider.py) and [`gateway/run.py`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/hermes_cli/runtime_provider.py), the function `resolve_requested_provider` reads this variable, converts it to lowercase, and returns it immediately if present.

```python

# 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`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/hermes_constants.py).

```python

# 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`](https://github.com/NousResearch/hermes-agent/blob/main/config.yaml). The resolution chain appears in multiple files including [`gateway/run.py`](https://github.com/NousResearch/hermes-agent/blob/main/gateway/run.py), [`cli.py`](https://github.com/NousResearch/hermes-agent/blob/main/cli.py), [`cron/scheduler.py`](https://github.com/NousResearch/hermes-agent/blob/main/cron/scheduler.py), and [`agent/context_compressor.py`](https://github.com/NousResearch/hermes-agent/blob/main/agent/context_compressor.py).

```python

# 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`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/config.yaml) settings:

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

```

The `resolve_requested_provider` function in [`hermes_cli/runtime_provider.py`](https://github.com/NousResearch/hermes-agent/blob/main/hermes_cli/runtime_provider.py) captures this value and returns `"nous"` directly.

### Override the Default Model

To use Claude Opus 4.6 explicitly:

```bash
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:

```bash
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:

```bash
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`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/hermes_cli/runtime_provider.py) for providers and distributed across [`gateway/run.py`](https://github.com/NousResearch/hermes-agent/blob/main/gateway/run.py), [`cli.py`](https://github.com/NousResearch/hermes-agent/blob/main/cli.py), [`cron/scheduler.py`](https://github.com/NousResearch/hermes-agent/blob/main/cron/scheduler.py), and [`agent/auxiliary_client.py`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/gateway/run.py), [`cli.py`](https://github.com/NousResearch/hermes-agent/blob/main/cli.py), and [`cron/scheduler.py`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/gateway/run.py) and [`cli.py`](https://github.com/NousResearch/hermes-agent/blob/main/cli.py), while auxiliary model defaults for vision tasks are managed in [`agent/auxiliary_client.py`](https://github.com/NousResearch/hermes-agent/blob/main/agent/auxiliary_client.py). The [`hermes_constants.py`](https://github.com/NousResearch/hermes-agent/blob/main/hermes_constants.py) file contains the default `OPENROUTER_BASE_URL` constant.