# Hermes Agent — Claude-Max-Proxy Setup

Repliziert den Proxy-Trick, den wir fuer ARIA nutzen: `claude-max-api-proxy`
(npm) wrappt die Claude Code CLI — angemeldet mit deiner Claude-Max-
Subscription — als OpenAI-kompatiblen `/v1/chat/completions`-Endpoint.
[Hermes Agent](https://github.com/NousResearch/hermes-agent) (Nous Research,
CLI/Desktop-Agent, unterstuetzt laut Doku "your own endpoint" als
Model-Provider) kann darueber mit Claude reden, ohne API-Kosten — laeuft
ueber die Subscription, nicht ueber Anthropic-API-Billing.

**Wichtig:** Hermes Agent selbst (das CLI/Desktop-Tool von Nous Research)
ist hier NICHT enthalten — Stefan deployt das selbst auf einer anderen
Maschine. Dieser Stack liefert nur die Proxy-Seite, die Hermes von dort
ansprechen kann. ARIA bleibt komplett unangetastet (eigenes Docker-Netz
`hermes-net`, eigenes Claude-CLI-Login-Volume, kein gemeinsamer Container).

## Architektur

```
Hermes Agent (andere Maschine)
        |  HTTP(S), Authorization: Bearer <TOKEN>
        v
  hermes-gateway  (Port ${HERMES_GATEWAY_PORT:-8447}, nach aussen exposed)
        |  prueft Bearer-Token, sonst 401
        v
  hermes-proxy    (Port 3456, NUR docker-intern erreichbar)
        |  claude-max-api-proxy -> Claude Code CLI (Claude-Max-Login)
        v
     Anthropic (ueber deine Claude-Max-Subscription)
```

Warum das Gateway davor: `hermes-proxy` selbst hat keine Authentifizierung
(genau wie ARIAs Proxy) — das ist bei ARIA ok, weil der Proxy nie einen
Netzwerk-Port bekommt. Hermes laeuft aber auf einer anderen Maschine, der
Proxy muss also ueber Netzwerk erreichbar sein. Ohne Auth waere das ein frei
nutzbarer Claude-Max-Zugang fuer jeden der den Port erreicht. Das Gateway
(`proxy-patches/gateway.js`, pure Node, keine Extra-Deps) prueft dafuer den
`Authorization: Bearer <TOKEN>`-Header gegen ein Shared Secret, bevor
irgendwas an `hermes-proxy` weitergeleitet wird.

## Was uebernommen wurde (1:1 aus ARIAs Proxy-Setup)

- **Sed-Patches** an der npm-CLI-Bridge (host-binding, `--dangerously-skip-permissions`,
  echter `--system-prompt`-Kanal, 24h-Timeout, Prompt via stdin) — generische
  Infra-Fixes, nicht ARIA-spezifisch.
- **Adapter-Patches** (`proxy-patches/openai-to-cli.js`, `cli-to-openai.js`) —
  die OpenAI-`tools` <-> `<tool_call>`-Text-Bruecke. Generisch, 1:1 uebernommen.
- **NICHT** uebernommen: ARIAs `routes.js`-Patch (Live-Tool-Stream/Not-Aus
  fuers Diagnostic-UI, ARIA-Bridge-spezifisch). Stattdessen gibt's hier das
  eigene `gateway.js` fuer die Auth, die ARIA in der Form nicht braucht.

## Setup

1. **`.env` anlegen:**
   ```bash
   cd /shared/projects/hermes_agent
   cp .env.example .env
   openssl rand -hex 32   # Ausgabe in .env bei HERMES_GATEWAY_TOKEN eintragen
   ```

2. **Stack starten:**
   ```bash
   docker compose up -d
   ```

3. **Einmalig Claude-CLI-Login** (oeffnet Browser-OAuth mit deiner Claude-Max-Subscription):
   ```bash
   docker exec -it hermes-proxy claude
   ```
   Danach liegen die Credentials persistent in `hermes-data/claude-config/.credentials.json`
   — ueberlebt Container-Restarts.

4. **Von der Hermes-Maschine aus testen:**
   ```bash
   curl -s http://<diese-maschine>:${HERMES_GATEWAY_PORT:-8447}/v1/chat/completions \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <HERMES_GATEWAY_TOKEN aus .env>" \
     -d '{"model":"claude-sonnet-4","messages":[{"role":"user","content":"Sag Hallo"}]}'
   ```
   Ohne oder mit falschem Bearer-Token gibt's `401 unauthorized` — Gateway
   arbeitet.

5. **Hermes Agent konfigurieren** (auf der Ziel-Maschine, `~/.hermes/config.yaml`):
   ```yaml
   model:
     provider: custom
     model: "sonnet"
     base_url: "http://<diese-maschine>:8447/v1"
     api_key: "<derselbe HERMES_GATEWAY_TOKEN>"
   ```
   `base_url` hat laut Hermes-Doku Vorrang vor `provider` — funktioniert wie
   bei selbst gehosteten/lokalen Endpoints (vLLM, Ollama etc.), die
   Hermes-Doku beschreibt genau diesen Ansatz. Modellnamen `sonnet` / `opus`
   / `haiku` werden vom Adapter (`openai-to-cli.js`, `MODEL_MAP`) auf die
   `--model`-CLI-Flags gemappt.

## Sicherheitshinweis

Das Gateway schuetzt vor Fremdnutzung deiner Subscription (Bearer-Token-
Pflicht), **aber der Traffic selbst ist unverschluesseltes HTTP** — kein TLS
zwischen Hermes und dem Gateway. Solange beide Maschinen im selben
vertrauenswuerdigen LAN oder per VPN verbunden sind: unkritisch. Wenn die
Hermes-Maschine ueber offenes Internet zugreifen soll: Port NICHT direkt
exposen, sondern per SSH-Tunnel, WireGuard/Tailscale oder einen TLS-
Reverse-Proxy davorschalten. Sag Bescheid, dann bauen wir das nach, sobald
klar ist wie die beiden Maschinen tatsaechlich verbunden sind.

## Wo deployen?

Diese Compose-Datei ist ortsunabhaengig — lief bisher nirgends deployed,
liegt nur unter `/shared/projects/hermes_agent/` (Code-Editor-Sync). Du
kannst sie 1:1 dahin kopieren, wo der Proxy tatsaechlich laufen soll (z.B.
aria-wohnung als eigener isolierter Stack neben ARIA, oder eine ganz andere
Maschine mit Zugriff auf deine Claude-Max-Subscription). Wichtig ist nur:
egal wo, `HERMES_GATEWAY_PORT` muss von der Hermes-Maschine aus erreichbar
sein.