Hermes Agent API: Setup Guide, Endpoint Reference, and Managed Hosting

What the Hermes Agent API is, how the OpenAI-compatible server works, and why Agent 37 hosts it from $3.99/mo vs DIY.

Published on

•

Hermes Agent API: Setup Guide, Endpoint Reference, and Managed Hosting
Do not index
The Hermes Agent API is an OpenAI-compatible HTTP server built into Hermes Agent that lets any frontend call the agent over a REST interface. Enable it with two environment variables, start the gateway, and clients can send Chat Completions requests to /v1 with bearer-token auth. This guide covers every step: enabling the server, the full endpoint reference, provider key setup, free local options, Python and curl examples, frontend connections, and troubleshooting.
If you want a persistent host for the API server without managing Docker, TLS, or uptime yourself, we built Agent 37 specifically for that. Managed Hermes instances start at $3.99/mo (as of October 2026), run around the clock, and come with a browser terminal, file browser, and live Linux desktop so you never need to SSH in from a terminal app.

Does Hermes Agent have an API, and is it OpenAI-compatible?

Yes, Hermes Agent ships a built-in HTTP API server that is fully OpenAI-compatible. Once enabled, any client that speaks the OpenAI Chat Completions or Responses protocol can use Hermes as a tool-equipped backend without any custom SDK. The API server exposes Chat Completions, Responses, Models, and health endpoints at the same paths the OpenAI API uses.
The default local bind address is http://127.0.0.1:8642. You can change the port and bind address via environment variables before starting the gateway. Frontends like Open WebUI, LobeChat, and LibreChat need nothing beyond a base URL and the bearer token.
The API server is separate from the inference provider API key Hermes uses to call an LLM. That distinction matters and causes most of the confusion searchers report, so we cover both clearly below.

