---
title: "Connect Hermes Agent to XiuRouter"
description: "Use the Hermes model wizard to add a custom endpoint and verify context, requests, and read-only tools."
image: "https://docs.xiu.ai/og.png"
---

> XiuAI documentation index
> Full documentation index: https://docs.xiu.ai/en/llms.txt
> Check the index for current pages before reading.

# Connect Hermes Agent to XiuRouter

For both first setup and an existing installation, run `hermes model` outside the Hermes conversation. The in-session `/model` command switches configured providers; it cannot add a new connection.

## Choose a setup method

- First setup: run the model wizard and add a XiuRouter Custom endpoint.
- Existing setup: retain your original provider, add XiuRouter, and switch in a new session.
- Chat-assisted setup: unavailable; exit the conversation and run the wizard.

## Before you start

- `hermes --version` returns a version.
- You have a dedicated XiuRouter key for Hermes.
- You are ready to select a model from the endpoint's model list.

Hermes agent tools require at least 64,000 tokens of context. Use the context supported by the actual model and source rather than guessing from its name.

## Add a Custom endpoint

Outside the Hermes session, run:

```bash
hermes model
```

Complete the wizard:

```text
Provider: Custom endpoint (self-hosted / VLLM / etc.)
Base URL: https://router-api.xiu.ai/v1
API Key: Your XiuRouter API key
Model: Select from the endpoint /v1/models list
API mode: Chat Completions
Context length: Try automatic detection; if it fails, enter the supported value
```

Hermes uses the endpoint's `/models` response for model and context resolution. Do not preselect the model on the XiuRouter site or put the key in project files, shared scripts, or screenshots.

## Verify

1. Start a new Hermes session and confirm the provider and model.
2. Send a short text request.
3. Ask Hermes to read the current directory and report its path without changing files.
4. Verify the key, model, `/v1/chat/completions`, and successful status in XiuRouter's request inspection view.

A text reply proves basic Chat Completions only. Terminal, file, and other tools need valid tool calls from the model. Complete a read-only tool task before granting broader permissions.

## Troubleshoot

| Symptom | Next step |
| --- | --- |
| Model discovery returns `401` | Run `hermes model` again and check the saved key |
| Hermes refuses to start the agent | Verify that the configured context is at least 64,000 tokens |
| Requests use `/v1/responses` | Change the Custom endpoint API mode back to Chat Completions |
| Text works but tools do not run | Try a model with verified tools and check its actual context |
| Long tasks stop | Use `router-api.xiu.ai`, not the console domain |

## Roll back

Run `hermes model`, restore the original provider and model, then verify a new session before revoking the XiuRouter key.

## Sources and review date

Reviewed on 2026-08-31. This translation preserves that date. Basic setup requires a complete reply and matching usage record; verify context and tools with the actual model.

Source: https://docs.xiu.ai/en/router/integrations/hermes/index.mdx