Skip to main content

โ€‹
1. Overview

Hermes Desktop uses the same Agent core as the CLI. When both connect to the same backend and profile, they share model settings, keys, sessions, skills, and memory. Add GravitexAI through Custom Endpoints to use models available to your account.
Updated against the official Hermes Desktop documentation reviewed on October 19, 2026. The screenshots show the Chinese interface; the steps below use the corresponding English labels.

โ€‹
2. Installation and prerequisites

  • Download the appropriate desktop package from the Hermes website. The official macOS desktop package supports Apple Silicon; see the installation guide for platform requirements.
  • Create an API key in the GravitexAI Console.
  • Choose a model with tool calling and a context window of at least 64,000 tokens.
If you already have the Hermes CLI, you can launch Desktop with:
If GravitexAI is already configured in the CLI, check that Desktop uses the same backend and profile, then select the existing provider. See Hermes Agents for file-based configuration.

โ€‹
3. Configuration

โ€‹
Step 1: Check the backend and settings scope

Open Settings โ†’ Gateways โ†’ Current window and select Local gateway under Connection mode. Use Remote gateway, Hermes Cloud, or Connect via SSH only when connecting to a remote Hermes backend. After making a change, click Save and reconnect. Select Local gateway in the current-window gateway settings
Local gateway means the Hermes backend runs on your computer. GravitexAI cloud inference still requires internet access. With a remote connection, configuration and API requests are handled by that backend.
If you have multiple profiles, check Applies to at the top of Settings. Configure the endpoint and main model for the same target profile. This selector may be hidden when only one profile exists.

โ€‹
Step 2: Open Custom Endpoints

Go to Settings โ†’ Providers โ†’ Custom Endpoints and click New endpoint at the bottom of the form. To edit an existing endpoint, select it in the list and use the Edit Endpoint form below.

โ€‹
Step 3: Match each endpoint to its protocol

Create separate endpoints for GPT, Claude, and other Chat Completions models. The same GravitexAI API key can be reused, but each endpoint must use the protocol supported by its model. Use model IDs listed in the GravitexAI Model Catalog and available to your account. Set an explicit Default Model so it can be tested and selected after saving.
Select API Mode explicitly; entering a URL alone is insufficient. GPT uses Responses API with /v1. Claude uses Anthropic Messages without /v1 or /anthropic. Use Chat Completions only for models that support it. If API Mode is missing, update Desktop and the Hermes backend it connects to.
The screenshot shows gravitex-gpt: an Endpoint URL ending in /v1, Responses API, and gpt-5.5. Separate Claude and Chat Completions endpoints appear above it. Configure the GPT Responses API endpoint

โ€‹
Step 4: Test and save

  1. Enable Discover models if you want to query the endpoint catalog. Enter a model ID manually if discovery fails.
  2. Select Use for new chats for the endpoint you want as the default. When adding several endpoints, enable it only for your intended default.
  3. Click Test to check the inference route for the selected API Mode.
  4. Click Save after testing. A saved endpoint can also be activated with Use.
Test sends a real inference request and may incur a small API charge. When editing an existing endpoint, leaving API Key blank keeps the saved key.

โ€‹
Step 5: Select and apply the main model

Open Settings โ†’ Model โ†’ Main model. Select gravitex-gpt, gravitex-claude, or gravitex-chat, choose a matching model, and click Apply to save the profile default. Select gravitex-claude and apply the main model The screenshot uses gravitex-claude with claude-sonnet-5-5. For GPT, select gravitex-gpt and a GPT model. Set reasoning according to model support. Leave the context-window override at 0 to use the detected value.
Saving an endpoint or API key does not by itself select the main model. If Hermes says it is not connected to any AI provider, select the provider and model here, click Apply, and check that Applies to matches the chat profile.

โ€‹
Step 6: Verify in a new chat

Create a New session, check the model picker beside the composer, and send a short test message.
  • Main model โ†’ Apply changes the profile default.
  • The composer picker remembers its own selection and may retain an earlier model; check it in the new chat.
  • Changing the default does not automatically switch an already open chat. Use that chatโ€™s picker or start another session.
The example sends โ€œHelloโ€ and receives a reply. The composer shows the selected model, Sonnet 5.5. New chat with a successful model reply

โ€‹
4. Auxiliary models

Settings โ†’ Model โ†’ Auxiliary models lets you assign models to vision, web extraction, compression, and title generation. Start with auto ยท use main model. To override a task, click Change and select a configured provider and a suitable model; vision requires image-input support. Check for auxiliary tasks previously pinned to another provider.

โ€‹
5. Success checks

  • The endpoint is saved and API Mode matches the model.
  • A provider and model are selected under Main model, with Apply completed.
  • A new chat shows the intended model and receives a normal reply.
  • There are no provider-connection, authentication, endpoint, or model-not-found errors.

โ€‹
6. Troubleshooting

Check the backend and profile. Open Settings โ†’ Model โ†’ Main model, choose the saved GravitexAI provider and model, and click Apply. Merely adding an endpoint or key, or leaving the original auto selection, may not complete main-model setup.
Edit the endpoint, enter a complete valid key, save, and test. A blank field keeps the old key. Check key status and model permissions in your GravitexAI account.
GPT requires the URL with /v1 and Responses API; Claude requires the root URL without /v1 and Anthropic Messages. Do not append /responses or /messages to Endpoint URL.
Copy an available model ID from the GravitexAI Model Catalog into Default Model. Match the endpoint protocol; changing only the model ID cannot fix an incompatible API Mode.
Check the profile you edited. Running chats and profile defaults are separate. Switch in the chat picker, or start a new session and select the intended model.
Check that both use the same Hermes backend, profile, and data directory. Remote backends do not automatically read local CLI credentials; configure the target backend and profile.
No. The Agent backend runs locally, but GravitexAI inference still uses network requests. Check connectivity from the backend machine.

โ€‹
7. Resources

Hide API keys in screenshots, chats, and repositories. Revoke and replace any exposed key in the GravitexAI Console.