[Book a 30 minute call with Agent 37](https://cal.com/vishnukool/30min)

What are the two different API keys in Hermes Agent?

There are two separate keys and conflating them is the most common source of errors. The provider API key is the credential Hermes sends upstream to an LLM provider such as Anthropic, OpenAI, OpenRouter, or DeepSeek so that Hermes can generate responses. The API server key is the bearer token clients must include when calling the HTTP endpoints Hermes exposes. These are completely independent, and both are required for a working deployment.
Think of it this way: the provider key is Hermes talking to the model, and the API server key is your frontend talking to Hermes. Setting API_SERVER_KEY does not configure your LLM provider, and setting your Anthropic key does not protect your API server.
Key
Environment variable
Who uses it
Where it goes
LLM provider key
Varies by provider (e.g. ANTHROPIC_API_KEY)
Hermes, to call the model
Sent upstream to the provider
API server key
API_SERVER_KEY
Your frontend or client app
Sent as Authorization: Bearer ... to Hermes

How do I enable the Hermes Agent API server?

Enabling the API server requires setting two environment variables and then starting the gateway process. Set API_SERVER_ENABLED=true so the gateway activates the HTTP listener, and set API_SERVER_KEY to a strong random string that clients will send as a bearer token. Without API_SERVER_KEY set to a non-empty value, the server will reject all requests or refuse to start depending on the Hermes version.
# Set in your shell, .env file, or container environment
export API_SERVER_ENABLED=true
export API_SERVER_KEY=your-strong-random-key-here

# Optional: change the port (default 8642)
export API_SERVER_PORT=8642

# Optional: bind to all interfaces for remote access
export API_SERVER_HOST=0.0.0.0

# Start the API gateway
hermes gateway
When the gateway starts successfully you will see output confirming the server is listening. The default bind is 127.0.0.1:8642, which means the server is only reachable from the same machine. If you are running Hermes inside Docker and connecting from another container, see the Docker networking section below.
Security note: binding to 0.0.0.0 exposes the API server to all network interfaces. The API server includes terminal and file tools, so a leaked API_SERVER_KEY gives an attacker direct access to the host filesystem. Always use a strong random key, rotate it if it is ever exposed, and do not bind to 0.0.0.0 on a machine with a public IP unless you have a reverse proxy with TLS in front.

What endpoints does the Hermes Agent API expose?

Hermes exposes three groups of endpoints: the core OpenAI-compatible inference endpoints, the Runs API for streaming and long-running work, and the Jobs API for scheduled background tasks. The base URL for all of them is http://HOST:8642/v1 unless you changed the port.

Core OpenAI-compatible endpoints

Endpoint
Method
Purpose
/v1/chat/completions
POST
Standard Chat Completions. Stateless per request via the messages array. Supports stream: true and Hermes hermes.tool.progress events.
/v1/responses
POST
Responses-style API with server-side conversation state via previous_response_id or named conversation keys.
/v1/models
GET
Returns the list of models Hermes can route to. Used by frontends to populate the model dropdown.
/health
GET
Returns 200 OK when the gateway is up.
/health/detailed
GET
Returns component-level health status including the LLM provider connection.

Runs API (streaming and long-running tasks)

The Runs API is for work that takes longer than a single HTTP round trip or where you want to stream progress events to a UI.
Endpoint
Method
Purpose
/v1/runs
POST
Start a run. Returns a run_id immediately.
/v1/runs/{run_id}/events
GET
Stream Server-Sent Events for a run. Each event includes type, content, and tool activity.
/v1/runs/{run_id}/approval
POST
Resume a paused run that requires human approval.
/v1/runs/{run_id}/clarify
POST
Send a clarification response to a paused run.
/v1/runs/{run_id}/stop
POST
Terminate a running job.

Jobs API (scheduled background tasks)

The Jobs API lets you schedule recurring or future-triggered tasks without keeping an HTTP connection open. This is the surface to use for morning briefings, inbox watchers, price monitors, and similar autonomous workflows.
Endpoint
Method
Purpose
/v1/jobs
POST
Create a scheduled or recurring job with a cron expression or trigger condition.
/v1/jobs
GET
List all jobs in the current session.
/v1/jobs/{job_id}
GET
Get the status and last result of a specific job.
/v1/jobs/{job_id}
DELETE
Cancel and remove a job.
For the full endpoint reference including request body schemas, see the Hermes Agent documentation at NousResearch.

How do I set up an LLM provider for Hermes Agent?

Hermes needs a provider key to call a model. Set the appropriate environment variable before starting the gateway. Hermes supports multiple providers and you can switch models with the /model command inside a session or by passing the model field in a Chat Completions request.
# OpenRouter (routes to many models including Claude and GPT-4o)
export OPENROUTER_API_KEY=sk-or-...

# Anthropic directly
export ANTHROPIC_API_KEY=sk-ant-...

# DeepSeek
export DEEPSEEK_API_KEY=sk-...

# OpenAI
export OPENAI_API_KEY=sk-...

# Nous Portal
export NOUS_API_KEY=...

hermes gateway
To switch models per-request, include the model field in your Chat Completions body:
{
  "model": "anthropic/claude-3-5-sonnet",
  "messages": [{"role": "user", "content": "Hello"}]
}
OpenRouter is convenient for switching between providers without changing environment variables, because it routes by model string. DeepSeek offers competitive per-token pricing. If cost control matters, read the free local model section below.

Provider cost context

Real users report meaningful surprise bills when running agentic workloads. An agent that calls a model many times per task can accumulate tokens faster than a simple chatbot. One commonly cited example in community discussions involves accumulating over $50 in provider spend within a week on Claude or GPT-4o for a moderately active agent. To control costs: use a cheaper provider for development (DeepSeek or Nous Portal), set hard spending limits in your provider dashboard, or run a local model entirely free.

Is there a free way to run Hermes Agent without a paid API key?

Yes. Hermes supports any OpenAI-compatible base URL, which means you can point it at a locally running model server instead of a paid cloud provider. Ollama, vLLM, llama.cpp with its HTTP server, and LM Studio all expose an OpenAI-compatible API at http://localhost:11434/v1 (Ollama default) or a similar local address. No provider key is needed and there are no per-token charges.
# Run Ollama locally with a model
ollama pull llama3.2

# Point Hermes at the local Ollama server
export OPENAI_API_BASE=http://localhost:11434/v1
export OPENAI_API_KEY=ollama  # Ollama ignores this but the field is required

export API_SERVER_ENABLED=true
export API_SERVER_KEY=local-dev-key
hermes gateway
The tradeoff is that local models run on your own hardware and are typically slower and less capable than frontier models. For development, testing, and privacy-sensitive tasks they are a strong choice. For production agent workloads that need reliable tool use, a frontier model from a paid provider usually performs better.
If you want persistent hosting without per-token cost uncertainty, our Hermes agent hosting uses a bring-your-own-key model so your API keys go directly to the provider and we never see them.

How do I call the Hermes Agent API from Python or curl?

Because the Hermes API server is OpenAI-compatible, you can use the official openai Python SDK pointed at your Hermes instance instead of at OpenAI. Change base_url to your Hermes gateway address and set api_key to your API_SERVER_KEY.

curl example (Chat Completions)

curl http://127.0.0.1:8642/v1/chat/completions \
  -H "Authorization: Bearer your-api-server-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hermes",
    "messages": [{"role": "user", "content": "Summarise the top news today"}],
    "stream": false
  }'

