94 lines
2.5 KiB
Markdown
94 lines
2.5 KiB
Markdown
---
|
|
title: Hermes Kraken — OpenAI-Compatible API Server
|
|
created: '2026-05-29'
|
|
updated: '2026-05-29'
|
|
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 → hermes.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`
|
|
|
|
SSH to Kraken still works via VPS reverse tunnel (port 2223) — the CF
|
|
hostname change does not affect SSH 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
|