Hermes Agent API Integration: One Endpoint, Any Frontend

Every OpenAI-compatible chat frontend already knows how to speak /v1/chat/completions. Hermes Agent takes that fact and runs with it: point any of them at http://localhost:8642/v1, pass an API key, and you get the full Hermes runtime - tools, memory, skills, cron - behind a familiar HTTP surface with no client changes.

That is the whole idea of the Hermes API server. It is not a Hermes-specific SDK you need to learn. It is the OpenAI shape, served locally, wrapping the agent. If you already have Open WebUI, LobeChat, LibreChat, NextChat, ChatBox, or a script that talks to openai-python, you already know how to integrate.

This post walks through what the API server exposes, how to turn it on, and the patterns that hold up when you start plugging real frontends into it.

What the API Server Actually Exposes

The API server is a component inside the Hermes gateway. When enabled, it binds to 127.0.0.1:8642 by default and speaks the OpenAI HTTP contract on four endpoint families:

/v1/chat/completions - the classic Chat Completions endpoint. Stateless, streaming or non-streaming. This is what 90% of OpenAI-compatible frontends use.
/v1/responses - the newer Responses API, stateful, with previous_response_id chaining so a conversation can be resumed by ID instead of resending the whole message history.
/v1/runs - a long-form task API for jobs that take longer than a single request cycle. The client submits a run, polls for status, and pulls the result when it is ready.
/api/jobs - a REST layer for the built-in cron scheduler, so an external app can create, list, and cancel scheduled agent runs the same way it would manage any other resource.

Every request you send goes through the full Hermes stack. The model does not answer alone. It has terminal access, filesystem, web search, memory files, and any MCP servers you configured. For a broader look at how those tools reach the model in the first place, see Hermes Agent and MCP.

Turning the API Server On

The API server is off by default. You opt in with two settings in ~/.hermes/.env:

API_SERVER_ENABLED=true
API_SERVER_KEY=$(openssl rand -hex 32)

Then restart the gateway (hermes gateway). The same values can live in ~/.hermes/config.yaml under gateway.api_server: if you prefer YAML, but environment variables win when both are set.

A few things worth knowing before you flip it on:

The default bind address is 127.0.0.1, which means the endpoint is reachable only from the same host. If you are running Hermes in a Docker container and want another container or your host machine to reach it, also set API_SERVER_HOST=0.0.0.0 and make sure the port is mapped.
API_SERVER_KEY must be at least 8 characters. Treat it like any other API secret - do not commit it, do not paste it into a shared channel. If it leaks, anything on the network can execute agent runs on your account with your tools and your credentials.
The port 8642 is a Hermes convention, not a standard. If it conflicts with something on your machine, change API_SERVER_PORT. Everything downstream just needs the base URL.

Once the server is up, sanity-check it with any OpenAI SDK:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8642/v1",
    api_key="the-key-you-set",
)

resp = client.chat.completions.create(
    model="hermes",
    messages=[{"role": "user", "content": "What day is it, and read README.md."}],
)
print(resp.choices[0].message.content)

Nothing about that snippet is Hermes-specific except the base URL. That is the point.

Frontends That Just Work

Because the surface is OpenAI's, most existing chat frontends connect with a single settings change. A short tour of the ones people ask about most:

Open WebUI. Admin Settings → Connections → OpenAI → Add Connection. Set the base URL to http://localhost:8642/v1 and the API key to your API_SERVER_KEY. The most common mistake is dropping the /v1 suffix - do not. Open WebUI persists this in its own database, so if you change the key later, update it through the admin UI, not by re-editing an env var.

LobeChat. In Settings → Language Model → OpenAI, override the API proxy URL to http://localhost:8642/v1 and paste the key. Model list can be a single entry named hermes; the server maps everything to the same agent.

LibreChat. Add a custom endpoint in librechat.yaml with apiKey: your-key, baseURL: http://localhost:8642/v1, and any model name you want to show in the picker. LibreChat handles the rest as if you configured a self-hosted OpenAI.

NextChat, ChatBox, and friends. Same pattern: base URL and key. If a frontend claims OpenAI compatibility, it almost certainly works.

The nice thing about running Hermes behind these frontends is that you get their UI polish - chat history, session pinning, model switching, side-by-side comparisons - while the "model" is actually your agent with your tools.

Streaming, Tool Progress, and the Responses API

Two things about the API server surprise people the first time.

The first is that streaming carries tool progress. When the agent decides to run the shell, hit the web, or read a file, the stream surfaces that step to the client. Frontends that respect the streaming format will show "running tool: web_search" or similar inline, then continue with the model's actual reply. You get real observability of what the agent is doing without wiring a separate log tap.

The second is the Responses API. /v1/responses is stateful in a way /v1/chat/completions is not. Instead of re-sending the full message history on every turn, the client can pass previous_response_id and the server picks up where the prior response left off. That matters for long, multi-turn conversations where re-uploading history is expensive, and it maps naturally onto the way OpenAI's own newer SDKs are moving. If your frontend supports both, prefer Responses for long-lived sessions and Chat Completions for one-shot calls.

Runs and Jobs cover the cases that are awkward in the request/response model: a run that takes ten minutes to finish, or a scheduled job that fires every morning at 8am and drops a summary in a channel. See Hermes Agent scheduled tasks and automation for the pattern on the cron side.

Patterns Worth Following

A few habits that have held up when the API server is doing real work:

Keep the endpoint on localhost until you have a reason. The default bind is safe. If you need remote access, put a real reverse proxy in front of it with TLS and authentication, do not just flip the host to 0.0.0.0 on the public internet.

One key per client, if you can. The current server takes a single API_SERVER_KEY. If you are wiring multiple frontends and want to revoke one without breaking the rest, run separate Hermes instances behind separate keys, or terminate at a proxy that mints per-client keys and forwards a shared one to the agent.

Model name is a label, not a router. Every request goes through the same agent. Point every frontend at the same model: "hermes" entry unless you specifically want them to show different names in their UI.

Watch the logs when you first plug in a new frontend. The gateway logs each incoming request and each tool call. Skim them on the first few conversations - you will learn quickly whether the frontend is sending the messages you expect or, for example, injecting a system prompt that fights your existing memory files.

Prefer Responses for long chats, Chat Completions for scripts. The client-side complexity is the same. The server-side cost is not.

Where Hermify Fits

Running the API server yourself is straightforward, but it still means keeping the gateway process alive, the container upgraded, and the port reachable. If you would rather skip that, Hermify runs a managed Hermes Agent for you on Telegram, with the same tools, memory, and skills, live in about a minute. Today the managed API surface is Telegram-first; the self-hosted API server is where you go when you want to point custom clients at your own agent. Either way, the underlying runtime is the same, so the mental model here transfers.