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

# Hermes

> Use RunInfra as a named custom provider in Hermes.

Use RunInfra as a named custom provider in Hermes.

Support level: `ready`. Connect supports automatic setup.

<Note>
  Connect writes the named provider in `config.yaml` and uses `.env` for literal keys. The recorded round trip used WSL. Native Windows paths still need confirmation.
</Note>

## Connect Hermes

Have Hermes installed, a workspace API key, and available RunInfra credits. Choose a catalog model with at least 64,000 context tokens. Connect requires that minimum for this setup.

```bash theme={"dark"}
npx @runinfra/connect hermes
```

The bare agent command is an alias for `on`. In an interactive terminal, Connect starts login if needed. Review and approve the proposed changes. Connect saves a snapshot, writes the provider and key settings, and makes a real Chat Completions request that uses credits.

To choose a model during setup:

```bash theme={"dark"}
npx @runinfra/connect hermes on --model deepseek-v4-flash
```

See [Connect](/docs/tools-sdks/connect) for status, diagnostics, and key replacement.

## What Connect writes

| Platform        | Connect's default configuration target | Literal-key target           |
| --------------- | -------------------------------------- | ---------------------------- |
| macOS and Linux | `~/.hermes/config.yaml`                | `~/.hermes/.env`             |
| Windows         | `%USERPROFILE%\.hermes\config.yaml`    | `%USERPROFILE%\.hermes\.env` |

When `HERMES_HOME` is set, Connect uses `config.yaml` and `.env` inside that directory. Confirm the active directory and profile. The native Windows targets above describe Connect's file choices, not a confirmed native Windows installation.

Connect writes these named-provider settings:

| Setting                             | Value                                       |
| ----------------------------------- | ------------------------------------------- |
| `providers.runinfra.api`            | `https://api.runinfra.ai/v1`                |
| `providers.runinfra.key_env`        | `RUNINFRA_API_KEY`                          |
| `providers.runinfra.transport`      | `chat_completions`                          |
| `providers.runinfra.default_model`  | The selected catalog model id               |
| `providers.runinfra.context_length` | The selected model's catalog context window |
| `model.default`                     | The selected catalog model id               |
| `model.provider`                    | `custom:runinfra`                           |

Connect removes `api_key` and `key_cmd` from the RunInfra provider settings. It also removes the selected model's `api_key`, `key_env`, `key_cmd`, and `base_url` fields so the named provider supplies them.

### Key placement

Literal mode adds the `RUNINFRA_API_KEY` assignment to `.env`. The YAML references that variable through `providers.runinfra.key_env`; it does not store the literal key there.

For helper mode:

```bash theme={"dark"}
npx @runinfra/connect hermes on --key-source helper
```

Helper mode uses the launch environment instead of writing a new literal assignment. Connect keeps an existing `.env` assignment when another provider still uses that variable. Review the warning and check helper credential precedence separately.

<Accordion title="Pass the helper key to the app">
  Export `RUNINFRA_API_KEY` with your RunInfra API key in the environment that launches the app. Restart GUI apps and background services with that environment.

  On Windows, set `RUNINFRA_API_KEY` in your user environment, then fully restart the app. GUI and Start menu launches do not receive a terminal-only `$env:RUNINFRA_API_KEY` value. This launch guidance does not confirm native Windows path behavior.
</Accordion>

## Verify

Hermes v0.21.1 on WSL completed a verified round trip on September 8, 2026, using the Connect-written named provider and `.env` key. The request returned `RUNINFRA_OK` and was confirmed in RunInfra usage.

Inspect the selected model and `custom:runinfra` provider:

```bash theme={"dark"}
hermes config get model
```

This checks selection, not a reply or its destination. In an authorized isolated environment, run the follow-up command. Connect prints it but does not execute it:

```bash theme={"dark"}
hermes chat -q "Reply exactly RUNINFRA_OK. Do not use tools." --oneshot -Q
```

The no-tools prompt is not a permission boundary. Confirm the reply and request destination separately.

## Restart

Restart Hermes after editing files. Run `hermes config get model` to inspect selection. This does not verify a reply or its destination.

## Known behaviours

Still check native Windows paths, `HERMES_HOME` and profiles, Hermes's minimum context size, helper credential precedence, and restoration after Hermes saves changes. Connect's 64,000-token minimum is a setup guard, not confirmation of every model's behavior in Hermes.

If Connect cannot safely read the YAML, environment assignments, or another provider's credential references, it refuses the changes. Review both files before retrying.

## Troubleshooting

| Symptom                                              | What to check                                                                                               |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| The model is refused for its context size            | Choose a model with at least 64,000 context tokens.                                                         |
| Hermes selects another provider                      | Check `model.default`, `model.provider`, the active profile, and `HERMES_HOME`.                             |
| A `.env` assignment remains after switching key mode | Another provider may still use it. Connect preserves shared assignments. Review the warning before editing. |
| Helper authentication fails                          | Check `RUNINFRA_API_KEY` in the actual launch environment and review credential precedence.                 |
| Connect refuses YAML or `.env` syntax                | Review the named files and credential references. Connect does not apply partial changes.                   |
| Normal `off` refuses changed bytes                   | Review Hermes's saved changes before choosing `off --force`.                                                |

## Revert

```bash theme={"dark"}
npx @runinfra/connect hermes off
```

In the recorded run, `off` restored `config.yaml` byte for byte and removed the added RunInfra key line from `.env`. With intact state and snapshots, `off` restores the original managed files from before the first `on` in the active connection. It removes files that did not exist then. Later `on` calls and key rotations keep that restore point.

If Hermes or another editor changed a managed file, Connect refuses to overwrite it. Back up and review the edits before choosing to discard them:

```bash theme={"dark"}
npx @runinfra/connect hermes off --force
```

Connect saves the current contents in a recovery snapshot and prints its id before restoring the origin. Keep the snapshots. If the origin snapshot is missing, cleanup does not guarantee original-byte restoration. See [Connect recovery](/docs/tools-sdks/connect#what-off-restores).

Restore manual environment and profile changes yourself. File restoration does not restore external credentials or other profiles.

## Related

<Columns cols={3}>
  <Card title="Connect" icon="plug" href="/docs/tools-sdks/connect">
    Set up, inspect, and restore your coding agent.
  </Card>

  <Card title="Chat completions" icon="braces" href="/docs/api-reference/chat-completions">
    Read the request contract.
  </Card>

  <Card title="Models" icon="list" href="/docs/api-reference/models">
    Find model ids and context windows.
  </Card>
</Columns>