Freegate

English version: README.md

Зачем платить за LLM, когда есть бесплатные?

Твой AI-агент, бот или скрипт использует один OpenAI-совместимый endpoint. За ним Freegate автоматически распределяет запросы между 50+ бесплатными моделями — Groq, Mistral, Gemini, NVIDIA NIM, OpenRouter, ZAI, Cerebras, DeepSeek, SambaNova, SiliconFlow, DeepInfra, Hyperbolic, Cohere, LLM7, Nara и локальные модели. Если один провайдер упал, перегружен или сжёг дневной лимит — запрос мгновенно уходит на следующий. Ты никогда не видишь «rate limit», и никогда не платишь.

Результат: полноценный LLM-доступ для повседневной работы по цене $0.

🔒 Работает локально — переписки никуда не уходят

Freegate крутится на твоей машине (http://localhost:4000). Твой localhost — только твой: никто другой не может к нему подключиться, и наоборот. Ключи провайдеров лежат в твоём локальном .env, история — в локальных файлах. Ни один чужой сервер не видит твои ключи и переписки.

Возможности

| | | |---|---| | 🔀 Автопереключение | 50+ провайдеров в одной цепочке. Провайдер упал? Следующий уже отвечает. | | 🤖 Автоуправление моделями | Сам находит новые бесплатные модели, тестирует, добавляет рабочие, отключает мёртвые — встроенный планировщик, всегда актуальная база. | | 🎛️ Полный ручной контроль | Ты решаешь, что работает: включай/отключай любой провайдер или модель, подставляй свои ключи (бесплатные или платные) и выбирай режим роутинга. Никакой магии за твоей спиной. | | 🗂️ База моделей | Структурированный паспорт каждой модели (скор, латентность, окно, история) + сортировка: лучшие модели получают приоритет в роутинге. | | 🏷️ Категории моделей | reasoning / coding / general / vision / local — правильная модель для каждой задачи. | | 🖼️ Vision-конвейер | Скриншот → vision-модель читает → кодинг-модель отвечает на вопрос. | | 💰 Бесплатно | Только free-модели. Дашборд показывает остаток лимита каждого провайдера. | | ⚡ Умный выбор | Прокси сам находит самый быстрый и стабильный провайдер для каждого запроса. | | 🎯 Стратегии роутинга | weighted (по умолчанию), weighted-roundrobin, weighted-least — ровнее расходуют лимиты. | | 🛡️ Надёжность | Circuit breaker, очередь запросов, автоотключение мёртвых провайдеров, watchdog. | | 📊 Дашборд | Статус, скорость, лимиты, история, токены, RPM-график, экономия ($). RU/EN. 4 темы (PolyCopy/Тёплый/Космос/Бумага) — переключатель в шапке. | | 💾 Кэш на диске | Повторные промпты не тратят лимиты вообще. | | 🎓 Методолог | Агент отвечает как инженер: план→тест→код (coding), пошагово (reasoning), как фронтенд-дизайнер (design). Промпты настраиваются в config.json. | | 🌐 Веб-поиск | Для вопросов-поиска Freegate находит актуальные факты в интернете (DuckDuckGo, без ключа) — отвечает по существу, а не галлюцинирует. | | 🧪 Самопроверка | Опционально: сложные ответы проверяет второй моделью (vetting) и помечает ошибки. Вкл: config.vetting.enabled. | | ✂️ Сжатие промптов | Опционально: убирает вежливость/заполнители (Caveman-стиль), экономя токены. config.compress.enabled. | | 📈 Sparkline 24ч | Успех по часам в дашборде + фильтры истории (поиск по модели/провайдеру, OK/Ошибки). | | 🔌 Совместимость | Любой OpenAI-клиент: opencode, Cursor, ChatGPT-аналоги, твои скрипты. |

Быстрый старт — 30 секунд

npx freegate init -i     # мастер: режим quick (1 ключ OpenRouter) или full (все ключи)
npx freegate start       # прокси на http://localhost:4000
npx freegate test        # проверить, что всё работает

Режимы init:

• quick — вставь один ключ OpenRouter → сразу 15+ бесплатных моделей. Остальные ключи добавишь позже в дашборде → «Настройки».
• full — все ключи провайдеров → 8 источников, максимум скорости и надёжности (авто-failover).

Подключить к Cursor в 2 клика: Cursor → Settings → Models → «OpenAI-compatible» → Base URL http://localhost:4000/v1, API Key = твой пароль.

Дашборд: http://localhost:4000/?key=твой_пароль. Темы: ?theme=cosmic или кнопка «Тема» в шапке; npx freegate themes — список.

Или через Docker:

docker run -d --name freegate -p 4000:4000 \
  -e PROVIDER_GROQ_APIKEY=... \
  -e PROVIDER_MISTRAL_APIKEY=... \
  -e AUTH=your-secret-key \
  nik951751/freegate

Подключение к любому OpenAI-клиенту

| Поле | Значение | |------|----------| | Base URL | http://localhost:4000/v1 | | API Key | твой пароль из init | | Модель | tier-s (быстрая) / tier-splus (мощная) |

Пример для opencode (~/.config/opencode/opencode.jsonc):

{
  "provider": {
    "free-proxy": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Freegate",
      "options": {
        "baseURL": "http://localhost:4000/v1",
        "apiKey": "your-secret-key-here"
      },
      "models": {
        "tier-splus": { "name": "Freegate (Best)", "input": ["text"] },
        "tier-s": { "name": "Freegate (Fast)", "input": ["text"] }
      }
    }
  }
}

