> For the complete documentation index, see [llms.txt](https://thegrid.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://thegrid.ai/docs/integrations-and-best-practices/integrations/hermes-agent.md).

# Hermes Agent Integration with The Grid | Provider Setup

Use The Grid as the AI model behind Hermes Agent. Copy and paste a few commands into your terminal. No coding required.

Use The Grid as the AI model behind Hermes Agent. Setup takes about 5 minutes. You'll copy and paste a few commands into your terminal. No coding required.

## Before you start

You need three things:

1. **Hermes Agent installed.** To check, open your terminal, type `hermes --version`, and press Enter. If you see a version number, you're ready. If not, follow the [Hermes install guide](https://github.com/NousResearch/hermes-agent#installation).
2. **A Grid account with credits** at [app.thegrid.ai](https://app.thegrid.ai).
3. **A Grid consumption key.** In the Grid app, go to Settings → API Keys → Create Consumption Key, then copy the key.

{% hint style="info" %}
Where's my terminal? On Mac, open the Terminal app. On Windows, open PowerShell. If Hermes runs on a server, connect to that server and use its terminal.
{% endhint %}

## Setup

{% stepper %}
{% step %}

### Save your Grid key

Copy this command. Replace `PASTE_YOUR_KEY_HERE` with your key, then press Enter.

```bash
hermes config set THEGRID_API_KEY PASTE_YOUR_KEY_HERE
```

Hermes stores the key privately on your computer. You only do this once.
{% endstep %}

{% step %}

### Connect Hermes to The Grid

Copy this whole block, paste it into your terminal, and press Enter. You don't need to change anything.

```bash
hermes config set model.provider custom
hermes config set model.base_url https://messages-beta.api.thegrid.ai
hermes config set model.api_mode anthropic_messages
hermes config set model.api_key '${THEGRID_API_KEY}'
hermes config set model.default agent-prime
hermes config set model.context_length 196608
```

This tells Hermes to send requests to The Grid using the key you saved in step 1.
{% endstep %}

{% step %}

### Start Hermes and test it

```bash
hermes chat
```

Type `Say hello from The Grid` and press Enter. If Hermes replies, you're all set.
{% endstep %}
{% endstepper %}

## Choose a model

Hermes starts with `agent-prime`. It's the right choice for most people.

| Model            | Best for                                                                                                    | Context window |
| ---------------- | ----------------------------------------------------------------------------------------------------------- | -------------- |
| `agent-standard` | Fast, simple, repetitive tasks. Quick tool calls, routing, and running many agents at once.                 | 128K tokens    |
| `agent-prime`    | Everyday agent work. Multi-step tasks with roughly 5 to 20 tool calls. Recommended default.                 | 196K tokens    |
| `agent-max`      | Long, unattended work measured in hours. Deep research and chains of 50+ steps where accuracy matters most. | 1M tokens      |

To make a different model your default, run the matching lines.

For `agent-standard`:

```bash
hermes config set model.default agent-standard
hermes config set model.context_length 128000
hermes config set model.max_tokens 65536
```

For `agent-prime`:

```bash
hermes config set model.default agent-prime
hermes config set model.context_length 196608
hermes config set model.max_tokens 131072
```

For `agent-max`:

```bash
hermes config set model.default agent-max
hermes config set model.context_length 1000000
hermes config set model.max_tokens 128000
```

To learn more about each tier, see [Current instruments](/docs/instrument-specifications/current-instruments.md).

<details>

<summary>Optional: switch between The Grid and other providers</summary>

Use this if you want to keep your current provider and switch to The Grid when you choose. Complete step 1 above first, and skip step 2.

Run this command to open your settings file:

```bash
hermes config edit
```

Go to the end of the file and paste this block:

```yaml
custom_providers:
  - name: thegrid
    base_url: https://messages-beta.api.thegrid.ai
    key_env: THEGRID_API_KEY
    api_mode: anthropic_messages
    models:
      agent-prime:
        context_length: 196608
      agent-max:
        context_length: 1000000
```

If your file already has a line that says `custom_providers:`, don't paste that line again. Paste only the lines from `- name: thegrid` down, directly below your existing providers.

Save and close the file. Then, in Hermes chat, type either of these to switch:

```
/model agent-prime --provider custom:thegrid
/model agent-max --provider custom:thegrid
```

{% hint style="info" %}
`agent-standard` isn't available in this setup yet. Hermes asks it for longer replies than it allows. To use `agent-standard`, follow the main setup above instead.
{% endhint %}

{% hint style="info" %}
How to save and close depends on which editor opened:

* **Notepad** (usual on Windows): press Ctrl+S, then close the window.
* **nano** (usual on Mac and Linux, with shortcuts listed at the bottom): press Ctrl+O, then Enter to save. Press Ctrl+X to exit.
* **vim** (a plain screen with no menus): press Esc, type `:wq`, and press Enter.
  {% endhint %}

</details>

## Troubleshooting

Start with `hermes doctor`. It checks your setup and points to what's wrong. It may say "No API key found". You can ignore that if Hermes replies in step 3.

{% hint style="warning" %}
**"command not found: hermes"** Hermes isn't installed, or your terminal needs a restart. Close the terminal, open a new one, and try again. If it still fails, reinstall Hermes.
{% endhint %}

{% hint style="warning" %}
**HTTP 401 Unauthorized** Hermes can't use your key. Make sure it's a consumption key from Settings → API Keys → Create Consumption Key. Run step 1 again with that key, then restart Hermes.
{% endhint %}

{% hint style="warning" %}
**HTTP 402 Payment Required** Your credits have run out. Top up at [app.thegrid.ai](https://app.thegrid.ai).
{% endhint %}

{% hint style="warning" %}
**Replies come from a different provider** Run step 2 again, then restart Hermes.
{% endhint %}

{% hint style="warning" %}
**Context length or max\_tokens error** The model name and its limits don't match. Run the lines for your model under Choose a model.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://thegrid.ai/docs/integrations-and-best-practices/integrations/hermes-agent.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.