93 lines
3.0 KiB
Markdown
93 lines
3.0 KiB
Markdown
---
|
||
title: Hermes Kraken — OpenAI-Compatible API Server
|
||
created: '2026-05-29'
|
||
updated: '2026-09-04'
|
||
type: tech
|
||
namespace: personal
|
||
tags: [hermes, kraken, infra, agent, how-to]
|
||
sources:
|
||
- family/projects/aide-kraken-backend.md
|
||
confidence: medium
|
||
related:
|
||
- "[[tech/hermes-docker-kraken]]"
|
||
- "[[tech/vps-qentra]]"
|
||
---
|
||
|
||
# Hermes Kraken — OpenAI-Compatible API Server
|
||
|
||
Hermes on Kraken exposes an OpenAI-compatible `/v1/chat/completions`
|
||
endpoint (`gateway/platforms/api_server.py`). Exposed externally via
|
||
Cloudflare Tunnel → used by the Android **Aide** app as a Hermes-backed
|
||
assistant.
|
||
|
||
## Architecture
|
||
|
||
```
|
||
Android (Aide)
|
||
└── HTTPS → kraken.qentra.top/v1/chat/completions
|
||
↓ Cloudflare Tunnel
|
||
cloudflared (Kraken, host network)
|
||
↓ localhost:8642
|
||
hermes-kraken (docker run, network_mode: host)
|
||
↓
|
||
Hermes gateway → Gemini / OpenRouter / ...
|
||
```
|
||
|
||
`network_mode: host` means port 8642 is directly on the Kraken host —
|
||
no port mapping needed.
|
||
|
||
## Config (Kraken /opt/data/config.yaml)
|
||
|
||
```yaml
|
||
api_server:
|
||
enabled: true
|
||
port: 8642
|
||
host: "0.0.0.0"
|
||
key: "<secret>" # openssl rand -hex 32
|
||
```
|
||
|
||
Restart container via Portainer or:
|
||
```bash
|
||
BASE=http://localhost:9000
|
||
KEY="ptr_AJY+Ba9A7f6pcAHZfDD5koU4stkKgJCdbTEXLDLxn0g="
|
||
EP=3
|
||
CID=$(curl -s -H "X-API-Key: $KEY" \
|
||
"$BASE/api/endpoints/$EP/docker/containers/json" \
|
||
| jq -r '.[] | select(.Names[] | contains("hermes-kraken")) | .Id')
|
||
curl -s -X POST -H "X-API-Key: $KEY" \
|
||
"$BASE/api/endpoints/$EP/docker/containers/$CID/restart"
|
||
```
|
||
|
||
Health check: `curl -s http://localhost:8642/health`
|
||
|
||
## Cloudflare Tunnel Setup
|
||
|
||
Tunnel name: `kraken`. Public hostname (CF Zero Trust dashboard):
|
||
- **Hostname:** `kraken.qentra.top`
|
||
- **Type:** HTTP (not SSH)
|
||
- **URL:** `localhost:8642`
|
||
|
||
`kraken.qentra.top` — HTTP-маршрут на Hermes API (8642). SSH через Cloudflare Tunnel идёт **отдельным** hostname **`ssh-kraken.qentra.top` → `ssh://localhost:22`** (рабочий с 2026-09-04; вход `ssh kraken@ssh-kraken.qentra.top`, разовый `cloudflared access login ssh-kraken.qentra.top`, см. [[kraken-access]]). Альтернативный SSH-путь — VPS reverse tunnel `91.207.28.205:2223`. ⚠️ Двухуровневый `ssh.kraken.qentra.top` НЕ работает (нет edge-TLS на 2-уровневом subdomain) — подробности/питфол в [[kraken-access]].
|
||
|
||
## Aide Android Client Config
|
||
|
||
Provider: Custom Endpoint
|
||
|
||
| Field | Value |
|
||
|-------|-------|
|
||
| Base URL | `https://kraken.qentra.top/v1` |
|
||
| API Key | secret from config.yaml |
|
||
| Model | `hermes-agent` (maps to Hermes internally) |
|
||
|
||
## What Was Not Changed
|
||
|
||
- cloudflared container — already running
|
||
- VPS reverse SSH tunnel — unaffected
|
||
- `network_mode: host` on hermes-kraken — already set
|
||
|
||
## See Also
|
||
|
||
- [[tech/hermes-docker-kraken]] — how Hermes runs on Kraken (docker run
|
||
pattern, no compose)
|
||
- [[tech/vps-qentra]] — VPS qentra.top: Cloudflare + nginx stack
|