# Hermes Agent API Server: OpenAI-Compatible Endpoints and Setup

The Hermes Agent API server turns your local agent into an OpenAI-compatible HTTP endpoint that any chat frontend can connect to. This guide covers every endpoint, SSE streaming with tool progress events, the Jobs API for scheduled work, multi-user profiles, and connecting frontends like Open WebUI and LobeChat.

Source: https://fast.io/resources/hermes-agent-api-server-guide/
Last reviewed: 2026-05-16

## What the API Server Does

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.

## How to Enable and Configure the API Server

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

```bash
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:

```bash
hermes gateway
```

Verify it's running:

```bash
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.

## Core Endpoints Reference

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.

```bash
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

| Endpoint | Method | Purpose |
|----------|--------|---------|
| /v1/chat/completions | POST | Stateless chat, OpenAI-compatible |
| /v1/responses | POST | Server-side conversation state |
| /v1/runs | POST | Start long-running agent task |
| /v1/runs/{id}/events | GET | SSE stream of run progress |
| /v1/models | GET | List available agent profiles |
| /health | GET | Basic health check |

## SSE Streaming and Tool Progress Events

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.

## Jobs API for Scheduled Automations

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 WebSocket events feed or activity polling 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.

## Multi-User Profiles and Isolation

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:

```bash
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:

```bash
### 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 14-day Business Trial](https://fast.io/pricing/) (credit card required) provides cloud 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.

## How to Connect Frontends Like Open WebUI and LobeChat

**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`:

```bash
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**

```python
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.

## Frequently asked questions

### Does Hermes Agent have an API?

Yes. Hermes Agent includes a built-in API server that exposes OpenAI-compatible HTTP endpoints. Enable it by setting API_SERVER_ENABLED=true in your .env file and starting the gateway. It supports /v1/chat/completions, /v1/responses, a Runs API for long-form tasks, and a Jobs API for scheduled automations.

### Is Hermes Agent OpenAI compatible?

The API server implements the OpenAI Chat Completions format, the Responses API with server-side state, and SSE streaming. Any frontend or SDK that can connect to the OpenAI API works with Hermes Agent by pointing the base URL to localhost:8642/v1. Tested frontends include Open WebUI, LobeChat, LibreChat, AnythingLLM, NextChat, and the OpenAI Python SDK.

### How do I connect Open WebUI to Hermes Agent?

Set API_SERVER_ENABLED=true and API_SERVER_KEY in your Hermes .env file, then run hermes gateway. In Open WebUI, go to Admin Settings, Connections, OpenAI, and add a connection with URL http://localhost:8642/v1 and your API key. For Docker deployments, use host.docker.internal instead of localhost.

### Can multiple users share one Hermes Agent?

Yes, through profiles. Each profile (created with hermes profile create) gets isolated configuration, memory, skills, and API keys. Run each profile on a different port, and the /v1/models endpoint advertises each profile as a separate model. Frontends see multiple agents in the model dropdown.

### What is the hermes.tool.progress SSE event?

It is a custom Server-Sent Event emitted during streaming that shows which tool the agent is executing in real time. Frontends that understand it render inline progress indicators. Frontends that don't ignore it. These events never appear in the persisted conversation history.

### How do I schedule recurring tasks with the Hermes Agent API?

Use the Jobs API. POST to /api/jobs with a cron schedule and task definition. The agent executes the job on schedule with full access to its tools and memory. You can pause, resume, or trigger jobs manually through dedicated endpoints.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.