2026-05-13 план: Aide → Kraken backend через Hermes API + CF Tunnel

family/projects/aide-kraken-backend.md

@@ -0,0 +1,134 @@
+# Aide → Kraken Backend: план настройки
+
+> Создано: 2026-05-13  
+> Статус: 📋 план, не выполнен
+
+## Цель
+
+Сделать Кракена бэкендом для приложения **Aide** на Android — как замена Siri/Google Assistant с Hermes вместо Claude API напрямую.
+
+---
+
+## Почему это реализуемо
+
+- Hermes gateway уже поддерживает **OpenAI-compatible API server** (`gateway/platforms/api_server.py`)
+- Endpoint: `POST /v1/chat/completions` — именно то, что ожидает Aide (BYOK → Custom Endpoint)
+- Кракен работает в режиме `network_mode: host` → порт 8642 будет доступен напрямую на хосте
+- cloudflared уже запущен на Кракене (туннель `kraken` активен) → достаточно добавить hostname
+
+---
+
+## Архитектура
+
+```
+Android (Aide)
+  └── HTTPS → hermes.kraken.qentra.top/v1/chat/completions
+                    ↓ Cloudflare Tunnel
+              cloudflared (контейнер на Кракене, host network)
+                    ↓ localhost
+              hermes-kraken:8642  (API server)
+                    ↓
+              Hermes gateway → Gemini / OpenRouter / ...
+```
+
+---
+
+## Шаги
+
+### Шаг 1 — Включить API server в Hermes (config.yaml на Кракене)
+
+Добавить в `/opt/data/config.yaml`:
+
+```yaml
+api_server:
+  enabled: true
+  port: 8642
+  host: "0.0.0.0"   # слушать на всех интерфейсах (CF туннель на хосте)
+  key: "СГЕНЕРИРОВАТЬ_СЕКРЕТ"  # openssl rand -hex 32
+```
+
+Перезапустить контейнер:
+```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"
+```
+
+Проверить:
+```bash
+curl -s http://localhost:8642/health
+# → {"status":"ok","version":"..."}
+```
+
+### Шаг 2 — Добавить Cloudflare Tunnel hostname
+
+В **Cloudflare Zero Trust** → Networks → Tunnels → `kraken` → Edit → Public Hostnames → Add:
+
+| Поле | Значение |
+|------|----------|
+| Subdomain | `hermes` |
+| Domain | `kraken.qentra.top` |
+| Type | HTTP |
+| URL | `localhost:8642` |
+
+Результат: `https://hermes.kraken.qentra.top` → Кракен:8642
+
+> Нужно будет сделать через CF Zero Trust Dashboard (web UI) — Орёл сам не может, нужен Alex.
+
+Проверить после добавления:
+```bash
+curl -s https://hermes.kraken.qentra.top/health
+```
+
+### Шаг 3 — Настроить Aide на Android
+
+В Aide → Providers → Add Provider → Custom Endpoint:
+
+| Поле | Значение |
+|------|----------|
+| Base URL | `https://hermes.kraken.qentra.top/v1` |
+| API Key | секрет из config.yaml |
+| Model | `hermes-agent` (или любое — маппится на Hermes) |
+
+---
+
+## О cloudflared SSH перенастройке
+
+Текущий SSH hostname `kraken.qentra.top → SSH → localhost:22` **не мешает** — он просто не используется (SSH ходит через VPS на 2223).
+
+Варианты:
+- **Оставить как есть** — просто добавить новый hostname `hermes.kraken.qentra.top` для API
+- **Перенастроить старый** — изменить `kraken.qentra.top` с SSH на HTTP (если SSH через CF больше не нужен)
+
+Рекомендую: **оставить** старый SSH hostname (не мешает, может пригодиться), добавить новый для Hermes API.
+
+---
+
+## Что НЕ нужно менять
+
+- ✅ Контейнер cloudflared — уже запущен и работает
+- ✅ Reverse SSH туннель на VPS — не трогаем, SSH доступ остаётся
+- ✅ network_mode: host у hermes-kraken — порт 8642 сразу на хосте
+
+---
+
+## Что нужно от Alex
+
+1. Сгенерировать API ключ: `openssl rand -hex 32` (сохранить в `.env` или config)
+2. Добавить hostname в CF Zero Trust (вебинтерфейс)
+3. Ввести endpoint + ключ в Aide
+
+Всё остальное Орёл сделает сам.
+
+---
+
+## Связанные заметки
+
+- [[kraken-access]] — SSH и Portainer доступ к Кракену
+- [[kraken-portainer-access]] — Portainer API команды
+- [[openmediavault-rpi5]] — структура Docker на Кракене