---
name: hermes-api-endpoint-setup
description: "Configure Hermes Agent API endpoints: built-in API server and OneAPI-compatible proxy endpoints."
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [hermes, api-server, oneapi, endpoint, configuration, proxy]
    related_skills: [hermes-agent, openai-api-testing, llm-inference]
---

# Hermes API Endpoint Setup

Two ways to expose Hermes Agent as an API: the built-in OpenAI-compatible API server, and connecting to OneAPI-compatible proxy endpoints.

## Choosing an Approach

| Need | Approach |
|------|----------|
| Expose Hermes as an API for other tools | **Built-in API Server** |
| Route Hermes through a proxy/load balancer | **OneAPI Endpoint** |
| Multiple model providers behind one endpoint | **OneAPI Endpoint** |
| Custom port with external access | **Built-in API Server** |

## Section 1: Built-in API Server

Set up Hermes Agent's built-in OpenAI-compatible API server on a custom port with external access.

**When to use:** Exposing Hermes Agent as an API server for other applications to consume.

**Key config:**
```bash
hermes config set api_server.enabled true
hermes config set api_server.port 8080
hermes api-server start
```

**Critical pitfall:** Extra nesting in the API response format. The built-in server wraps responses in an extra layer. Clients expecting standard OpenAI format may need adjustment.

**CRITICAL: Key strength.** The API server silently refuses to start if the key (in `platforms.api_server.extra.key` or `API_SERVER_KEY` env var) is < 16 chars or looks like a placeholder. Error only appears in `~/.hermes/logs/gateway.log`. Always use a strong 64-char hex key: `python3 -c "import secrets; print(secrets.token_hex(32))"`.

**See:** `references/hermes-api-server-setup.md` for full configuration, SSL, and deployment guide.

## Section 2: OneAPI Endpoint Configuration

Connect Hermes Agent to a OneAPI-compatible proxy endpoint — set base_url, api_key, default model, auxiliary models, and delegation models.

**When to use:** Routing Hermes through OneAPI, New API, or similar proxy platforms for load balancing, key management, or multi-provider aggregation.

**Key config:**
```bash
hermes config set provider.custom.base_url "https://your-oneapi-instance.com/v1"
hermes config set provider.custom.api_key "sk-*** hermes config set provider.custom.model "gpt-4o"
```

**Pitfalls:**
- OneAPI model names may differ from upstream — use the names OneAPI defines
- Rate limits are per-key in OneAPI — configure appropriate limits
- Delegation models: set separately if using agent delegation

**See:** `references/oneapi-custom-endpoint-setup.md` for full configuration and troubleshooting.