<!-- Canonical URL: https://ask.atlascloud.ai/integrate-hermes-agent-atlascloud -->

# How Do You Integrate Hermes Agent with Atlas Cloud?

> Connect Hermes Agent to Atlas Cloud by storing the Atlas Cloud key in ~/.hermes/.env, selecting provider: custom, setting the base URL to https://api.atlascloud.ai/v1, and choosing a live model ID from /v1/models.

Hermes Agent can use [Atlas Cloud](https://www.atlascloud.ai/?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=integrate-hermes-agent-atlascloud) as a custom OpenAI-compatible inference provider. The integration needs three things: an Atlas Cloud API key, the base URL `https://api.atlascloud.ai/v1`, and a [model ID from Atlas Cloud's model list](https://www.atlascloud.ai/pricing/models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=integrate-hermes-agent-atlascloud&sort=new). Once those are in Hermes Agent's current `model:` configuration, the agent can run through Atlas Cloud without a provider-specific SDK.

> **Key takeaways**
>
> * Install Hermes Agent with the official installer, then keep the Atlas Cloud key in `~/.hermes/.env` rather than in source control.
> * Configure Hermes Agent with `provider: custom` and `base_url: https://api.atlascloud.ai/v1`.
> * Query `/v1/models` before choosing a model. Model names change faster than integration code, so the live response is safer than copying an old ID from a tutorial.
> * Run `hermes doctor` before starting a long-lived agent, then use `hermes` to test the first conversation.
> * Atlas Cloud's unified API makes it possible to change the language model later without rebuilding the Hermes integration.

## What are Hermes Agent and Atlas Cloud?

[Hermes Agent](https://github.com/NousResearch/hermes-agent) is an open-source, self-improving agent built by Nous Research. It includes a terminal interface, persistent memory, skills, scheduled automations, messaging gateways, and support for multiple inference providers. The current Hermes Agent documentation emphasizes that models can be changed without rewriting the agent.

[Atlas Cloud's main platform](https://www.atlascloud.ai/?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=integrate-hermes-agent-atlascloud) exposes hundreds of language, image, video, and audio models through a unified API. For Hermes Agent, the important part is its OpenAI-compatible inference surface: Hermes can treat Atlas Cloud as a custom provider and send normal chat-completion traffic to it.

This pairing is useful when you want Hermes Agent to remain independent of a single model vendor. The agent configuration stays stable, while the selected Atlas Cloud model can change as requirements, pricing, or availability change.

## Before you start

You need:

1. A Linux, macOS, WSL2, or supported Windows environment.
2. A working Hermes Agent installation.
3. An Atlas Cloud account and API key.
4. Enough Atlas Cloud balance or account access for the model you select.

Do not paste a real API key into a public repository, issue, screenshot, or shared configuration file. Hermes Agent supports a local `.env` file specifically so secrets can remain separate from ordinary configuration.

## Step 1: Install Hermes Agent

On Linux, macOS, or WSL2, use the installer published by Nous Research:

```bash
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
```

Reload your shell after installation:

```bash
source ~/.zshrc
```

If you use Bash, reload `~/.bashrc` instead. Then confirm that the CLI is available:

```bash
hermes --help
```

The official project also supports native Windows through its PowerShell installer. Follow the current [Hermes Agent installation documentation](https://hermes-agent.nousresearch.com/docs/) rather than translating the Unix command into PowerShell yourself.

## Step 2: Create an Atlas Cloud API key

Sign in to the Atlas Cloud console and create an API key for this Hermes Agent deployment. Use a dedicated key when your account controls allow it; separating agent traffic makes later rotation and usage review easier.

Store the key in Hermes Agent's local environment file:

```bash
printf '\nOPENAI_API_KEY=%s\n' 'replace-with-your-atlas-cloud-key' >> ~/.hermes/.env
```

Replace the placeholder locally. Do not include the real key in `config.yaml` if that file will be backed up, synchronized, or committed.

Why use `OPENAI_API_KEY`? Hermes Agent's current custom-provider path resolves that environment variable when an explicit OpenAI-compatible base URL is configured. Atlas Cloud uses bearer-token authentication on that compatible interface.

## Step 3: Get a live Atlas Cloud model ID

Do not guess the model ID. Check the [Atlas Cloud model list](https://www.atlascloud.ai/pricing/models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=integrate-hermes-agent-atlascloud&sort=new), then ask the API for the current catalog:

```bash
export ATLASCLOUD_API_KEY='replace-with-your-atlas-cloud-key'

curl https://api.atlascloud.ai/v1/models \
  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
```

Choose a text model that supports the behavior your Hermes deployment needs, especially tool use, reasoning, context length, and expected latency. Copy the exact `id` returned by the API.

For a persistent agent, start with a general-purpose tool-capable model rather than optimizing only for the cheapest token price. After the integration works, you can test lower-cost models for summarization or other routine tasks.

## Step 4: Point Hermes Agent at Atlas Cloud

Open `~/.hermes/config.yaml` and configure the current top-level `model:` section:

```yaml
model:
  default: "replace-with-a-live-atlas-cloud-model-id"
  provider: "custom"
  base_url: "https://api.atlascloud.ai/v1"
```

Keep the key in `~/.hermes/.env`; the YAML file only needs the provider, endpoint, and model ID.

This detail matters because older Hermes Agent examples may use an `inference:` block. The current official configuration sample uses `model:`. If your installed version behaves differently, run `hermes update` and check the configuration documentation shipped with that version before changing more settings.

## Step 5: Diagnose the configuration

Run Hermes Agent's built-in checks:

```bash
hermes doctor
```

Then start the agent:

```bash
hermes
```

Send a small test request that does not need external tools, such as:

```text
Reply with the model name you are using, then summarize what tools are available in this Hermes session.
```

A normal streamed response confirms that Hermes can authenticate, reach the Atlas Cloud endpoint, and call the configured model.

## Common integration problems

### Authentication errors

Check that `OPENAI_API_KEY` exists in `~/.hermes/.env`, contains the Atlas Cloud key without extra quotes or spaces, and is being loaded by the same Hermes installation you are running. Rotate the key if it has been exposed.

### Unknown model errors

Call `https://api.atlascloud.ai/v1/models` again and copy the exact live ID. Do not remove a provider prefix or shorten the identifier unless the API response itself uses the shorter form.

### Hermes calls the wrong provider

Confirm that the active configuration contains both:

```yaml
provider: "custom"
base_url: "https://api.atlascloud.ai/v1"
```

Selecting a built-in provider can route the request to that provider's own endpoint instead of Atlas Cloud.

### The configuration matches an old tutorial but fails

Hermes Agent is evolving quickly. Compare your file with the current [official configuration reference](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) and use `hermes config get` to inspect the active profile. In particular, verify whether your version expects the current `model:` structure.

## How to change models without rebuilding the integration

Once Atlas Cloud is configured as the custom provider, switching models only requires a new ID from the [live model catalog](https://www.atlascloud.ai/pricing/models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=integrate-hermes-agent-atlascloud&sort=new):

1. Query `/v1/models`.
2. Update `model.default` in `~/.hermes/config.yaml`.
3. Run `hermes doctor`.
4. Start a fresh test conversation.

The endpoint and credential handling remain the same. This is the practical value of a unified API for an agent: model evaluation becomes a configuration change instead of a new SDK integration.

## When this setup is a good fit

The Atlas Cloud integration is a strong fit when:

* You want Hermes Agent to access multiple model families through one account.
* You expect to benchmark or replace the main model over time.
* You want an OpenAI-compatible endpoint rather than provider-specific client code.
* Your future Hermes skills may need access to image or video models from the same platform.

A direct model-provider integration may be simpler if the agent will permanently use one provider and you do not need Atlas Cloud's broader model catalog. The right choice depends on whether flexibility and centralized access matter more than having the shortest possible single-provider setup.

## Final checklist

Before leaving Hermes Agent running unattended, verify all five items:

- The Atlas Cloud key is stored outside version control.
- `provider` is set to `custom`.
- `base_url` is exactly `https://api.atlascloud.ai/v1`.
- `model.default` matches an ID from the live models endpoint.
- `hermes doctor` and a simple conversation both succeed.

With those checks complete, Hermes Agent is integrated with Atlas Cloud. You can now evaluate different language models behind the same agent without changing its tools, memory, skills, or user interface.

## FAQ

### Does Hermes Agent have a built-in Atlas Cloud provider?

A dedicated Atlas Cloud provider is not required. Hermes Agent can connect through its custom OpenAI-compatible provider using the Atlas Cloud base URL and API key.

### What is the Atlas Cloud base URL for Hermes Agent?

Use https://api.atlascloud.ai/v1 as the OpenAI-compatible base URL.

### Where should I store the Atlas Cloud API key?

Store it in ~/.hermes/.env as OPENAI_API_KEY and keep the real key out of config files, screenshots, and version control.

### Which Atlas Cloud model should Hermes Agent use?

Query https://api.atlascloud.ai/v1/models and choose a current text model that meets your tool-use, reasoning, context, latency, and cost requirements.

### How can I verify the integration?

Run hermes doctor, start Hermes with the hermes command, and send a small test prompt. Authentication or unknown-model errors usually point to the API key, base URL, or model ID.