obsidian-vault/family/projects/aide-kraken-backend.md

Aide → Kraken Backend: план настройки

Создано: 2026-05-13
Статус: ✅ работает (Aide + SpeakGPT)

Цель

Сделать Кракена бэкендом для приложения 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:

api_server:
  enabled: true
  port: 8642
  host: "0.0.0.0"   # слушать на всех интерфейсах (CF туннель на хосте)
  key: "СГЕНЕРИРОВАТЬ_СЕКРЕТ"  # openssl rand -hex 32

Перезапустить контейнер:

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"

Проверить:

curl -s http://localhost:8642/health
# → {"status":"ok","version":"..."}

Шаг 2 — Изменить hostname в CF Zero Trust

В Cloudflare Zero Trust → Networks → Tunnels → kraken → Edit → Public Hostnames → найти kraken.qentra.top:

Изменить:

• Type: SSH → HTTP
• URL: localhost:22 → localhost:8642

Сохранить. Результат: https://kraken.qentra.top → Кракен:8642

Делается через CF Zero Trust Dashboard — нужен Alex.

Проверить после изменения:

curl -s https://kraken.qentra.top/health

Шаг 3 — Настроить Aide на Android

В Aide → Providers → Add Provider → Custom Endpoint:

Поле	Значение
Base URL	https://kraken.qentra.top/v1
API Key	секрет из config.yaml
Model	hermes-agent (или любое — маппится на Hermes)

Шаг 4 — Настроить SpeakGPT

В SpeakGPT → Settings → API:

Поле	Значение
Base URL	https://kraken.qentra.top/v1
API Key	секрет из config.yaml
Model	hermes-agent

Важно: Base URL обязательно должен заканчиваться на /v1, иначе SpeakGPT стучится в корень /chat/completions, который не существует.

---

Заметки по эксплуатации

Туннель нестабилен — sendmsg: network is unreachable

Иногда после старта cloudflared начинает циклически падать с ошибкой write udp: sendmsg: network is unreachable — проблема с IPv6/UDP на RPi5.

Решение: пересоздать контейнер с флагом --protocol http2:

docker run --rm --network host cloudflare/cloudflared tunnel --no-autoupdate --protocol http2 run --token <TOKEN>

После запуска проверить 4/4 Registered в логах.

После пересоздания cloudflared — Cloudflare может выдать 403

При смене connector ID (после пересоздания контейнера) Cloudflare WAF может начать блокировать запросы с незнакомых IP. Запросы с телефона (Aide, SpeakGPT) обычно проходят, так как используют мобильный User-Agent.

Если 403 — проверить Cloudflare Zero Trust Dashboard:

• Access → Applications — нет ли лишних правил для kraken.qentra.top
• Или просто подождать — кэш обновляется

---

О cloudflared

SSH через CF (kraken.qentra.top → SSH → localhost:22) не используется — SSH ходит через VPS на порту 2223. Поэтому hostname просто перенастраивается с SSH на HTTP без потери функциональности.

---

Что НЕ нужно менять

• ✅ Контейнер 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 на Кракене