Поддерживаемые провайдеры

| Провайдер | Модели | Где ключ | Лимит/день | |-----------|--------|----------|------------| | Groq | gpt-oss-120b, qwen-27b, allam-2-7b, compound | console.groq.com | 1000 | | Mistral | codestral, small | console.mistral.ai | 500K ток | | NVIDIA NIM | llama, vision | build.nvidia.com | 40 | | Gemini | gemini-3.6-flash, vision | aistudio.google.com | 1500 | | OpenRouter | cohere-north, glm, nemotron, ox-alpha, dots-3, lfm, laguna | openrouter.ai | 50-100 | | ZAI | glm-4.7-flash | open.bigmodel.cn | 1000 | | Cerebras | gpt-oss-120b, gemma-4-31b | cloud.cerebras.ai | 1000 | | DeepSeek | deepseek-v4-flash, vision | platform.deepseek.com | 1000 | | Локальные | Ollama, LM Studio | — | безлимит |

Новые бесплатные модели находятся, тестируются и добавляются автоматически — не нужно следить за релизами. Менеджер моделей работает каждые 6 часов.

Каталог расширяемый: добавь модель в providers.json — и она попадёт в пул. Провайдеры, недоступные твоему ключу (404), отключаются автоматически.

Как это работает

1. Приходит запрос на /v1/chat/completions (формат OpenAI).
2. Freegate выбирает лучший провайдер: здоровый, под лимитом, самый быстрый сегодня.
3. Если запрос не прошёл — мгновенно пробует следующий из цепочки.
4. Ответ возвращается клиенту в том же формате — клиент ничего не замечает.

Методолог (Productive Agent Layer)

Freegate определяет тип задачи (кодинг / рассуждение / поиск / болтовня) и подмешивает короткий системный промпт-методолог без изменений на стороне клиента. Любой OpenAI-совместимый клиент (opencode, Cursor, чат) получает ответы как от опытного инженера:

• coding — краткий план перед кодом, предложенный тест, где проверять.
• design — смелая эстетическая идея, характерные шрифты, единая палитра через CSS-переменные, срежиссированные анимации, адаптив. По мотивам Anthropic frontend-design.
• reasoning — рассуждать пошагово, показывать допущения.
• search — короткий фактологичный ответ, не выдумывать источник.
• chat — по существу и кратко.

Ко всем категориям подмешивается общий блок «не сдавайся»: если модель не находит нужный инструмент/файл/скилл там, где ожидал — не отказывается, а ищет обходной путь (читает файлы напрямую, проверяет node_modules, пробует альтернативы). Вследствие этого free-модели ведут себя находчивее, а не заканчивают ответ «не могу».

Дополнительно: категория задачи даёт буст моделям подходящей категории (coding→coding-модели, reasoning→reasoning-модели), не исключая fallback. Распределение категорий видно в дашборде и через node tools/context-diag.js.

Методолог-промпты — производный сжатый текст по мотивам superpowers (MIT). Полный агентный цикл (инструменты, субагенты) выполняется на стороне клиента.

Самообновляющаяся база моделей

Планировщик встроен в сервер — работает всегда, без cron/launchd, у всех пользователей пакета. Каждые 6 часов (настраивается) Freegate:

1. Проверяет существующие модели: мёртвые (404/402) отключаются.
2. Перепроверяет мёртвых через 7 дней — если провайдер вернул модель, она автоматически реактивируется.
3. Сканирует 8 источников: OpenRouter, HuggingFace + нативные списки Groq, Mistral, Gemini, Cerebras, DeepSeek, NVIDIA NIM.
4. Тестирует новых кандидатов параллельно и добавляет рабочие.
5. Считает скор (success-rate + латентность + контекст-окно + свежесть) и сортирует: лучшие модели получают приоритет в роутинге.

Ручные записи каталога (твои приоритеты в providers.json) не перезаписываются — сортировка применяется только к автодобавленным моделям.

