> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes Agent

> Connect Hermes Agent to TokenLab

Use TokenLab as a named model provider in Hermes while keeping your existing accounts and tool permissions.

## Let my agent set this up

Copy this task to an agent already running on your computer:

```text theme={null}
Read this guide and help me connect Hermes to TokenLab:
https://docs.tokenlab.sh/integrations/hermes-agent
Check my installed version and active configuration first.
Preserve existing accounts, providers, permissions and other settings.
Back up local files and show proposed changes.
Have me enter any API key locally; never ask for, print or paste it in chat.
Check configuration loading first.
Explain any paid request test separately before running it.
```

## Install or check Hermes

Follow the [official installation guide](https://hermes-agent.nousresearch.com/docs/getting-started/installation). It offers desktop installers for Apple Silicon macOS and Windows, and a CLI path for Linux and native Windows. Check the requirements for your system; skip installation if Hermes is already installed.

## Optional: reversible setup

Use the Hermes helper included in TokenLab Skills **0.1.3** for official Hermes **0.21.3**. It previews and backs up the change, adds only a named provider, and preserves YAML comments, accounts, the default model and permissions. Read the [setup reference](https://github.com/hedging8563/tokenlab-skills/blob/900de0c4e296c0d2ed00b5d842815ed89c403503/skills/tokenlab-api-integration/references/hermes_setup.md) first.

Set `SKILL_DIR` to the installed `tokenlab-api-integration` folder and `HERMES_PYTHON` to the Python in the Hermes installation shown by `hermes --version`: `venv/bin/python` on macOS/Linux or `venv\Scripts\python.exe` on Windows. PowerShell uses `$SkillDir` and `$HermesPython`. Use that existing environment; the helper does not install global Python packages.

```bash theme={null}
"$HERMES_PYTHON" "$SKILL_DIR/scripts/configure_hermes.py" --model gpt-5.6-luna
"$HERMES_PYTHON" "$SKILL_DIR/scripts/configure_hermes.py" --model gpt-5.6-luna --apply
```

```powershell theme={null}
& $HermesPython "$SkillDir/scripts/configure_hermes.py" --model gpt-5.6-luna
& $HermesPython "$SkillDir/scripts/configure_hermes.py" --model gpt-5.6-luna --apply
```

After applying, skip the manual merge below. Follow the helper’s printed home and loading commands; it detects `active_profile`. Configuration inspection does not validate the key. Preview restoration with `--restore`, then add `--apply` to restore the original bytes. Conflicts, later edits, managed settings and WSL stop automatic setup; retain those settings and use the manual route.

## Configure a named provider

Find the active Hermes directory: `HERMES_HOME` when set, otherwise `~/.hermes` (Windows: `%LOCALAPPDATA%\hermes`). Back up `config.yaml`, then merge the following entries without replacing other settings. The example uses Chat Completions; choose a current model that supports this format and tool calling.

Back up the active configuration. Add only the TokenLab entry and preserve existing providers, accounts, default-model selection and permissions. If the name is already used, choose another name and update the commands. To undo setup, remove only your added entry or restore its previous backup.

```yaml theme={null}
providers:
  tokenlab:
    api: https://api.tokenlab.sh/v1
    key_env: TOKENLAB_API_KEY
    transport: chat_completions
    default_model: gpt-5.6-luna
```

Create a key in [API keys](https://tokenlab.sh/dashboard/api?tab=keys). Enter it locally as `TOKENLAB_API_KEY` in the Hermes directory’s `.env` or in the environment of the process that starts Hermes. Never paste the key into a conversation or put it in the provider YAML.

## Check configuration, then make a request

Check the added provider with `hermes config get providers.tokenlab.api`; it should show `https://api.tokenlab.sh/v1`. Keep the existing `model` section unchanged. Start a new session with the explicit provider and model below; launch normally without these flags to use your previous default. Configuration inspection does not validate the key.

```bash theme={null}
hermes chat --provider custom:tokenlab --model gpt-5.6-luna
```

When ready to spend TokenLab balance, send a short text request. Check the response and its matching record in [Requests](https://tokenlab.sh/dashboard/runs?section=requests). Only then try a read-only tool task. Auxiliary models and optional tools can have separate providers or keys.

## Restore or troubleshoot

If the provider is unknown, check the installed version and the [current provider format](https://hermes-agent.nousresearch.com/docs/integrations/providers). For authentication errors, check the local environment and key status without printing the key. To undo setup, restore the previous model selection and remove only the TokenLab entries you added.

MCP and Skills are separate extensions: use the [MCP guide](/integrations/tokenlab-mcp-server) for API tools or the [Skill guide](/integrations/coding-agent-skill) for integration guidance. Neither is required to select this provider.