---
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