# 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 — Изменить 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.

Проверить после изменения:
```bash
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) |

---

## О 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 на Кракене