🚀 API Server de Hermes

🧠 ¿Qué es el API Server?

El API Server es un adaptador de plataforma de Hermes Agent que expone un servidor HTTP compatible con la API de OpenAI. Permite que cualquier cliente externo converse con tu agente sin depender de Telegram ni del contexto de memoria del asistente principal.

⚙️ Configuración en el VPS

api_server:
  enabled: true
  port: 8642

API_SERVER_KEY="tu-clave-secreta-aqui"   # Obligatoria. Bearer token para autenticar.
API_SERVER_HOST="127.0.0.1"              # Bind. Por defecto loopback.
API_SERVER_PORT="8642"                   # Puerto.
API_SERVER_CORS_ORIGINS=""               # Opcional. Ej: "https://tu-dominio.es"
API_SERVER_MODEL_NAME=""                 # Opcional. Sobrescribe nombre en /v1/models.

📡 Endpoints disponibles

Health y metadatos

Chat Completions / Responses

Sesiones nativas

Runs estructurados

🔐 Autenticación

Todas las rutas excepto /health requieren este header:

Authorization: Bearer tu-clave-secreta-aqui

El servidor compara el token con API_SERVER_KEY usando hmac.compare_digest() para evitar timing attacks. Si fallas, devuelve:

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

🪪 Headers especiales de Hermes

🔧 Ejemplos con curl

Health check

curl http://localhost:PUERTO/health

Listar modelos

curl -H "Authorization: Bearer tu-clave-secreta-aqui" \
  http://localhost:PUERTO/v1/models

Chat completion simple

curl -X POST http://localhost:PUERTO/v1/chat/completions \
  -H "Authorization: Bearer tu-clave-secreta-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tu-modelo",
    "messages": [
      {"role": "system", "content": "Eres un asistente creativo."},
      {"role": "user", "content": "Dame 3 ideas de nombres para un producto de automatización con IA."}
    ]
  }'

Streaming

curl -X POST http://localhost:PUERTO/v1/chat/completions \
  -H "Authorization: Bearer tu-clave-secreta-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tu-modelo",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Escribe un slogan para mi marca."}
    ]
  }'

Continuar una sesión existente

SESSION_ID="api_1234abcd"

curl -X POST http://localhost:PUERTO/v1/chat/completions \
  -H "Authorization: Bearer tu-clave-secreta-aqui" \
  -H "X-Hermes-Session-Id: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tu-modelo",
    "messages": [
      {"role": "user", "content": "Ahora dame una versión más corta."}
    ]
  }'

Crear sesión y chatear

# Crear sesión
SESSION=$(curl -X POST http://localhost:PUERTO/api/sessions \
  -H "Authorization: Bearer tu-clave-secreta-aqui" \
  -H "Content-Type: application/json" \
  -d '{"title": "Brainstorm landing Junio", "system_prompt": "Eres experto en copy para desarrolladores."}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['session']['id'])")

# Enviar mensaje dentro de la sesión
curl -X POST "http://localhost:PUERTO/api/sessions/$SESSION/chat" \
  -H "Authorization: Bearer tu-clave-secreta-aqui" \
  -H "Content-Type: application/json" \
  -d '{"message": "Propón 3 hero sections para una landing de IA."}'

🐍 Ejemplos con Python

Con requests

import requests, json

BASE = "http://localhost:PUERTO"
API_KEY = "tu-clave-secreta-aqui"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

# Chat simple
resp = requests.post(
    f"{BASE}/v1/chat/completions",
    headers=HEADERS,
    json={
        "model": "tu-modelo",
        "messages": [
            {"role": "user", "content": "Resume en 3 bullets por qué una PWA vende más que una web tradicional."}
        ],
    },
)
print(resp.json()["choices"][0]["message"]["content"])

# Streaming
with requests.post(
    f"{BASE}/v1/chat/completions",
    headers=HEADERS,
    json={"model": "tu-modelo", "stream": True, "messages": [{"role": "user", "content": "Hola"}]},
    stream=True,
) as r:
    for line in r.iter_lines():
        if line and line.startswith(b"data: "):
            payload = line[6:].decode()
            if payload == "[DONE]":
                break
            chunk = json.loads(payload)
            delta = chunk["choices"][0].get("delta", {}).get("content", "")
            print(delta, end="", flush=True)

Con el SDK oficial de OpenAI

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:PUERTO/v1",
    api_key="tu-clave-secreta-aqui",
    default_headers={
        "X-Hermes-Session-Key": "tu-session-key:formulario:contacto",
    },
)

