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

# Hermes Agent

> Connect AnyAPI as a custom provider in Hermes Agent for multi-model access

# Hermes Agent

[Hermes Agent](https://github.com/NousResearch/hermes-agent) is an open-source, terminal-native autonomous coding and task agent by Nous Research. It features persistent memory, agent-created skills, and a messaging gateway with 21 platform adapters (Telegram, Discord, Slack, Google Chat, WhatsApp, Signal, SMS, Email, and more).

<Info>
  AnyAPI is not a built-in provider in Hermes Agent. You configure it as a **named custom OpenAI-compatible provider** via the `custom_providers:` list.
</Info>

## Quick Start

<Steps>
  <Step title="Get your API key">
    Sign up at [anyapi.ai](https://anyapi.ai) and create an API key in the [dashboard](https://dash.anyapi.ai/?page=api-keys).
  </Step>

  <Step title="Store the key as a secret">
    Add the key to `~/.hermes/.env` (Hermes keeps secrets separate from settings):

    ```bash theme={"system"}
    echo 'ANYAPI_API_KEY=your-key-here' >> ~/.hermes/.env
    ```
  </Step>

  <Step title="Run the provider wizard">
    ```bash theme={"system"}
    hermes model
    ```

    When prompted:

    1. Select **Custom endpoint (self-hosted / VLLM / etc.)**
    2. Provider name: `anyapi`
    3. Base URL: `https://api.anyapi.ai/v1`
    4. API key env var: `ANYAPI_API_KEY`
    5. Default model: `openai/gpt-4o` (or any model from the [AnyAPI catalog](https://anyapi.ai/ai-models))
  </Step>

  <Step title="Start Hermes">
    ```bash theme={"system"}
    hermes chat
    ```

    Your agent now routes requests through AnyAPI.
  </Step>
</Steps>

## Manual Configuration

For full control, edit the config files directly instead of using `hermes model`.

### Set the API key

`~/.hermes/.env`:

```bash theme={"system"}
ANYAPI_API_KEY=your-key-here
```

### Configure provider and model

`~/.hermes/config.yaml`:

```yaml theme={"system"}
model:
  default: openai/gpt-4o
  provider: custom:anyapi
  base_url: https://api.anyapi.ai/v1

custom_providers:
  - name: anyapi
    base_url: https://api.anyapi.ai/v1
    key_env: ANYAPI_API_KEY
    api_mode: chat_completions
```

### Verify

```bash theme={"system"}
hermes config show
```

## Model Format

AnyAPI uses the `vendor/model` format. Always include the vendor prefix:

```yaml theme={"system"}
model:
  provider: custom:anyapi
  default: openai/gpt-4o          # correct
  # default: gpt-4               # wrong — missing vendor prefix
```

Browse all available models at [anyapi.ai/ai-models](https://anyapi.ai/ai-models) or query the API:

```bash theme={"system"}
curl -sS -H "Authorization: Bearer $ANYAPI_API_KEY" \
  https://api.anyapi.ai/v1/models | jq -r '.data[].id'
```

## Advanced Configuration

<AccordionGroup>
  <Accordion title="Context window">
    Set the context length for the default model:

    ```yaml theme={"system"}
    model:
      default: openai/gpt-4o
      context_length: 128000
    ```

    For per-model overrides:

    ```yaml theme={"system"}
    custom_providers:
      - name: anyapi
        base_url: https://api.anyapi.ai/v1
        key_env: ANYAPI_API_KEY
        models:
          openai/gpt-4o:
            context_length: 128000
          google/gemini-2.5-pro:
            context_length: 1000000
    ```
  </Accordion>

  <Accordion title="Auxiliary (side) models">
    Hermes runs side LLM tasks (vision, compression, title generation, etc.) and lets you override the model per task:

    ```yaml theme={"system"}
    auxiliary:
      vision:
        provider: custom:anyapi
        model: openai/gpt-4o
      compression:
        provider: custom:anyapi
        model: openai/gpt-4o-mini
      title_generation:
        provider: custom:anyapi
        model: openai/gpt-4o-mini
    ```

    Tasks not overridden inherit from the main `model:` block.
  </Accordion>

  <Accordion title="Fallback providers">
    A list of backups Hermes tries when the primary model fails:

    ```yaml theme={"system"}
    fallback_providers:
      - provider: custom:anyapi
        model: openai/gpt-4o
      - provider: custom:anyapi
        model: openai/gpt-4o-mini
    ```
  </Accordion>

  <Accordion title="Anthropic-style endpoint">
    AnyAPI also exposes Anthropic's `/v1/messages` format for Claude models:

    ```yaml theme={"system"}
    model:
      default: anthropic/claude-sonnet-4.6
      provider: custom:anyapi-anthropic

    custom_providers:
      - name: anyapi-anthropic
        base_url: https://api.anyapi.ai/v1
        key_env: ANYAPI_API_KEY
        api_mode: anthropic_messages
    ```
  </Accordion>
</AccordionGroup>

## Configuration Examples

<Tabs>
  <Tab title="GPT-4o">
    ```yaml theme={"system"}
    model:
      default: openai/gpt-4o
      provider: custom:anyapi
      base_url: https://api.anyapi.ai/v1

    custom_providers:
      - name: anyapi
        base_url: https://api.anyapi.ai/v1
        key_env: ANYAPI_API_KEY
    ```
  </Tab>

  <Tab title="Gemini 2.5 Pro">
    ```yaml theme={"system"}
    model:
      default: google/gemini-2.5-pro
      provider: custom:anyapi
      base_url: https://api.anyapi.ai/v1

    custom_providers:
      - name: anyapi
        base_url: https://api.anyapi.ai/v1
        key_env: ANYAPI_API_KEY
    ```
  </Tab>

  <Tab title="Multi-model with fallbacks">
    ```yaml theme={"system"}
    model:
      default: openai/gpt-4o
      provider: custom:anyapi
      base_url: https://api.anyapi.ai/v1

    custom_providers:
      - name: anyapi
        base_url: https://api.anyapi.ai/v1
        key_env: ANYAPI_API_KEY
        api_mode: chat_completions

    auxiliary:
      compression:
        provider: custom:anyapi
        model: openai/gpt-4o-mini
      title_generation:
        provider: custom:anyapi
        model: openai/gpt-4o-mini

    fallback_providers:
      - provider: custom:anyapi
        model: anthropic/claude-sonnet-4.6
      - provider: custom:anyapi
        model: openai/gpt-4o-mini
    ```
  </Tab>
</Tabs>

## Gateway Mode

When running Hermes as a messaging gateway (Telegram, Discord, Slack, etc.), the configuration is identical. Restart the service after changes:

```bash theme={"system"}
hermes gateway restart
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="No API key / provider not found">
    Hermes can't find your AnyAPI key.

    1. Verify the env file: `grep ANYAPI ~/.hermes/.env`
    2. Re-run the wizard: `hermes model` → Custom endpoint
    3. Confirm YAML uses `key_env: ANYAPI_API_KEY` (or the alias `api_key_env:`)
  </Accordion>

  <Accordion title="Authentication failed (HTTP 401)">
    Your key is invalid, revoked, or has no credits.

    1. Validate the key at [dash.anyapi.ai](https://dash.anyapi.ai)
    2. Check your balance/quota
    3. Reissue the key if needed
  </Accordion>

  <Accordion title="Model not found / Bad Request (HTTP 400)">
    The model ID is unknown or missing the vendor prefix.

    1. List the live catalog: `curl -H "Authorization: Bearer $ANYAPI_API_KEY" https://api.anyapi.ai/v1/models`
    2. Use `vendor/model` form (e.g. `openai/gpt-4o`, not bare `gpt-4o`)
  </Accordion>

  <Accordion title="Base URL errors">
    The endpoint must be exactly `https://api.anyapi.ai/v1` — no trailing slash, no `/chat/completions` suffix (Hermes appends that automatically).
  </Accordion>

  <Accordion title="Schema validation warnings">
    If Hermes warns about unknown YAML keys, check that you are using:

    * `custom_providers:` (plural list), not `custom_provider:`
    * `auxiliary.<task>.provider`, not `auxiliary_providers:`
    * `model.context_length`, not `context_limits:`
  </Accordion>

  <Accordion title="Rate limiting (HTTP 429)">
    Check usage at [dash.anyapi.ai](https://dash.anyapi.ai), upgrade your plan, or route side tasks to cheaper models via `auxiliary.*`.
  </Accordion>
</AccordionGroup>

## Best Practices

1. **Keep credentials in `.env`, never in `config.yaml`**
2. **Configure fallbacks** — AnyAPI gives you many providers behind one key, use them for resilience
3. **Route side tasks to small models** — use `auxiliary.*` with cheaper models like `openai/gpt-4o-mini`
4. **Always use `vendor/model` format** — bare model names will not resolve
5. **Monitor usage** at [dash.anyapi.ai](https://dash.anyapi.ai)

## Support

* **AnyAPI Dashboard**: [dash.anyapi.ai](https://dash.anyapi.ai)
* **AnyAPI Discord**: [Discord community](https://discord.gg/rJgyzGynHw)
* **AnyAPI Email**: [support@anyapi.ai](mailto:support@anyapi.ai)
* **Hermes Agent Issues**: [github.com/NousResearch/hermes-agent/issues](https://github.com/NousResearch/hermes-agent/issues)