Hermes Agent API Server: OpenAI-Compatible Endpoints and Setup

Nous Research Hermes Agent is an open-source AI agent with persistent memory, terminal access, file operations, and extensible skills. By default you interact with it through the terminal. The API server changes that: flip one environment variable and your agent becomes an HTTP service that speaks the OpenAI protocol.

Any application that can talk to the OpenAI API can now talk to your Hermes Agent. That includes Open WebUI (126k+ GitHub stars), LobeChat, LibreChat, AnythingLLM, NextChat, ChatBox, Jan, big-AGI, and the OpenAI Python SDK with a custom base_url. The agent keeps all its capabilities (tools, memory, skills) while serving responses over HTTP.

The server runs on port 8642 by default and supports four endpoint families: Chat Completions, Responses, Runs, and Jobs. Each serves a different interaction pattern, from simple stateless chat to long-running background automations.

Configuration lives in your Hermes Agent .env file (typically at ~/.hermes/.env). Add these environment variables:

API_SERVER_ENABLED=true
API_SERVER_PORT=8642
API_SERVER_HOST=127.0.0.1
API_SERVER_KEY=your-secret-key-here

API_SERVER_KEY sets the bearer token for authentication. When the server binds to a non-loopback address (anything other than 127.0.0.1), authentication becomes mandatory. For local-only access you can skip the key, but setting one is good practice regardless.

Start the gateway:

hermes gateway

Verify it's running:

curl http://localhost:8642/health

You should get {"status": "ok"} back. The detailed health endpoint at /health/detailed returns session and resource metrics if you need diagnostics.

Two additional variables handle CORS for browser-based frontends:

• API_SERVER_CORS_ORIGINS accepts a comma-separated allowlist of origins (e.g., http://localhost:3000,https://chat.example.com)
• When enabled, preflight responses cache for 10 minutes

The server also accepts an Idempotency-Key header for 5-minute response deduplication, which helps frontends that retry on network hiccups.

The API server exposes four endpoint families. Here is the complete surface:

Chat Completions (POST /v1/chat/completions)

The standard OpenAI format. Send a messages array, get a chat.completion response with token usage. Supports inline images via image_url objects (HTTP/HTTPS URLs and data:image/ base64 URIs). Set "stream": true for Server-Sent Events.

curl http://localhost:8642/v1/chat/completions \
  -H "Authorization: Bearer your-secret-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hermes-agent",
    "messages": [{"role": "user", "content": "List files in ~/projects"}],
    "stream": true
  }'

Responses API (POST /v1/responses)

Server-side conversation storage via SQLite. Chain turns with previous_response_id so the client doesn't need to resend the full history. Supports named sessions via a conversation parameter and returns structured function_call and function_call_output items for tool rendering.

Runs API

For long-form agent executions where you want progress updates:

• POST /v1/runs starts execution, returns a run_id
• GET /v1/runs/{run_id} polls run state
• GET /v1/runs/{run_id}/events streams SSE progress events
• POST /v1/runs/{run_id}/stop interrupts an active run

Model Discovery and Health

• GET /v1/models lists available agents (profile names appear as model IDs)
• GET /v1/capabilities returns machine-readable feature availability
• GET /health and GET /v1/health return status OK
• GET /health/detailed includes session and resource metrics

Persist your Hermes Agent's files across sessions and machines

Fastio gives your agent 50GB of free persistent storage with MCP-native access. No credit card, no expiration. Read and write files from any Hermes profile through one endpoint.

Start 14-Day Trial

Streaming is where the Hermes API server diverges from vanilla OpenAI in a useful way. Beyond standard chat.completion.chunk events, the server emits custom hermes.tool.progress events that show what tools the agent is using in real time.

When the agent decides to run a terminal command, search the web, or read a file, the stream emits a progress event before the tool executes. Frontends that understand this event can render inline indicators (like the progress badges you see in Open WebUI). Frontends that don't understand the event ignore it and render the text chunks as normal.

A typical streaming session looks like this: the client sends a request with "stream": true, receives an initial chat.completion.chunk with role information, then sees hermes.tool.progress events as the agent works (showing tool name and status), followed by content chunks as the agent generates its response, and finally a [DONE] sentinel. The progress events carry metadata about which tool is active without including tool output in the stream, keeping bandwidth efficient.

The Responses API streaming follows the OpenAI Responses spec: response.created, response.output_text.delta, response.output_item.added, response.output_item.done, and response.completed. Tool calls appear as function_call and function_call_output items, giving frontends enough structure to render tool UIs. The response.output_item.added event fires before tool execution begins, so a frontend can display a spinner or label before results arrive.

The Runs API streaming endpoint (/v1/runs/{run_id}/events) provides tool-call progress, token deltas, and lifecycle events. It's designed for dashboard-style UIs that need reconnection support without losing state. If a client disconnects and reconnects, it can resume the stream from where it left off because the Runs API retains terminal status.

This layered approach means simple frontends get basic streaming, while purpose-built UIs get full tool visibility. The hermes.tool.progress events never pollute the persisted assistant message, so conversation history stays clean regardless of how much tool activity happened during generation.

One practical consideration: system prompts from the frontend layer on top of the core agent system prompt. If your frontend sends a system message (Chat Completions) or sets instructions (Responses API), those get appended to the agent's existing prompt. Tools, memory, and skills remain active regardless of what the frontend sends.

The Jobs API handles recurring background work. Unlike the Runs API (which is for one-shot executions you want to monitor), Jobs are cron-style automations that the agent runs on a schedule.

Full CRUD surface:

