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

# Use LithosAI with Hermes Agent

> Connect Hermes Agent directly to LithosAI through the OpenAI Chat Completions API.

Hermes Agent connects directly to LithosAI through the OpenAI Chat Completions API. You do
not need a local proxy or protocol adapter.

<Note>
  This setup uses a named custom provider, so you can keep LithosAI alongside any other
  providers already configured in Hermes Agent.
</Note>

## Before you begin

Create a key on the [API Keys](https://console.lithosai.cloud/keys) page and confirm the
model ID you want to use on the [Models](https://console.lithosai.cloud/models) page.

<Steps>
  <Step title="Install Hermes Agent">
    Install Hermes Agent with any method on the
    [official installation page](https://hermes-agent.nousresearch.com/docs/getting-started/installation),
    then confirm the installation.

    ```bash theme={null}
    hermes doctor
    ```
  </Step>

  <Step title="Add your LithosAI key">
    Hermes Agent reads provider keys from `~/.hermes/.env`. Add your key there.

    ```bash ~/.hermes/.env theme={null}
    LITHOSAI_API_KEY=your-key
    ```

    Exporting `LITHOSAI_API_KEY` in the shell that starts Hermes Agent also works.
  </Step>

  <Step title="Add LithosAI as a custom provider">
    LithosAI is a
    [named custom provider](https://hermes-agent.nousresearch.com/docs/integrations/providers#named-custom-providers).
    Merge the following into `~/.hermes/config.yaml`, or open the file with `hermes config edit`.

    ```yaml ~/.hermes/config.yaml theme={null}
    providers:
      lithosai:
        api: https://api.lithosai.cloud/v1
        key_env: LITHOSAI_API_KEY
        transport: chat_completions
        default_model: moonshotai/Kimi-K3

    model:
      default: moonshotai/Kimi-K3
      provider: custom:lithosai
    ```

    `key_env` names the environment variable that holds the key, so the credential never
    enters the configuration file. Replace the model ID if you selected a different model in
    the LithosAI console.

    <Tip>
      Hermes Agent does not read the context window from LithosAI. If the context meter or
      compaction looks wrong, add `context_length` to the `lithosai` entry with the value from
      the [Models](https://console.lithosai.cloud/models) page.
    </Tip>
  </Step>

  <Step title="Start a session">
    Start Hermes Agent from the project you want it to inspect. The session opens on LithosAI
    because `model.provider` is `custom:lithosai`.

    ```bash theme={null}
    hermes
    ```

    <Note>
      Auxiliary tasks such as vision, web summarization, and session titles use the main chat
      model by default, so they run on LithosAI too.
    </Note>
  </Step>
</Steps>

## Verify the connection

From a project that contains a `README.md`, ask Hermes Agent:

```text theme={null}
Read README.md and reply with only its first Markdown heading.
```

Hermes Agent should read the local file and return its heading. This verifies both the model
response and a basic local tool call.

## Troubleshooting

| Symptom                                        | Cause                                                                                                            |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `Unknown provider` or LithosAI does not appear | `model.provider` must be `custom:lithosai`, and `providers.lithosai` must be present in `~/.hermes/config.yaml`. |
| Authentication fails                           | `LITHOSAI_API_KEY` is not in `~/.hermes/.env` or the shell that started Hermes Agent.                            |
| Context usage or compaction is inaccurate      | Add `context_length` to the `lithosai` provider entry.                                                           |

Issues common to every agent are listed under [Common issues](/coding-agents#common-issues).

## Resources

* [Hermes Agent provider documentation](https://hermes-agent.nousresearch.com/docs/integrations/providers)
* [Hermes Agent installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation)
* [LithosAI models](https://console.lithosai.cloud/models)