API server: use Hermes from any OpenAI-compatible client

What API server is for

The API server runs inside the gateway and serves Hermes over HTTP with OpenAI-style endpoints such as /v1/chat/completions, /v1/responses and /v1/models. Any frontend or script that can talk to the OpenAI API, such as Open WebUI, can then use your agent with its tools, skills and memory. Further endpoints cover runs, sessions and scheduled jobs. By default it listens only on localhost port 8642 and requires a bearer token. For several users, the docs suggest a separate profile per user, each with its own port and key. The API endpoint runs a server-side Hermes agent with that host and profile's tools, memory and skills. Files, terminal, browser and local MCP work run on the API-server host, not on the frontend laptop.

What you need

• A configured Hermes install with a model provider
• A fresh non-placeholder API_SERVER_KEY of at least 16 characters, required even on localhost. Generate one with openssl rand -hex 32; use the same value in the client. Do not copy your-secret-key or other short example keys.

Set it up

1. 1

   Add API_SERVER_ENABLED=true and API_SERVER_KEY=<your key> to ~/.hermes/.env

2. 2

   Optionally set API_SERVER_PORT, API_SERVER_HOST or API_SERVER_CORS_ORIGINS for browser access

3. 3

   Start the gateway with hermes gateway and point your client at http://localhost:8642/v1

Check it works

• The gateway startup log shows the API server listening on http://127.0.0.1:8642
• GET /health returns {"status": "ok"} without authentication
• POST a test message to /v1/chat/completions with your bearer token and model hermes-agent

Limits and failure points

• No file uploads: only inline images as http(s) or data:image URLs are accepted
• The default cap is 10 concurrent runs, after which requests get HTTP 429
• Stored Responses history is capped at 100. Bare model names without provider are ignored by default only on Chat Completions/Responses unless direct_model_requests is true; explicit provider and native Runs/session-chat endpoints honor requested models subject to session/route precedence.

Messaging setup

All messaging platforms

• How to set up Hermes Agent with Open WebUI and the API server

Spotted something wrong or out of date? Tell us on X at @HermesWatcher↗ (opens in a new tab) and we will fix it.