GET    /api/jobs              List all jobs
POST   /api/jobs              Create a scheduled job
GET    /api/jobs/{id}         Fetch job definition
PATCH  /api/jobs/{id}         Update job parameters
DELETE /api/jobs/{id}         Remove a job
POST   /api/jobs/{id}/pause   Suspend scheduling
POST   /api/jobs/{id}/resume  Resume scheduling
POST   /api/jobs/{id}/run     Trigger immediate execution

Jobs run within the agent's full context, meaning they have access to tools, memory, and skills. A common pattern: schedule a job to check a data source every hour, write results to a workspace, and notify you through a messaging gateway when something changes.

The /run endpoint lets you trigger a job out of schedule for testing without modifying the cron definition. Pausing preserves the job's configuration and history while stopping future executions.

For teams running Hermes Agent as persistent infrastructure, the Jobs API turns the agent into a lightweight automation server. Combined with Fastio's webhook system for reactive triggers, you can build workflows where the agent both polls on schedule and responds to external events by writing results to a shared workspace.

A practical example: create a job that monitors a project folder for new files every 30 minutes, summarizes any additions, and posts the summary to a Telegram channel through the messaging gateway. The job definition specifies the schedule, the prompt, and optionally which tools the job is allowed to use. Each execution creates a run that you can inspect after the fact through the Runs API.

Note the URL prefix difference: Jobs use /api/jobs while the OpenAI-compatible endpoints use /v1/. This separation keeps the standard-compliant surface clean while giving Hermes-specific features their own namespace.

Hermes Agent profiles let multiple users (or multiple personas) share one machine without cross-contamination. Each profile gets its own configuration, API keys, memory, skills, and conversation history.

Create a profile:

hermes profile create work

Three isolation levels are available:

• Fresh (default): Blank profile with default subdirectories
• Clone (--clone): Copies core identity files (config.yaml, .env, SOUL.md)
• Clone-All (--clone-all): Full recursive copy, minus runtime files like gateway.pid

Profiles are stored under ~/.hermes/profiles/<name>/. Each profile can run its own API server on a different port with a different key:

### In ~/.hermes/profiles/work/.env
API_SERVER_ENABLED=true
API_SERVER_PORT=8643
API_SERVER_KEY=work-team-key

### In ~/.hermes/profiles/personal/.env
API_SERVER_ENABLED=true
API_SERVER_PORT=8644
API_SERVER_KEY=personal-key

The API server advertises profile names as model IDs in /v1/models responses. When a frontend connects, it sees each profile as a separate "model" it can select. This means Open WebUI users can switch between your work agent and personal agent from the same model dropdown.

For teams, profiles provide per-person isolation on a shared server. Each person's agent has private memory and credentials, while the underlying compute and skills remain shared. Profile packages (SOUL, config, skills, cron jobs, MCP connections) can be versioned in git and installed on other machines, though credentials and memories stay local.

When agents need persistent file storage that outlives a session or survives a machine swap, a shared workspace fills that gap. Fastio's Business Trial provides 50GB of storage with MCP-native access, so any Hermes profile can read and write files through the Fastio MCP server at /storage-for-agents/ without managing infrastructure.

Open WebUI

Open WebUI has first-party Hermes Agent documentation. The setup takes under two minutes:

1. Ensure API_SERVER_ENABLED=true and API_SERVER_KEY are set in your .env
2. Run hermes gateway to start the API server
3. In Open WebUI, go to Admin Settings, then Connections, then OpenAI
4. Click Add Connection
5. Set the URL to http://localhost:8642/v1 (the /v1 suffix is required)
6. Enter your API key
7. Click the checkmark to verify, then Save

For Docker deployments, replace localhost with host.docker.internal:

OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1
OPENAI_API_KEY=your-secret-key

On Linux without Docker Desktop, add --add-host=host.docker.internal:host-gateway to your Docker run command.

LobeChat

Open Settings, then Language Model, then OpenAI. Set the custom endpoint to http://localhost:8642/v1 and enter your API key. Click "Get Model List" to fetch available profiles. LobeChat's OpenAI provider works with any OpenAI-compatible backend.

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8642/v1",
    api_key="your-secret-key"
)

response = client.chat.completions.create(
    model="hermes-agent",
    messages=[{"role": "user", "content": "Check disk usage"}],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

LibreChat

LibreChat supports custom endpoints natively. In your LibreChat configuration, add an endpoint pointing to http://localhost:8642/v1 with your API key. The Chat Completions endpoint works out of the box. LibreChat's multi-model UI lets you switch between Hermes Agent and other providers in the same conversation.

Troubleshooting common issues:

• Missing /v1 suffix in the URL is the most frequent connection problem
• API keys must match exactly between your .env and the frontend configuration
• The gateway must be running (hermes gateway) for the API server to accept connections
• Use curl http://localhost:8642/health to confirm the server is reachable before debugging frontend settings
• If you changed the port via API_SERVER_PORT, update all frontend URLs to match
• For remote access (not localhost), ensure API_SERVER_KEY is set and API_SERVER_HOST is bound to 0.0.0.0 or the appropriate interface
• The model field in requests is cosmetic on the server side. The actual LLM is configured in the agent's config.yaml, not selected by the client. The model name in /v1/models responses helps frontends display a label but doesn't control routing

Proxy mode for Docker and remote deployments:

The API server supports a GATEWAY_PROXY_URL configuration for relay setups. This is useful when the agent runs inside a Docker container and needs to proxy requests to the host, or for end-to-end encrypted relay deployments where a lightweight proxy sits between the internet and the agent process.