response = client.chat.completions.create(
    model="tu-modelo",
    messages=[
        {"role": "system", "content": "Eres un asistente creativo."},
        {"role": "user", "content": "¿Qué servicios ofrece tu marca?"},
    ],
)
print(response.choices[0].message.content)

🎯 Casos de uso

🔗 Integración con n8n, webhooks y landing pages

n8n

En un nodo HTTP Request:

• Method: POST
• URL: http://localhost:PUERTO/v1/chat/completions
• Authentication: Header Auth → Authorization: Bearer tu-clave-secreta-aqui
• Body: JSON con model y messages.
• Opcional: añade X-Hermes-Session-Key para continuidad.

Webhook → middleware propio

Internet → HTTPS → nginx / Vercel / Cloudflare → tu middleware → localhost:PUERTO

from flask import Flask, request, jsonify
import requests

app = Flask(__name__)
HERMES_URL = "http://localhost:PUERTO/v1/chat/completions"
API_KEY = "tu-clave-secreta-aqui"

@app.route("/lead-webhook", methods=["POST"])
def lead_webhook():
    data = request.json
    prompt = f"Lead: {data.get('name')} ({data.get('email')})\nMensaje: {data.get('message')}\nClasifica y responde."
    r = requests.post(HERMES_URL, headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }, json={
        "model": "tu-modelo",
        "messages": [{"role": "user", "content": prompt}],
    })
    return jsonify(r.json())

Landing page con JavaScript

async function askHermes(message) {
  const res = await fetch("/api/chat", {  // tu proxy backend
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ message }),
  });
  return await res.json();
}

El proxy backend añade el Authorization y reenvía a Hermes. La API key nunca llega al navegador.

🛡️ Límites de seguridad

Lo que Hermes ya hace por defecto

• Bind en 127.0.0.1 (loopback).
• API_SERVER_KEY obligatoria; sin ella no arranca.
• Rechazo de claves placeholder en binds accesibles por red.
• Comparación de tokens con hmac.compare_digest().
• Sanitización de headers de sesión.
• Límite de body: 10 MB.
• Logs saneados: nunca vuelca la API key.
• Continuidad de sesión requiere autenticación.

Lo que DEBES hacer tú

1. No expongas el puerto del API Server a Internet. Usa proxy reverso con HTTPS y auth extra.
2. No compartas la API key con el frontend. Solo en servidor.
3. Usa claves fuertes:
   bash

   openssl rand -hex 32

4. Restringe CORS a dominios concretos:
   bash

   API_SERVER_CORS_ORIGINS="https://tu-dominio.es,https://app.tu-dominio.es"

5. Añade rate limiting en el proxy o middleware para evitar facturas sorpresa.
6. Monitorea /health/detailed para alertas de uptime.
7. No uses nohup hermes gateway run. Solo systemd:
   bash

   systemctl --user start hermes-gateway-default.service
   systemctl --user restart hermes-gateway-default.service
   systemctl --user stop hermes-gateway-default.service

8. Audita /api/jobs: con la API key se pueden crear cron jobs.

🩺 Diagnóstico rápido

📚 Referencias

• Documentación oficial de Hermes Agent: hermes-agent.nousresearch.com/docs
• Código fuente: /ruta/a/hermes-agent/gateway/platforms/api_server.py
• Skill de Hermes: skill_view(name='hermes-agent')