How Do You Verify the Hermes Agent API?
Enable `API_SERVER_ENABLED` and configure `API_SERVER_KEY` on a private Hermes gateway. Check `GET /health`, then verify an authenticated `POST /v1/chat/completions` before connecting Open WebUI or LobeChat.
Check the response envelope before connecting a UI
Enable the API server in the Hermes environment and configure its API key there. Configure the model provider separately. From the same network path the frontend will use, send a nonstreaming Chat Completions request using the intended model and a short prompt with a known answer. Ask for `HERMES-API-OK` exactly and request no tool use. Capture only the HTTP status and a redacted first choice. Read its terminal reason and compare the message text with the expected answer. If the endpoint returns HTTP 200 with a length-limited result, the connection worked and the acceptance test still failed. Using a direct client first gives you an observable baseline for diagnosing frontend base URL, model, or streaming differences.
API Server | Hermes AgentCompare hosting by the evidence it exposes
On a Docker host, port 8642 serves the gateway’s health and API endpoints. The documented container layout keeps Hermes data under `/opt/data`, backed by a host directory. In staging, capture a health response and an authenticated completion, recreate the gateway with the same mount, and repeat both calls using the same client settings. A health response followed by a chat rejection after recreation gives you a narrower investigation than a dead socket. Check whether the replacement inherited the intended settings and whether the rejection came from the gateway or an intermediary. On managed hosting, ask who can retrieve startup and request diagnostics, what redacted fields you receive, and who can restore the equivalent persisted settings. Compare the same two captures before and after a vendor-led restart.
Hermes Docker Setup | Hermes AgentConfigure the two sides of the connection
The Hermes Agent API gives compatible frontends such as Open WebUI and LobeChat an HTTP interface to Hermes. Start with a working model configuration in Hermes. The official API guide shows hermes setup --portal for operators who choose Nous Portal. Set API_SERVER_ENABLED to true in ~/.hermes/.env, then check the API guide for your installed release to confirm the server key, bind address, and gateway startup instructions.
Keep the gateway credential on the client side of the connection and configure the model provider credential in Hermes. Use distinct secrets and keep the first listener reachable only by the intended test client. Verify a plain chat without tools first. Once it passes, test one harmless tool operation your application needs, such as reading a fixture file from the pilot workspace.
API Server | Hermes AgentVerify the endpoint your client uses
The Hermes Docker guide documents port 8642 for the gateway's HTTP API and health endpoint. Use the health path documented for your version to establish that your client can reach the gateway. Then use the documented chat route and a valid client credential to verify an actual model reply. Confirm the exact paths and methods for any additional operations your frontend needs, including model listing, Responses, runs, or scheduled jobs, against your deployed release.
In an illustrative test, suppose Open WebUI and Hermes share a private network and your test prompt asks for the sum of 8 and 13. Record the health result, verify that a request without the gateway credential is rejected where authentication is required, then send the authenticated chat and check for 21. Repeat with streaming if the frontend depends on it.
Hermes Docker Setup | Hermes AgentFollow the request to the failing service
If health fails, check the gateway's running state and whether the client can reach the configured address and port. In the official Docker image, s6-overlay supervises the gateway, so a running container can coexist with a gateway that is repeatedly restarting. Check the gateway output in docker logs and look for recurring startup errors.
When health works and chat fails, check where the error originates. A rejection at the Hermes gateway calls for checking the client credential and requested route. An upstream provider error in the gateway logs calls for checking the configured provider, model, or quota. Once a direct request returns a valid reply from the frontend's network, retry through the frontend. If only the frontend fails, compare its base URL, credential settings, and streaming mode with the working request.
Hermes Docker Setup | Hermes Agent