# free-claude gateway

Локальный Docker-шлюз, который позволяет твоему коду с Anthropic SDK работать
через бесплатные тиры сторонних AI-провайдеров. Сделан для **личного
использования** в условиях ограниченного бюджета на платный Claude API.

> Это серая зона. Прочитай раздел **Риски** прежде чем использовать.

## Архитектура

```
┌─────────────────────────────────────────────────┐
│ Docker контейнер free-claude                    │
│                                                  │
│  ┌─────────────┐    ┌──────────────────────┐   │
│  │ AI Router   │←──→│ Бесплатные провайдеры│   │
│  │ (port 3000) │    │ (Kira / Builder ID)  │   │
│  └─────────────┘    └──────────────────────┘   │
│         ↑                                        │
│  ┌──────────────────────┐                       │
│  │ Anthropic-compat     │  принимает /v1/messages│
│  │ proxy (port 8889)    │  в формате Anthropic SDK│
│  └──────────────────────┘                       │
│         ↑                                        │
│  ┌──────────────────────┐                       │
│  │ Web UI (port 8888)   │  настройка + статус   │
│  └──────────────────────┘                       │
│                                                  │
│  Volume: /data → конфиги, ключи, сессии         │
└─────────────────────────────────────────────────┘
        ↑                ↑                ↑
   guest-bot       vision-guardian    Claude Code
```

## Установка

### Локально (на этом сервере)

```bash
cd /root/free-claude
docker compose up -d
```

Открой `http://<host>:8888` и пройди настройку.

### Удалённо одной командой

```bash
curl -fsSL https://your-host/install.sh | sudo bash
```

Скрипт скачает Dockerfile + код, соберёт образ, запустит контейнер.

## Использование

### Шаг 1 — авторизация

1. Открой `http://<host>:8888` (наш Web UI)
2. Нажми «Открыть UI роутера» → откроется родной интерфейс на `:3000`
3. Выбери провайдера (рекомендуется тот, что даёт самые щедрые free-тиры)
4. Авторизуйся через Google **отдельным аккаунтом** (не основным!)
5. Создай API-ключ. **Сохрани его сразу** — повторно не покажут.

### Шаг 2 — настройка

В Web UI вставь полученный ключ, выбери модель по умолчанию, сохрани.

### Шаг 3 — проверка

Нажми «Запустить тест» — будет эхо-запрос через прокси. Если ответ
`status: ok` — всё работает.

### Шаг 4 — подключение твоих сервисов

В коде где используешь Anthropic SDK (Python/Node/любой):

```bash
ANTHROPIC_BASE_URL=http://127.0.0.1:8889
ANTHROPIC_API_KEY=<ключ из Web UI>
```

И всё. SDK будет ходить через шлюз без изменений в коде.

#### Для guest-bot (avito-service)

В `docker-compose.yml` сервиса добавь:

```yaml
environment:
  - ANTHROPIC_BASE_URL=http://host.docker.internal:8889
  - ANTHROPIC_API_KEY=<ключ>
```

Или используй внешнюю сеть docker и обращайся к контейнеру по имени `free-claude:8889`.

#### Для vision-guardian (анализ фото гостей, паспортов, FaceID)

То же самое — переменные окружения. Vision запросы (`{type: "image"}`)
проходят через прокси прозрачно.

## Конфигурация

Файл `/data/config/settings.json` (создаётся через Web UI):

```json
{
  "default_provider": "kira",
  "default_model": "claude-sonnet-4-5",
  "api_key": "...",
  "base_url": "http://127.0.0.1:3000"
}
```

## Логи

- Web UI → раздел «Логи» — три потока: router, proxy, install
- На хосте: `docker compose logs -f`
- В контейнере: `/data/logs/{router,proxy,install}.log`

## Риски (прочитай!)

### Sustainability
Бесплатные тиры провайдеров (Kira AI, Builder ID, любые подобные) могут быть
урезаны или закрыты без предупреждения. Реалистичный срок жизни такой схемы —
**3-9 месяцев** с момента появления массовых туториалов. Не строй на этом
ничего критичного.

### Блокировки аккаунтов
Интенсивное использование free-tier через CLI может рассматриваться как
abuse. Возможны:
- Блокировка Google-аккаунта (используй **отдельный**, не основной)
- Блокировка провайдера (Kira/AWS Builder)
- Понижение лимитов

### Совместимость
Не все продвинутые функции Claude гарантированно работают через роутер:
- Prompt caching — может не передаваться
- MCP servers — частичная поддержка
- Tool use / sub-agents — работает в основном, но возможны edge cases
- Batch API — обычно нет

Для рутинных запросов (диалоги, простой код, анализ фото) — работает хорошо.
Для production-критичной работы — оставь платный Anthropic API.

### Безопасность
- Запросы идут через сторонние сервисы. Не отправляй через шлюз чувствительные
  данные клиентов в открытом виде (паспортные данные, реквизиты).
- API-ключи хранятся в `/data/config/settings.json` в открытом виде.
  Защити доступ к серверу.
- Не выставляй порты `3000`, `8888`, `8889` наружу в интернет без
  reverse-proxy с авторизацией.

### Юридический статус
- Установка для **личного использования** — нормально.
- Раздача знакомым как софт «AS-IS» с этим README о рисках — нормально.
- Перепродажа доступа через свои аккаунты как платный SaaS-сервис —
  нарушает TOS большинства провайдеров и может привести к претензиям.

## Отключение и удаление

```bash
cd /opt/free-claude   # или /root/free-claude
docker compose down
docker compose down -v   # вместе с томом /data — удалит конфиги!
docker image rm free-claude:latest
```

## Лицензия

Этот шлюз — обёртка вокруг сторонних open-source инструментов. AS-IS, без
гарантий. Используй на свой риск.