node tools/models-db.js          # отчёт по базе
curl -s "localhost:4000/v1/models-db?key=пароль" | python3 -m json.tool | head -30
node scripts/auto-manage-models.js   # ручной прогон цикла
AUTO_ADD=false node scripts/auto-manage-models.js  # только отчёт, без записи

Конфигурация (config.json):

{ "modelManager": { "enabled": true, "intervalHours": 6, "autoAdd": true, "recheckDisabledDays": 7 } }

Разработка

npm test          # unit-тесты (187 шт.)
node server.js    # запуск из исходников

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

Ключи — только в .env (не в git):

PROVIDER_GROQ_APIKEY=...       # Groq
PROVIDER_MISTRAL_APIKEY=...    # Mistral
PROVIDER_GEMINI_APIKEY=...     # Gemini
PROVIDER_NIM_APIKEY=...        # NVIDIA NIM
PROVIDER_OPENROUTER_APIKEY=... # OpenRouter
PROVIDER_ZAI_APIKEY=...        # ZAI

Параметры сервера — в config.json или env:

| Параметр | Env | По умолчанию | |----------|-----|--------------| | Порт | PORT | 4000 | | Пароль | AUTH | пусто (нет auth) | | Лимит запросов/мин | config.json → rateLimit | 100/мин |

Провайдеры — каталог в providers.json (18 моделей). Добавить свой: впиши его в config.json → providers (формат как в providers.json).

Платные провайдеры + маршрутизация free↔paid. По умолчанию Freegate использует только бесплатные модели, но уважает твои платные ключи. Пометь провайдера платным в config.json → providers флагом "paid": true (или "free": false) и добавь его ключ в .env. Затем выбери, как его использовать:

{ "routing": { "preference": "free-first" } }

• free-first (по умолчанию) — бесплатная база в приоритете, твои платные ключи как запас.
• paid-first — твои платные ключи в приоритете, бесплатные как fallback.
• paid-fallback — по умолчанию бесплатные; платные трогаем, только когда бесплатные упали.

Пример: добавь свой ключ DeepSeek или любой OpenAI-совместимый под Freegate и переключись на paid-fallback — дорогие вызовы будут идти только когда бесплатные провайдеры не справились, а не на каждый запрос.

Автообновление на лету — Freegate может обновляться сам, без твоего участия в чате:

{ "autoUpdate": { "enabled": true, "intervalHours": 12 } }

Каждый интервал он делает git fetch + pull (fast-forward) в своей папке и перезапускает сервис launchd. Безопасно: пропускается, если рабочее дерево грязное (твои локальные правки важнее), и никогда не трогает .env/config.json (gitignored).

Методолог — в config.json:

{
  "methodology": {
    "enabled": true,
    "prompts": {
      "coding": "Перед кодом — краткий план. Следи, чтобы тест описывал поведение.",
      "reasoning": "Рассуждай пошагово, показывай допущения, затем вывод."
    }
  }
}

• enabled: false — полностью выключает методолог и роутинг-буст.
• prompts — переопределяет текст для конкретной категории; остальные остаются в дефолтах.

Команды CLI

npx freegate init              # создать конфиг
npx freegate init -i           # интерактивный мастер (ключи, пароль)
npx freegate doctor            # диагностика: ключи, модели, «что проверить»
npx freegate diag              # отчёт: успешность, классы ошибок, смена провайдеров
npx freegate start             # запустить прокси
npx freegate status            # диагностика: провайдеры, лимиты, ошибки
npx freegate test              # проверить, что работает
npx freegate install-service   # автозапуск при старте системы
npx freegate dashboard         # открыть дашборд

FAQ

Это законно? Да. Ты подключаешь свои бесплатные ключи провайдеров — просто получаешь единый надёжный доступ к ним всем.

Сколько это стоит? $0. Только лимиты бесплатных тарифов провайдеров.

Какие модели самые быстрые? Прокси сам измеряет и выбирает. Сейчас лидируют Qwen (Groq, ~300ms) и cohere-north (OpenRouter).

Могу добавить свой провайдер? Да — впиши его в config.json или providers.json.

Это только для opencode? Нет. Любой OpenAI-совместимый клиент (см. examples/ — Cursor, Claude Code, скрипты).

Инструменты (tools/)

Генератор шортс — tools/generate_shorts.py

Бесплатная генерация вертикальных видео (9:16) через MiniMax H3 (видео + звук из одного промпта) или Wan 2.1. Работает через онлайн-демо Hugging Face — GPU в облаке, без установки.

cd tools
uv venv .venv && uv pip install --python .venv/bin/python -r requirements.txt
export HF_TOKEN=hf_xxx            # бесплатно: huggingface.co → settings/tokens
./.venv/bin/python generate_shorts.py "Cozy morning scene, warm light" --format 9:16 --duration 5

Каталог готовых промптов: tools/prompts.md.

Лицензия

MIT