Python example (openai SDK)

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8642/v1",
    api_key="your-api-server-key",
)

response = client.chat.completions.create(
    model="hermes",
    messages=[{"role": "user", "content": "What files are in my home directory?"}],
)

print(response.choices[0].message.content)

Python example with streaming

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8642/v1",
    api_key="your-api-server-key",
)

with client.chat.completions.stream(
    model="hermes",
    messages=[{"role": "user", "content": "Search the web for the latest AI news and summarise it"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
Streaming responses from Hermes include hermes.tool.progress events that carry tool activity (search queries, file reads, terminal commands) so a UI can show what the agent is doing in real time. See the Agent 37 streaming docs for how to handle Server-Sent Events from a hosted instance.

Runs API example (long-running task)

# Start a run
curl http://127.0.0.1:8642/v1/runs \
  -H "Authorization: Bearer your-api-server-key" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Monitor the inbox and draft replies to support emails every hour"}'

# Response includes run_id
# Stream events
curl -N http://127.0.0.1:8642/v1/runs/run_abc123/events \
  -H "Authorization: Bearer your-api-server-key"

How do I connect Open WebUI or another frontend to Hermes Agent?

Any frontend that accepts a custom OpenAI base URL works with the Hermes API server. Open WebUI is the most commonly used option. Set the OpenAI API URL to your Hermes gateway address and the API key to your API_SERVER_KEY.

Open WebUI via Docker Compose

When Hermes and Open WebUI run in separate Docker containers on the same host, localhost inside the Open WebUI container does not resolve to the Hermes container. Use host.docker.internal instead (works on Docker Desktop for Mac and Windows) or the container name if they share a Docker network.
# docker-compose.yml
services:
  hermes:
    image: nousresearch/hermes-agent:latest
    environment:
      - API_SERVER_ENABLED=true
      - API_SERVER_KEY=your-api-server-key
      - ANTHROPIC_API_KEY=sk-ant-...
    ports:
      - "8642:8642"

  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    environment:
      - OPENAI_API_BASE_URL=http://hermes:8642/v1
      - OPENAI_API_KEY=your-api-server-key
    ports:
      - "3000:8080"
    depends_on:
      - hermes
With this compose file, Open WebUI reaches Hermes via the hermes service name on the shared Docker network, not via localhost.
If Hermes is running on a remote machine or on Agent 37, replace http://hermes:8642/v1 with https://your-instance-id.agent37.app/v1 and set the key accordingly. The instance and preview URL docs explain how instance subdomains are constructed.

How do I change or rotate the Hermes Agent API key?

To rotate the API server key, update API_SERVER_KEY in your environment and restart hermes gateway. There is no hot-reload, so existing connections will drop and reconnect with the new key. Update your frontend configuration at the same time. For the LLM provider key, update the relevant environment variable (for example ANTHROPIC_API_KEY) and restart the gateway. Provider keys can also be rotated in your provider's dashboard independently of Hermes.

[Book a 30 minute call with Agent 37](https://cal.com/vishnukool/30min)

How do I run Hermes Agent API persistently without managing a server?

Running hermes gateway on a laptop or a development machine means the API server stops when the machine sleeps, reboots, or loses connectivity. For any production use, a morning briefing agent, an inbox watcher, or a client-facing backend, you need a machine that stays on continuously.
We run persistent Hermes agent hosting starting at $3.99/mo (as of October 2026). Each instance is an isolated Linux container. Files, sessions, and memory persist between tasks. You get a browser-based terminal, file browser, and live Linux desktop via noVNC so you can manage the instance without installing anything locally. API keys go directly to providers (Anthropic, OpenAI, OpenRouter) and we never see them.
Agencies and consultants who want to provision one Hermes instance per client can do that through the Agent 37 Cloud API. One POST to /v1/instances provisions a new isolated sandbox. The white-label dashboard is a full multi-tenant agent app built on that API.
notion image

Self-host vs Agent 37 for the Hermes Agent API server

notion image
Self-host / DIY VPS
Agent 37
Enable API server
You set env vars and run gateway
Managed, pre-configured
Persistence
You ensure uptime
Always-on, never sleeps
Isolation
You design per-tenant logic
Per-instance isolation built in
TLS and networking
You configure reverse proxy
Handled at platform level
Updates and patches
You apply them
Platform-managed automatically
Debug access
SSH from your terminal
Browser terminal, file browser, live desktop
API provisioning
Not applicable
POST /v1/instances for white-label deployments
Entry price
Compute cost plus your time
From $3.99/mo
For a broader look at hosting options for personal use, see our personal AI agent hosting page which covers Hermes, OpenClaw, Claude Code, and Codex side by side.

What does Hermes Agent API hosting cost?

Hosting cost and model cost are separate line items. Agent 37 uses a bring-your-own-key model, so you pay us for compute and pay your LLM provider directly for tokens. No markup on model spend.
notion image
Plan
Price (as of October 2026)
Best fit
Basic
$3.99/mo
First Hermes instance, personal use, pilots
Plus
$9.99/mo
Light production, bundled free model access
Pro
$29.99/mo
Client-facing API, Chromium, stronger support
Max
$99.99/mo
Teams, roles, onboarding, agency operations
Cloud API provisioning (white-label, per-instance billing) starts around $4.76/mo per instance metered by the minute. Full details are on the Agent 37 pricing page.
Provider spend varies by model and usage. As a reference point, Claude 3.5 Sonnet on Anthropic's direct API costs $3 per million input tokens and $15 per million output tokens as of mid-2026 according to Anthropic's published pricing. For development and testing, DeepSeek and local Ollama models reduce provider spend to near zero.

How do I troubleshoot common Hermes Agent API errors?

Most errors fall into four categories: the server never starts, authentication fails, the model list is empty, or Docker networking blocks the connection. Work through this list in order.

Connection refused

Symptom: curl: (7) Failed to connect to 127.0.0.1 port 8642: Connection refused
Causes and fixes:
  • API_SERVER_ENABLED is not set to true. Verify with echo $API_SERVER_ENABLED.
  • hermes gateway is not running or exited with an error. Check the process and its stdout for error messages.
  • You are connecting from a different container and using localhost. Use host.docker.internal (Docker Desktop) or the service name (Docker Compose shared network).
  • The port was changed via API_SERVER_PORT. Confirm the port in the gateway startup output.

Invalid API key / 401 Unauthorized

Symptom: {"error": {"message": "Invalid API key", "type": "invalid_request_error"}}
Causes and fixes:
  • The Authorization header is missing or malformed. It must be Authorization: Bearer YOUR_API_SERVER_KEY.
  • API_SERVER_KEY was not exported before starting the gateway. Restart with the variable set.
  • The key in your frontend does not match API_SERVER_KEY. Copy-paste the exact value.
  • You are sending your LLM provider key as the server key. These are different. See the two-key section above.

No models in dropdown

Symptom: Open WebUI or another frontend shows an empty model list.
Causes and fixes:
  • GET /v1/models is returning an empty array because no provider key is configured. Hermes cannot return available models if it cannot reach the provider.
  • Check /health/detailed to see which components report unhealthy.
  • Confirm your provider environment variable is set and the value is valid by calling the provider's own API directly.
  • If using Ollama, confirm ollama list returns models on the host running Ollama.

Slow responses or timeouts

Symptom: Requests hang for 30 seconds or longer before returning, or return a timeout error.
Causes and fixes:
  • The provider is rate-limiting your key. Check your provider dashboard for quota errors.
  • You are using a local model (Ollama, llama.cpp) on hardware that is too slow for the model size. Try a smaller quantized model.
  • The agent is running a multi-step tool chain (web search, file operations) and the progress is not visible because streaming is off. Add stream: true to see incremental output.
  • Network latency between the API server and the provider. Hosting Hermes in the same region as your provider's data center reduces round-trip time.

Provider API key errors

Symptom: {"error": "Authentication error: invalid API key"} or similar in the gateway logs.
Causes and fixes:
  • This error comes from the provider, not from Hermes. Your LLM provider key (Anthropic, OpenAI, etc.) is wrong or expired.
  • Regenerate the key in the provider's dashboard and update the environment variable, then restart hermes gateway.
  • Do not confuse this with the Hermes API_SERVER_KEY error. Provider auth errors appear in gateway logs; server key errors appear in HTTP responses to clients.
For issues specific to Agent 37-hosted instances, the Agent 37 quickstart and REST API reference cover instance-level diagnostics.

Quick-start checklist: Hermes Agent API in five steps

  1. Set API_SERVER_ENABLED=true and API_SERVER_KEY=<strong-random-string> in your environment.
  1. Set your LLM provider key (ANTHROPIC_API_KEY, OPENAI_API_KEY, or equivalent).
  1. Run hermes gateway and confirm the startup log shows the server listening on port 8642.
  1. Test with curl http://127.0.0.1:8642/health and confirm 200 OK.
  1. Point your frontend (Open WebUI, Python openai client, or your own app) at http://HOST:8642/v1 with the API_SERVER_KEY as the bearer token.
For a managed environment where steps 1 through 3 are handled for you, deploy a Hermes instance on Agent 37 and skip the gateway setup entirely.

FAQ

Does Hermes Agent require an API key, and which key does it need?
Hermes Agent requires two separate keys for a fully working deployment. The LLM provider key (such as an Anthropic or OpenAI key) is what Hermes uses to call a language model and generate responses. The API_SERVER_KEY is what your frontend or client app sends to authenticate against the Hermes HTTP server. Both are required; they serve completely different purposes and are set separately.
How do I change or rotate the Hermes Agent API key?
To rotate the API server key, update the API_SERVER_KEY environment variable and restart hermes gateway. Active connections will drop and must reconnect with the new key, so update your frontend configuration at the same time. To rotate the LLM provider key, update the provider-specific environment variable (for example ANTHROPIC_API_KEY) and restart the gateway. You can also revoke and reissue provider keys from within the provider's own dashboard without touching Hermes at all.
Is there a free API for Hermes Agent?
Yes, in two senses. The Hermes API server itself is free software you can run locally. For the LLM provider that Hermes calls to generate responses, you can point Hermes at a locally running model (Ollama, vLLM, llama.cpp, or LM Studio) with no provider account and no per-token cost. If you prefer a hosted provider, some offer free tiers with rate limits. The only cost on Agent 37 is the compute hosting fee, starting at $3.99/mo, and whatever you pay your provider directly.
Is there a web interface for Hermes Agent, and how do I connect it?
Hermes Agent does not ship a standalone web UI, but it connects to any OpenAI-compatible frontend. Open WebUI is the most widely used option. Set the OpenAI API URL in Open WebUI's settings to http://HOST:8642/v1 and the API key to your API_SERVER_KEY. If you are running both in Docker, use the service name or host.docker.internal rather than localhost as the hostname. Hermes Desktop is the official desktop client. Agent 37 also provides a browser-based chat interface on every hosted instance. See the personal AI agent hosting page for a live example.
How do I run Hermes Agent for free on a local model?
Install Ollama, pull a model with ollama pull llama3.2, set OPENAI_API_BASE=http://localhost:11434/v1 and OPENAI_API_KEY=ollama before starting hermes gateway. Hermes will route all inference requests to the local Ollama server with no provider account needed. vLLM and llama.cpp with the --server flag work the same way. The tradeoff is that local models are slower and typically less capable at tool use than frontier models, but the cost is zero beyond electricity and hardware.

Sources: [Hermes Agent API server documentation](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server) (NousResearch); [Anthropic API pricing](https://www.anthropic.com/pricing) (Anthropic, 2026); [OpenAI Chat Completions API reference](https://platform.openai.com/docs/api-reference/chat) (OpenAI); [Ollama documentation](https://ollama.com/library) (Ollama); [Open WebUI documentation](https://docs.openwebui.com/) (Open WebUI project).
[Book a 30 minute call with Agent 37](https://cal.com/vishnukool/30min)