How to Connect AIsa to Hermes Desktop

Hermes Desktop gives builders a desktop workspace for running and managing agent conversations. AIsa gives those agents a unified model gateway, so they can route model calls through one OpenAI-compatible API endpoint instead of wiring every provider separately.

In this guide, we will connect Hermes Desktop to AIsa, set AIsa as the model endpoint, choose a supported text model, and run a quick test from the desktop app.

What you are setting up

By the end of this guide, Hermes Desktop should be able to call AIsa through:

That endpoint is AIsa's OpenAI-compatible chat base URL. Once it is configured, Hermes can use AIsa as its model provider layer while you continue working from the Hermes Desktop interface.

Prerequisites

Before starting, make sure you have:

1. Hermes Desktop installed.
2. An AIsa account.
3. An AIsa API key.
4. A supported AIsa text model ID.
5. Access to a terminal, such as PowerShell on Windows or Terminal on macOS/Linux.

A model ID must be copied exactly from AIsa's supported model list or from the list Hermes shows during setup. For the main Hermes model, choose a text, reasoning, or coding model. Avoid image, video, embedding, Whisper, and TTS models as the default Hermes chat model.

Step 1: Install or open Hermes Desktop

Install Hermes Desktop from the official Hermes download page, then open the app. Hermes Desktop and the Hermes CLI use the same underlying agent, configuration, keys, sessions, skills, and memory, so you can configure the model provider through the terminal and use the result inside the desktop app.

On Windows, Hermes can run natively on Windows 10 and Windows 11. The native Windows installer does not require admin rights, and Hermes stores its install/runtime data under the user's local Hermes directory. To confirm the exact paths on your machine, run:

This command shows where Hermes is reading its config and secrets from.

Step 2: Start the Hermes model setup wizard

Open a terminal and run:

Hermes will ask you to choose a model provider. Select:

This option is the correct route for AIsa because AIsa exposes an OpenAI-compatible model API.

Step 3: Add the AIsa endpoint and API key

When Hermes asks for the API endpoint, enter:

When Hermes asks for the API key, paste your AIsa API key.

Keep the key private. Do not record it, screenshot it, paste it into chat, commit it to GitHub, or place it in public documentation.

Step 4: Choose API mode

When Hermes asks for the API compatibility mode, choose:

AIsa also supports OpenAI-compatible chat completions at /v1, so Chat Completions is the most explicit option for this setup.

Step 5: Choose a supported text model

Hermes should show available models from the endpoint. Select a supported text, reasoning, or coding model.

For example, AIsa's model catalog includes text-capable models from providers such as OpenAI, Anthropic, Google, DeepSeek, Alibaba Qwen, Moonshot Kimi, MiniMax, Zhipu AI, and ByteDance Seed. Use the exact model ID shown in the AIsa catalog or Hermes model list.

Example format:

Your available model list may change over time, so always copy the exact model ID from the current AIsa model catalog or from the Hermes setup list.

Step 6: Set context length

When Hermes asks for context length, press Enter to leave it blank unless your team has a specific context length requirement.

Leaving it blank lets Hermes auto-detect the model context when available.

Step 7: Verify the configuration

After setup, run:

Look for the model section. The exact formatting can vary by Hermes version, but the important parts are:

Some Hermes versions may display a named custom provider such as:

That is fine. The key checks are:

1. The model is a valid AIsa text model ID.
2. The base URL is https://api.aisa.one/v1.
3. Hermes is using a custom/OpenAI-compatible endpoint, not a different provider route.

Step 8: Test in the terminal

Before testing inside Hermes Desktop, run a quick terminal test:

Send this prompt:

If Hermes responds, the core provider setup is working.

Step 9: Test inside Hermes Desktop

Open Hermes Desktop and start a new chat. Send:

A successful response confirms that Hermes Desktop is using the same configured backend.

Optional: Connect AIsa capabilities inside Hermes

After the model endpoint works, you can ask Hermes to fetch AIsa's agent-facing instructions:

Once Hermes has the relevant AIsa instructions, you can test practical workflows such as web research, model routing, market data lookup, content drafting, or agent task planning, depending on the capabilities enabled for your AIsa account.

A simple post-setup test prompt

Use this prompt inside Hermes Desktop for a screen-recorded test:

Troubleshooting

No inference provider configured

Run:

Then choose Custom Model / OpenAI-compatible endpoint, enter the AIsa endpoint, add your API key, and select a supported text model.

Endpoint verification fails

Check the base URL:

Use /v1 for OpenAI-compatible Chat Completions.

Authentication error

Create or copy a valid AIsa API key, then re-run:

Paste the key again when Hermes asks for it.

Model error or model not found

Use a valid model ID from the current AIsa model catalog or the model list Hermes returns during setup. Avoid display names when Hermes expects a model ID.

Hermes asks for an OpenRouter key

That usually means Hermes is routing through OpenRouter instead of the AIsa custom endpoint. Re-run:

Then select the custom/OpenAI-compatible endpoint again and confirm that the base URL is set to AIsa.

Desktop model switching causes issues

The model switcher can only switch between models and providers that are already configured. Use hermes model to add or repair a provider setup. If a model switch changes the route unexpectedly, inspect the active config with:

Then re-run the model setup wizard.

502 Bad Gateway

A 502 usually means the endpoint was reached, but the upstream server returned an invalid or incomplete response. Retry after a short wait. If one model returns repeated 502 errors while another model works, use the working model and report the failing model route to the team.

Security checklist

Before publishing a video or screenshot:

1. Hide the API key.
2. Hide the full .env file if it contains secrets.
3. Hide config output that includes an API key.
4. Rotate any API key that was accidentally exposed.
5. Use a fresh key for public demos.

Quick reference

Why this matters

This setup lets builders use Hermes Desktop as their agent workspace while AIsa provides the model gateway. Instead of configuring every model provider separately, builders can point Hermes to AIsa, add one API key, select a supported model, and start testing agent workflows from the desktop.

For teams building with agents, that creates a simpler foundation: one workspace, one model endpoint, and a path to AIsa-powered capabilities from inside Hermes.

References checked

• AIsa API Reference: https://aisa.one/docs/api-reference
• AIsa guide, Use AIsa in Hermes Agent: https://aisa.one/docs/guides/tutorials/use-aisa-in-hermes-agent
• AIsa Supported Models: https://aisa.one/docs/guides/models
• Hermes Desktop App docs: https://hermes-agent.nousresearch.com/docs/user-guide/desktop
• Hermes AI Providers docs: https://hermes-agent.nousresearch.com/docs/integrations/providers
• Hermes Windows Native docs: https://hermes-agent.nousresearch.com/docs/user-guide/windows-native