README.md

---
title: Hermes Agent API
emoji: ⚕
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
license: mit
---

# Hermes Agent API

A deployment-agnostic HTTP API around the [Hermes agent](https://github.com/morongosteve/hermes-agent).
The image clones the agent at build time, installs it, and serves `api_server.py`.

## Endpoints

- `GET /health` — liveness probe (always 200 once up)
- `GET /` — JSON service/route description
- `POST /v1/agent` — native Hermes turn
- `POST /v1/chat/completions` — OpenAI-compatible chat completions (non-streaming)

## Configuration (Space secrets / variables)

Set these under **Settings → Variables and secrets**:

- `OPENROUTER_API_KEY` *(secret, required for the agent to answer)* — upstream model key
- `HERMES_MODEL` *(optional)* — default model (default `anthropic/claude-opus-4.6`)
- `HERMES_SERVER_API_KEY` *(optional)* — if set, callers must send it as
  `Authorization: Bearer <key>` or `X-API-Key`
- `HERMES_ENABLED_TOOLSETS` / `HERMES_DISABLED_TOOLSETS` *(optional)*

The API comes up healthy immediately; the agent endpoints start answering once
`OPENROUTER_API_KEY` is set.

## Example

```bash
curl -s https://shootstuff-hermes-agent-api.hf.space/health

curl -s -X POST https://shootstuff-hermes-agent-api.hf.space/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"hello"}]}'
```