Initial Hermes Agent stack: Claude-Max proxy + gateway, docker-compose, README
This commit is contained in:
ARIA
@@ -0,0 +1,116 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user