# API server: use Hermes from any OpenAI-compatible client

> Expose Hermes as an OpenAI-compatible HTTP endpoint so chat frontends and scripts can talk to your agent.

Canonical: https://hermeswatcher.com/tools/api-server  
Kind: Integration · Running & deploying  
Last reviewed: Oct 29, 2026  
Basis: Explained from the official Hermes Agent docs and repository (Nous Research). Steps follow the linked official sources.

## What it 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.

## Setting it up

1. Add API_SERVER_ENABLED=true and API_SERVER_KEY=<your key> to ~/.hermes/.env
2. Optionally set API_SERVER_PORT, API_SERVER_HOST or API_SERVER_CORS_ORIGINS for browser access
3. Start the gateway with `hermes gateway` and point your client at http://localhost:8642/v1

## How to 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

- 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](https://hermeswatcher.com/messaging)
- [Setup guide](https://hermeswatcher.com/learn/hermes-agent-open-webui-setup)

## Sources

- [Hermes Agent docs: API Server](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server)
- [Hermes Agent docs: Open WebUI + API Server](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/open-webui)
- [Official Hermes Agent source: website/docs/user-guide/messaging/open-webui.md](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/open-webui.md#L21-L29)
- [Official Hermes Agent source: website/docs/user-guide/features/api-server.md](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/features/api-server.md#L795-L817)
- [Official Hermes Agent source: website/docs/user-guide/features/api-server.md](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/features/api-server.md#L393-L438)
- [Official Hermes Agent source: website/docs/user-guide/features/api-server.md](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/features/api-server.md#L941-L947)
- [Official Hermes Agent source: gateway/platforms/api_server.py](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/platforms/api_server.py#L3908-L3934)

---

HermesWatcher is an independent guide. It is not affiliated with or endorsed by Nous Research. The [official Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs) and [repository](https://github.com/NousResearch/hermes-agent) from Nous Research are the authority; each page here lists the official sources it was written from. If this site and the official docs disagree, trust the official docs. Index for agents: https://hermeswatcher.com/llms.txt