Hermes Agent
Hermes Agent API: enable the OpenAI-compatible server
Updated 19 November 2026
“Hermes API” can mean two things. This page is about the API server, an HTTP endpoint in front of your agent so that other software, such as a chat frontend or your own script, can call it. If you mean the key for the AI model Hermes itself uses, that is a different setup: see Hermes Agent with ChatGPT or Hermes Agent with Claude.
Facts come from the Hermes Agent 0.23.2 documentation, mainly the API Server page, plus its command reference, all read on 19 November 2026.
Turn it on
The docs describe the API server as exposing the agent as an OpenAI-compatible HTTP endpoint. It is off by default. To enable it, add these lines to ~/.hermes/.env:
API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-devReplace the example key with your own secret. Then start the gateway, which is the process that also serves your chat apps:
hermes gatewayThe docs show the startup line as the API server listening on http://127.0.0.1:8642. That gives you the basics:
- Base URL. Point a client at
http://localhost:8642/v1. - Port.
8642by default, changed withAPI_SERVER_PORT. For the other ports Hermes uses, see Hermes Agent ports. - Bind address.
127.0.0.1by default, so only the same machine can reach it.API_SERVER_HOSTchanges it. - Key.
API_SERVER_KEYis the bearer token clients send. The docs mark it as required.
The same settings can live in ~/.hermes/config.yaml under gateway.api_server (keys such as enabled, port, host, key, cors_origins and model_name). The docs say environment variables take precedence over config.yaml.
Hermes needs a configured model provider and tool backends, because the API server only passes requests to the agent. The docs describe a Nous Portal subscription as covering both models and tools, and say to run hermes setup --portal before starting the API server.
Send a first request
With the gateway running, this is the docs’ own test call:
curl http://localhost:8642/v1/chat/completions \
-H "Authorization: Bearer change-me-local-dev" \
-H "Content-Type: application/json" \
-d '{"model": "hermes-agent", "messages": [{"role": "user", "content": "Hello!"}]}'The reply is a standard chat completion. The model name hermes-agent is the default for the default profile; GET /v1/models lists what your server advertises, and API_SERVER_MODEL_NAME can change it. To confirm the server is up without a key, call GET /health, which returns {"status": "ok"}.
One behaviour to know: on /v1/chat/completions and /v1/responses, a model value sent without a provider is ignored unless you set direct_model_requests: true under gateway.platforms.api_server in config.yaml. The docs say this is so that clients that hardcode a name like gpt-4o still fall back to your gateway default. Requests that include an explicit provider are honoured either way.
Your agent handles the request with its full toolset (the docs list terminal, file operations, web search, memory and skills) and returns the final response, so a call can take longer than a plain model call. With "stream": true you get server-sent events, with tool progress shown inline.
The endpoints and what they are for
The docs split the surface into the OpenAI-compatible routes and Hermes-specific ones. The liveness check is available at /health and /v1/health without a key. The other endpoints use bearer authentication.
| Endpoint | What it is for |
|---|---|
POST /v1/chat/completions | Standard Chat Completions. The conversation travels in the request; supports streaming and inline images. |
POST /v1/responses | OpenAI Responses format, with server-side conversation state through previous_response_id or a named conversation. |
GET /v1/responses/{id}, DELETE /v1/responses/{id} | Fetch or delete a stored response. |
GET /v1/models | Lists the agent as a model. Most frontends need it to discover the model. |
GET /api/model/options | Richer provider and model inventory for Hermes-aware clients, with pricing and capability hints. |
GET /v1/capabilities | Machine-readable list of what this server version supports, so a UI can check before relying on a feature. |
GET /health, GET /v1/health | Cheap liveness check. |
GET /health/detailed | Authenticated readiness check for monitoring: status and counts for config, state database, model, disk, platforms and active runs. |
POST /v1/runs | Start an agent run and get a run_id back, for clients that want to follow progress instead of holding one request open. |
GET /v1/runs/{run_id}, GET /v1/runs/{run_id}/events | Poll a run’s state, or follow its tool calls and lifecycle events over server-sent events. |
POST /v1/runs/{run_id}/stop | Interrupt a running turn. |
POST /v1/runs/{run_id}/approval, POST /v1/runs/{run_id}/clarify | Answer an approval request or a clarification question that a run is waiting on. |
/api/sessions and /api/sessions/{id}/... | Manage Hermes sessions over REST: list, create, read, rename, delete, fork, read messages, run a turn, or stream one. |
/api/jobs and /api/jobs/{job_id}/... | Create and manage scheduled jobs: list, create, fetch, update, delete, pause, resume or run now. |
GET /v1/skills, GET /v1/toolsets | Read-only lists of the agent’s skills and toolsets, so a client does not have to ask the model. |
Use Chat Completions to send the conversation history with each request, or Responses to keep conversation state on the server. The runs, sessions and jobs routes are for building a dashboard or control panel around the agent. The docs also describe an Idempotency-Key header on /v1/chat/completions, /v1/responses and /v1/runs for safe retries, with rules for what a repeated key returns; read that section if your client retries automatically.
Stateless or with memory of the conversation
The two main endpoints differ here, and the docs are direct about it.
- Chat Completions is stateless. The docs say the full conversation is included in each request through the
messagesarray. Your client resends the history every time, as it would with any OpenAI-compatible server. - Responses keeps state on the server. Send
previous_response_idwith the id of the earlier response, or use a namedconversation, and the server rebuilds the history, including tool calls and results.
Two further controls are in the docs. Sending an X-Hermes-Session-Id header on Chat Completions or Responses continues a named Hermes session (the docs say history then comes from the session). And X-Hermes-Session-Key gives long-term memory providers such as Honcho a stable per-channel scope, which matters for frontends shared by several people. A session id can name one the API server created, but not one owned by another surface such as the CLI or a chat app; that is refused with a 409. For how Hermes memory works in general, see Hermes Agent memory.
Stored responses are kept in SQLite and survive a gateway restart, with a cap on how many are kept. The documented limit is 100 stored responses, with the least recently used ones dropped first.
Connect a frontend or an SDK
Any client that speaks the OpenAI format can connect. Give it the base URL http://localhost:8642/v1 and your API_SERVER_KEY as its API key. The docs list these:
| Client | How the docs say to connect |
|---|---|
| Open WebUI | Has its own integration guide in the Hermes docs |
| LobeChat | Custom provider endpoint |
| LibreChat | Custom endpoint in librechat.yaml |
| AnythingLLM | Generic OpenAI provider |
| NextChat | BASE_URL environment variable |
| ChatBox | API Host setting |
| HF Chat-UI | OPENAI_BASE_URL |
| OpenAI Python SDK | OpenAI(base_url="http://localhost:8642/v1"), plus your key as the SDK’s API key |
Jan and big-AGI also appear in the docs’ list. Open WebUI, according to the docs, connects server to server and needs no CORS setting.
To give several people separate agents, the docs use profiles: one profile per person, each with its own API_SERVER_PORT and API_SERVER_KEY in that profile’s .env, started with hermes -p alice gateway. Each one then advertises its profile name as the model id.
Security: read this before you open it up
The docs’ warning is blunt: the API server gives full access to the agent’s toolset, including terminal commands. Anyone who holds the key can make the agent run things on that machine, so treat the key like a password.
- Always set a key. The docs say
API_SERVER_KEYis required for every deployment, including the default local-only bind. - Keep the default bind.
127.0.0.1means only software on the same machine can connect.API_SERVER_HOSTchanges the bind address, and a non-loopback address can allow connections from other machines. For private remote access, see Hermes Agent with Tailscale. - CORS is off by default. Set
API_SERVER_CORS_ORIGINSonly if a browser must call Hermes directly, and keep the list to explicit origins, for examplehttp://localhost:3000. Server-to-server frontends do not need it. - One key per profile. With multi-profile routing, each profile prefix needs its own key, and a shared default key is rejected with a 401 on a named profile.
- A concurrency cap exists.
max_concurrent_runsdefaults to 10 and limits concurrent runs started through Chat Completions, Responses, Runs and session-chat endpoints. Cron-triggered runs use the scheduler’s separate limits.
Responses carry X-Content-Type-Options: nosniff and Referrer-Policy: no-referrer. The docs do not describe TLS, so if you reach the server over a network, put it behind something that provides it.
Common errors
- Connection refused. The API server is off, the gateway is not running, or the client is on another machine while the server is bound to
127.0.0.1. CheckAPI_SERVER_ENABLED=true, restarthermes gateway, and call/healthfrom the same machine first. - 401 Unauthorized. The bearer token does not match
API_SERVER_KEY, or on a named profile prefix you used the default profile’s key. Environment variables overrideconfig.yaml, so check both places. - Your model name is ignored. Bare
modelvalues are opt-in; see the first request section fordirect_model_requests. - 400 unsupported_content_type. Uploaded files (
file,input_file,file_id) and non-imagedata:URLs are not supported. Inline images are. - 409 permission_denied. The session id belongs to a CLI, desktop or chat-app conversation. Use a fresh id for API work.
- Idempotency conflicts. For Chat Completions and Responses in canonical mode, reusing an
Idempotency-Keywith different identity fields or a different target givesadmission_conflict: HTTP 409, except that streaming Chat Completions reports it in the final error chunk of an HTTP 200 stream. For Runs, reusing a key with a different JSON payload gives HTTP 409idempotency_key_conflict. Use a new key for new work. - 429 Too many concurrent runs. The cap in
max_concurrent_runswas reached. Back off and retry, or raise the cap. - 503 with Retry-After. The docs give
runtime_drainingandstorage_unavailablefor a gateway that is shutting down or whose database stayed locked. Retry after the delay. - A browser app fails but curl works. That points to CORS: add the app’s exact origin to
API_SERVER_CORS_ORIGINS. - A reply stops with finish reason length. The docs say a turn that runs out of its iteration budget (
agent.max_turns) still returns a wrap-up withfinish_reason: "length". Treat it as an answer to a task that stopped short.
The API on ReadyHermes
ReadyHermes has the same idea as a button. In the workspace, Bot tools has an API endpoint item for calling your assistant from your own apps and scripts through an OpenAI-compatible API. Press Turn on and it shows a Base URL and an API key, plus a ready-made curl example that posts to the Base URL followed by /chat/completions with an Authorization: Bearer header.
- The key is shown only once, so copy it and keep it safe.
- Replace key makes a new key and the old one stops working immediately. Turn off stops every app using the key immediately.
- Requests use your assistant just as chatting does, so they use the AI included with your plan or your own model key.
- You do not set
API_SERVER_ENABLED,API_SERVER_KEY, ports or CORS yourself there.
We have not documented which other endpoints from the table above are exposed on ReadyHermes, or whether streaming is available there, so test what you need before building on it. Plans start from US$3.99 a month (Lite) or US$6.99 (Pro), with US$1 of AI included every month and a 1-hour free trial. See managed Hermes Agent hosting for the rest.
Questions
What is the Hermes Agent API server?
It is an OpenAI-compatible HTTP endpoint in front of your Hermes agent. Frontends such as Open WebUI, LobeChat or LibreChat, or your own scripts, can call it, and the agent handles each request with its full toolset.
How do I enable the Hermes API server?
Add API_SERVER_ENABLED=true and API_SERVER_KEY with your own secret to ~/.hermes/.env, then run hermes gateway. The docs show it listening on http://127.0.0.1:8642.
What is the Hermes API base URL and port?
The base URL for clients is http://localhost:8642/v1. The port is 8642 by default and can be changed with API_SERVER_PORT. The bind address is 127.0.0.1 by default and can be changed with API_SERVER_HOST.
Is the Hermes API stateless?
Chat Completions is stateless: the full conversation goes in the messages array of each request. The Responses endpoint keeps state on the server through previous_response_id or a named conversation, and an X-Hermes-Session-Id header can continue a session.
Is the Hermes API safe to expose?
The docs warn that it gives full access to the agent's toolset, including terminal commands, and that API_SERVER_KEY is required for every deployment. Keep the default 127.0.0.1 bind unless you need more, and keep CORS origins to an explicit list.