Hermes Agent

Hermes Agent is an open-source AI agent from Nous Research. It runs as a local or server-hosted agent runtime with tools, memory, skills, terminal access, and messaging integrations. In Enconvo, Hermes Agent is used through its OpenAI-compatible API server. After the Hermes gateway is running, Enconvo can use Hermes like any other AI model in chat, Enconvo agents, and model-powered features.

New to Hermes? Start with the Hermes Agent Quickstart, then return here to connect it to Enconvo.

API reference: Hermes Agent API server docs. Source: Hermes Agent GitHub repo.

Before you start

Hermes Agent already installed and configured
Hermes gateway running with the API server enabled
The API server token from API_SERVER_KEY in ~/.hermes/.env
Enconvo with the Hermes Agent AI model provider enabled

Hermes exposes OpenAI-compatible endpoints such as /v1/models, /v1/chat/completions, and /v1/responses. Enconvo’s Hermes provider uses the Chat Completions API (/v1/chat/completions). Enconvo does not use the Hermes Responses API for this provider. Configure Hermes as an OpenAI-compatible Chat Completions provider.

Set up automatically

Open Settings → AI Model → Hermes Agent. The setup card can start, stop, and configure the local Hermes API server for you. Use Auto Setup when Hermes is installed on the same Mac as Enconvo. Enconvo will:

Find Hermes

Check that the hermes CLI exists on this Mac.

Enable the API server

Update ~/.hermes/.env with API_SERVER_ENABLED=true and an API_SERVER_KEY if one is missing.

Start the gateway

Start the Hermes gateway service.

Verify the API

Probe the local API server with /v1/health and /v1/models.

Save credentials

Save the base URL and API server key into Enconvo’s Hermes credentials.

The setup card shows a runtime badge such as Running or Stopped. While the card is visible, Enconvo refreshes this status periodically and stops refreshing when the card is no longer visible.

Get the base URL and API key

Use this base URL when Enconvo runs on the same Mac as Hermes:

http://127.0.0.1:8642/v1

Read the API server token from ~/.hermes/.env:

awk -F= '/^API_SERVER_KEY=/{print $2}' ~/.hermes/.env

Enconvo sends this value as:

Authorization: Bearer <API_SERVER_KEY>

To test the OpenAI-compatible endpoint directly:

curl http://127.0.0.1:8642/v1/chat/completions \
  -H "Authorization: Bearer <API_SERVER_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hermes-agent",
    "messages": [
      { "role": "user", "content": "Hello!" }
    ]
  }'

Use the base URL ending in /v1, not the full /v1/chat/completions endpoint.

Connect Hermes by hand

Open Settings → AI Model → Hermes Agent, then configure the credential provider.

Hermes Agent credential settings in Enconvo

Setting	Value
Hermes Base URL	`http://127.0.0.1:8642/v1`
API Server Key	`API_SERVER_KEY` from `~/.hermes/.env`

Click Validate after entering the base URL and token.

How requests and attachments work

Enconvo sends Hermes requests through OpenAI-compatible Chat Completions:

POST /v1/chat/completions

Use hermes-agent or the model name advertised by the Hermes /v1/models endpoint. Image attachments are not sent to Hermes by Enconvo. Treat the Hermes provider as a text/chat provider in Enconvo, even if your upstream Hermes API server advertises image input support. For image workflows, use a vision-capable model provider or run OCR/image analysis before sending text to Hermes.

Use Hermes as an AI model

Once configured, Hermes appears in the model selector. Choose Hermes Agent and select the advertised model, usually hermes-agent.

Use this mode when you want an Enconvo conversation, command, or feature to run through Hermes Agent while keeping the normal Enconvo interface.

Open the model picker

In chat or another model-powered Enconvo feature, click the current model name.

Choose Hermes Agent

Select Hermes Agent in the provider list.

Select the Hermes model

Choose hermes-agent or the model name advertised by your Hermes API server.

Run the feature normally

Ask your question or run the Enconvo feature. Hermes handles the model call behind the scenes.

Enconvo loads Hermes models from the Hermes /v1/models endpoint. If Hermes is not running or the endpoint is unavailable, Enconvo falls back to hermes-agent.

Create an Agent for Hermes

You can also create an Enconvo agent that coordinates Hermes Agent. This is useful when you want an Enconvo-facing workflow, tool set, or prompt around Hermes’ agent runtime.

Open Create Agent

Open SmartBar and search for Create Agent.

Name the agent

Create a clear title, such as Hermes Agent.

Write coordinator instructions

Give the Enconvo agent instructions that explain how it should work with Hermes.

You coordinate Hermes Agent for the user.

Use Hermes for agentic work, automation, terminal-backed tasks, and requests that should run through the user's Hermes setup.
Summarize what Hermes did, surface any blockers, and ask before destructive or irreversible actions.

Choose the Hermes model

In the agent’s model settings, select Hermes Agent and choose hermes-agent.

Save and use the agent

Start a conversation with the new Enconvo agent. It will use Hermes while retaining the Enconvo agent interface and tools you configured.

Connect over your network

If Hermes is running on another machine, use the host machine’s LAN IP in Enconvo:

http://<hermes-host-lan-ip>:8642/v1

LAN access should use a strong API_SERVER_KEY. Only expose the Hermes API server on networks you trust.

Troubleshooting

Hermes Agent does not appear in the model picker

Make sure the Hermes provider is enabled in Settings → AI Model. If the model list is empty, confirm the gateway is running with hermes gateway status.

Validation fails with unauthorized

Recheck API_SERVER_KEY in ~/.hermes/.env. Enconvo expects this value and sends it as a Bearer token.

Connection fails

Confirm the API server is healthy with curl http://127.0.0.1:8642/v1/health. If Enconvo runs on another device, use the host’s LAN IP and make sure Hermes is bound for network access.

Start succeeds but the status takes a moment to update

Service managers can return before the API server is ready. Wait a few seconds and check the setup card’s runtime badge again, or run hermes gateway status and test curl http://127.0.0.1:8642/v1/health.

Image attachments are ignored

The Hermes provider in Enconvo is currently text-only. Enconvo will not send image attachments to Hermes; choose a vision-capable provider for direct image input.

Wrong base URL

Enter http://<gateway-host>:8642/v1. Do not include /chat/completions in the Enconvo base URL field.

Need gateway logs

Read Hermes gateway logs with tail -f ~/.hermes/logs/gateway.log and errors with tail -f ~/.hermes/logs/gateway.error.log.

OpenClaw

Connect another agent gateway the same way.

Agents

Give an Agent instructions and tools.

Get started

Enconvo Cloud and plans

Popular providers

More providers

Gateways and enterprise

Agent gateways

Local models

Speech

Before you start

Set up automatically

Get the base URL and API key

Connect Hermes by hand

How requests and attachments work

Use Hermes as an AI model

Create an Agent for Hermes

Connect over your network

Troubleshooting

OpenClaw

Agents

​Before you start

​Set up automatically

​Get the base URL and API key

​Connect Hermes by hand

​How requests and attachments work

​Use Hermes as an AI model

​Create an Agent for Hermes

​Connect over your network

​Troubleshooting

​Related

OpenClaw

Agents

Before you start

Set up automatically

Get the base URL and API key

Connect Hermes by hand

How requests and attachments work

Use Hermes as an AI model

Create an Agent for Hermes

Connect over your network

Troubleshooting

Related