Hermes Agent

Hermes Agent (opens in a new tab) is an open-source AI agent runtime by Nous Research. Connect Hermes to Xilos by setting the provider base URL and API key in your Hermes profile configuration. Once connected, every LLM call flows through the Xilos gateway for routing, guardrails, caching, and cost control.

Prerequisites

A Xilos account with an active organization.
An API key from Settings in the Xilos dashboard, or a Virtual Key with scoped limits.
Hermes Agent installed and configured (run hermes setup if you have not already).
The base URL: https://api.xilos.ai/api/v1.

Configuration

Hermes reads provider settings from ~/.hermes/config.yaml (or the profile-specific YAML under ~/.hermes/profiles/<name>/). You set the base URL, API key, and model, then export the key as an environment variable so Hermes doctor and tool checks recognize it.

Set the model provider and base URL

hermes config set model.default xilos
hermes config set model.provider auto
hermes config set model.base_url https://api.xilos.ai/api/v1
hermes config set model.api_key $XILOS_API_KEY

Export your Xilos API key as an environment variable

export XILOS_API_KEY="your-xilos-api-key"

Add this line to your shell profile (~/.bashrc or ~/.zshrc) so it persists across sessions.

Warning: You must also write the key to the Hermes .env file. Some tool checks read from .env, not config.yaml. Run the command below to copy the key into the active profile's environment file:
echo "XILOS_API_KEY=$XILOS_API_KEY" >> $(hermes config env-path)

Verify the configuration

hermes doctor

hermes doctor checks that the model, provider, and API key are valid and that required dependencies are present.

Start a session

hermes

Any command that triggers an LLM call now routes through Xilos.

Info: When model.default is set to xilos, the Xilos routing engine selects the underlying LLM for each query. To bypass routing and target a specific model, set model.default to a concrete model name (for example, claude-sonnet-4).

Verify the Connection

Send a test message and confirm it appears in the Xilos dashboard:

hermes chat -q "Hello, Xilos!"

Open your Xilos dashboard.
Navigate to Query Log.
Confirm the query appears with the routing decision, governance actions, and cost breakdown.

Troubleshooting

Problem	Cause	Fix
`Unknown provider 'openai'`	You set `model.provider: openai` for a custom endpoint.	Use `model.provider: auto` instead. Xilos is OpenAI-compatible, but Hermes resolves the provider through `auto`.
`hermes doctor` reports a missing API key	The key is in `config.yaml` but not in `.env`.	Write the key to the profile `.env` file with the command in step 2 above.
401 Unauthorized	The API key is invalid or expired.	Regenerate the key in the Xilos dashboard under Settings and update both `config.yaml` and `.env`.
Requests ignore routing rules	`model.default` is set to a concrete model name.	Set `model.default` to `xilos` so the Xilos routing engine selects the model.
Auxiliary tasks (vision, compression) fail	Hermes cannot find a backend for auxiliary models.	Set `OPENROUTER_API_KEY` or configure each auxiliary task's provider explicitly with `hermes config set auxiliary.<task>.provider`.

Warning: security.redact_secrets (enabled by default) redacts strings that look like API keys from tool output. If Hermes is working with your own tokens and the redaction interferes, disable it with hermes config set security.redact_secrets false, then start a new session. The setting is read once at startup and cannot be toggled mid-session.

Next Steps

Create a Routing Rule — Direct specific query types to the best model.
Create a Restriction Rule — Block, mask, or flag sensitive content.
Enable Context Compression — Reduce token costs by 50–90%.
Manage Virtual Keys — Scope API keys with budget and rate limits.

Integrations Overview OpenClaw