Hermes Agent Setup with AnonRouter

Hermes AgentAutonomous-agent integration guide

Hermes Agent can use AnonRouter through a named OpenAI Chat Completions provider. Because an agent can read files, browse, call tools, and run for long periods, use a dedicated key, a tool-capable model, and explicit safety limits.

Recommended setup with hermes model

1. Run hermes model.
2. Select Custom endpoint.
3. Enter https://api.anonrouter.ai/v1 as the API base URL.
4. Enter a compatibility-enabled AnonRouter ar_... inference key.
5. Enter an exact model id from the AnonRouter catalog.
6. Enter the model's advertised context length.

Hermes saves the provider and model in ~/.hermes/config.yaml. The current Hermes provider guide recommends this custom-endpoint flow over relying only on OPENAI_BASE_URL.

Ready-made configuration

For an explicit named provider, add this to ~/.hermes/config.yaml:

providers:
  anonrouter:
    api: https://api.anonrouter.ai/v1
    key_env: ANONROUTER_API_KEY
    transport: chat_completions

model:
  provider: custom:anonrouter
  default: meta-llama/llama-3.3-70b

Store the key separately in ~/.hermes/.env:

ANONROUTER_API_KEY=ar_REPLACE_WITH_YOUR_API_KEY

Replace the example model after checking its current context window and tool capabilities. Inside a running Hermes session, switch among already-configured models with:

/model custom:anonrouter:meta-llama/llama-3.3-70b

The /model command does not add credentials for a new provider; configure the provider first with hermes model or config.yaml.

Base URL and configuration precedence

Hermes treats https://api.anonrouter.ai/v1 as the API root and calls:

GET  https://api.anonrouter.ai/v1/models
POST https://api.anonrouter.ai/v1/chat/completions

Do not put /chat/completions in the provider api value.

Hermes documents configuration precedence in this order:

1. Command-line arguments.
2. ~/.hermes/config.yaml.
3. ~/.hermes/.env.
4. Built-in defaults.

Keep non-secret provider configuration in YAML and the key in .env. The Hermes environment-variable reference still mentions OPENAI_BASE_URL, while the newer provider guide limits that variable to its openai-api provider. The named custom provider above avoids that ambiguity.

Choose an agent-capable model

Hermes documents a minimum context window of 64,000 tokens for its full agent and tool workflow. Its system prompt, tool schemas, and working state can make smaller contexts unreliable, and current releases may refuse them during startup.

Before selecting a route:

1. Open its live AnonRouter model page.
2. Confirm the context window is at least 64,000.
3. Confirm tool calling is supported.
4. Use the exact API model id, not the display name.
5. Set model.context_length if Hermes cannot detect the value correctly.

AnonRouter forwards tool definitions and tool-call responses; Hermes executes the tools locally or in its configured execution backend. Do not enable vision for this custom provider because AnonRouter's current compatibility contract requires string message content.

Guard unattended tool loops

Hermes' Docker guidance recommends hard stops for unattended gateways. Add:

tool_loop_guardrails:
  hard_stop_enabled: true
  hard_stop_after:
    exact_failure: 5
    idempotent_no_progress: 5

This stops repeated failing or non-progressing tool loops. It is not a monetary limit and does not replace the AnonRouter key cap.

For high-impact tools, also use the narrowest filesystem, credential, and network permissions that let the agent complete its job. Never give an unattended process a management key.

Docker example

Hermes' official image keeps mutable state under /opt/data. Initialize the host directory and run setup:

mkdir -p ~/.hermes

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

Place the named-provider configuration and .env file in the mounted Hermes directory. Start an interactive session with:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent

For a deliberately configured unattended gateway:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

Your container platform can inject ANONROUTER_API_KEY directly instead of keeping it in .env. Avoid placing a live key in shell history or a committed Compose file.

Current AnonRouter spending controls

AnonRouter supports an optional lifetime credit limit on each inference key. Before dispatch, the billing path accounts for successful usage and reserved or unsettled usage and rejects a request that would cross the cap. You can set the limit while creating the key and update it later.

That is different from a recurring budget:

AnonRouter has account-level daily budgets for some usage plans, but these are not user-configurable recurring limits for one Hermes key. Before broad promotion to fully unattended agents, per-key daily or monthly ceilings would provide a stronger operational boundary. This guide does not claim they already exist.

Privacy boundary

Hermes sends the prompt, tool schemas, selected file content, tool results, and other active context to its model provider. Inspect configured tools before using a mailbox, calendar, browser profile, credential store, or private files.

This setup uses AnonRouter compatibility mode. The broker temporarily sees the static key identity and plaintext request together. The content is not intentionally retained, but the request is not unlinkable like the native ticket flow.

Troubleshooting

401 or 403 response

Verify the full ar_... key and enable OpenAI-compatible access. Confirm that the key_env name exactly matches the variable in .env or Docker.

404 response

Use https://api.anonrouter.ai/v1 as the provider API root. Do not append the completion path.

Hermes rejects the model at startup

Check the live context window. Choose a route with at least 64,000 tokens or set the correct model.context_length when discovery is inaccurate.

Tools never execute

Confirm the selected AnonRouter route supports tools. AnonRouter returns tool calls, while Hermes is responsible for executing them and sending results back.

The key hits its cap

Review usage before raising the limit. A loop guard protects against repeated tool behavior; a credit cap protects billing. Diagnose the agent instead of automatically rotating to an unlimited fallback key.

Hermes Agent setup FAQ

Should I use OPENAI_BASE_URL?

Use hermes model or the named custom-provider YAML shown above. Current Hermes documentation is inconsistent about the generic scope of OPENAI_BASE_URL.

Can I use /auto?

Hermes needs a tool-capable model with a sufficiently large context window. For predictable agent behavior, pin a verified model rather than assuming every route eligible for /auto meets Hermes' requirements.

Are there per-key daily or monthly limits?

Not currently as a self-service feature. Use a dedicated key with a conservative total credit limit and enable Hermes tool-loop guardrails.

Sources and further reading

• Hermes Agent: AI providers and custom endpoints
• Hermes Agent: configuration and precedence
• Hermes Agent: environment variables
• Hermes Agent: Docker
• Hermes Agent: custom-provider reasoning issue
• AnonRouter compatibility mode

AnonRouter is an independent service and is not affiliated with Nous Research or Hermes Agent.