README.ru.md
Rama codex/mvp · réplica de lectura del repositorio original.
<h1 align="center">CodexNest</h1>
<p align="center"><a href="./README.md">English</a> · Русский</p>
> **Репозиторий устарел.** CodexNest получил продолжение в [Nest Apps](https://github.com/petrovichest/nest-apps).
> Дальнейшее развитие проекта продолжается там. Этот репозиторий сохранён для справки.
## Переход на Nest Apps
Для стандартной установки через `install.sh` выполните команды от того же
Linux-пользователя, который установил CodexNest:
```bash
sed -i \
-e 's|petrovichest/codex-nest|petrovichest/nest-apps|g' \
-e 's|android-latest/CodexNest-latest.json|rolling-latest/NestApps-latest.json|g' \
"$HOME/.local/bin/codexnest"
git -C "${CODEXNEST_ROOT:-$HOME/.local/share/codexnest}/source" \
remote set-url origin https://github.com/petrovichest/nest-apps.git
codexnest check-update
```
Это переключает updater и Git source на Nest Apps без переустановки и
перезапусков. Проекты, диалоги, настройки и авторизация сохраняются; работающий
билд остаётся прежним до применения обновления.
Чтобы установить новый билд, откройте **Настройки → Обслуживание → Проверить
обновления → Обновить**. Применение обновления кратко перезапускает только
приложение CodexNest; в daemon-режиме Codex daemon продолжает работать.
Перезагрузка компьютера не требуется.
<p align="center">
<a href="./docs/assets/cover.png"><img src="./docs/assets/cover.png" width="1600" alt="CodexNest: одна сессия с поиском по проектам на компьютере и телефоне" /></a>
</p>
<p align="center">
<strong>Ваше рабочее пространство Codex. На компьютере и телефоне.</strong><br />
Управляйте проектами и диалогами Codex CLI на своей Linux-машине из браузера или Android-приложения.
</p>
<p align="center">
<a href="https://github.com/petrovichest/codex-nest/actions/workflows/ci.yml"><img src="https://github.com/petrovichest/codex-nest/actions/workflows/ci.yml/badge.svg" alt="Статус CI" /></a>
<a href="https://github.com/petrovichest/codex-nest/releases/latest"><img src="https://img.shields.io/github/v/release/petrovichest/codex-nest?label=release&color=646660" alt="Последний релиз" /></a>
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-292a29" alt="Лицензия Apache 2.0" /></a>
</p>
<p align="center">
<a href="#быстрый-старт">Быстрый старт</a> ·
<a href="#как-это-работает">Как это работает</a> ·
<a href="#скриншоты">Скриншоты</a> ·
<a href="https://github.com/petrovichest/codex-nest/releases/latest/download/CodexNest-latest.apk">Android APK</a> ·
<a href="./deploy/DEPLOYMENT.md">Документация</a>
</p>
CodexNest — неофициальный self-hosted проект для одного владельца. Он не связан
с OpenAI и не поддерживается ею.
## Быстрый старт
Нужна машина с Ubuntu или Debian (`amd64` или `arm64`), установленным Codex CLI
и выполненным входом в него. Запустите установщик от обычного пользователя:
> **Только приватный доступ.** Используйте CodexNest на самом хосте, в полностью
> доверенной LAN или своей приватной VPN. Не открывайте порт `4310` в интернет.
> Перед подключением прочитайте о [границе безопасности](#граница-безопасности).
```bash
curl -fsSL https://github.com/petrovichest/codex-nest/releases/latest/download/install.sh | bash
```
Установщик предоставляет закреплённую версию Node.js и управляемые
пользовательские службы, но не устанавливает Codex CLI и не выполняет вход в него.
Следуйте [инструкции первого подключения](./deploy/DEPLOYMENT.md#6-проверка-и-первый-вход),
чтобы открыть клиент в браузере или подключить
[Android-приложение](https://github.com/petrovichest/codex-nest/releases/latest/download/CodexNest-latest.apk).
## Возможности
- **Держите проекты под рукой.** Объединяйте серверные папки и сессии;
продолжайте диалоги, создавайте ответвления и отправляйте завершённое в архив.
- **Направляйте работу по ходу.** Следите за ответами и планами, проверяйте
команды и изменения файлов, отвечайте на вопросы, ставьте сообщения в очередь
или прерывайте выполнение.
- **Ведите несколько сессий.** Следите за параллельной работой и используйте
[CodexNest Team](#codexnest-team) для дочерних задач под управлением приложения.
- **Берите рабочее пространство с собой.** Работайте в браузере или Android,
сохраняйте черновики и недавние данные при временной потере связи. На iOS
HTTPS-сайт можно добавить на экран «Домой» как веб-приложение.
- **Настройте интерфейс под себя.** Выберите русский или английский язык,
системную, светлую или тёмную тему и отдельные размеры текста для навигации,
диалогов и редакторов.
- **Открывайте результат.** Просматривайте артефакты рядом с диалогом
и скачивайте готовые файлы.
- **Используйте голос и браузер.** Диктуйте промпты, получайте уведомления
о завершении работы и запросах внимания, подключайте вкладки Chrome через
[браузерное расширение](#браузерное-расширение).
## Как это работает
**Один аккаунт ChatGPT. Все ваши устройства.** Запустите Codex и CodexNest backend
на своём Linux-компьютере, мини-ПК или сервере. Хост может работать в headless-режиме,
без графического интерфейса. Вход в ChatGPT выполняется через Codex на этом хосте;
файлы проектов, инструменты разработки и выполняемые задачи остаются там.
[](./docs/assets/how-it-works-ru.png)
Подключайте любое число **своих устройств** через Android APK или браузер.
Доступ к хосту — по WireGuard, Tailscale, другой приватной VPN либо полностью
доверенной LAN. Устанавливать Codex, инструменты разработки и рабочую копию
проекта на каждом клиенте не требуется.
Подключённые клиенты видят общие проекты, историю диалогов и текущее состояние
выполнения; на каждом устройстве можно независимо переключаться между сессиями.
Настройки, данные входа, черновики и недавние данные сессий могут сохраняться
локально, а среда разработки остаётся на хосте.
## Скриншоты
Обновлённый интерфейс объединяет парящие панели, компактное поле ввода и единое
оформление элементов управления на компьютере и телефоне. Демонстрационный
проект **Launchpad** показывает добавление поиска, проверку хода работы и просмотр
результата. Все проекты и диалоги на изображениях — подготовленные примеры.
Нажмите на изображение, чтобы открыть его в полном размере.
Снято с интерфейса v0.1.9 на коммите [`b8805aa`](https://github.com/petrovichest/codex-nest/commit/b8805aa0ee30e5617de06497ff310d0bbc0c24cc), 21 сентября 2026 года.
### Рабочее пространство для ваших проектов
Парящая боковая панель держит проекты и сессии рядом с диалогом. Читайте план,
следите за ходом работы и отправляйте следующую инструкцию из компактного поля
ввода внизу экрана.
[](./docs/assets/desktop-session.png)
### Следующий шаг всегда под рукой
Выберите вариант ответа или напишите свой, пока следующее сообщение ждёт
в очереди. В светлой и тёмной темах одинаковое расположение элементов управления.
[](./docs/assets/desktop-queue.png)
### Сохраняйте контекст решений
Отправленные ответы сохраняют полный вопрос рядом с вашим выбором, в одной
парящей карточке. Вернитесь к диалогу, чтобы увидеть, о чём договорились и почему.
[](./docs/assets/desktop-answers.png)
### Проверьте, что стоит за ответом
Откройте ход работы, чтобы посмотреть команды, результаты тестов и изменения
файлов рядом с ответом. Раскрывайте отдельные записи, когда нужны подробности.
[](./docs/assets/desktop-activity.png)
### То же рабочее пространство на телефоне
Откройте список сессий, чтобы переключаться между проектами и диалогами.
Прочитайте план, продолжите сессию, ответьте на уточнение или откройте готовый
отчёт. Здесь показан мобильный веб-интерфейс, который также используется внутри
Android-приложения.
<p align="center">
<a href="./docs/assets/mobile-sessions.png"><img src="./docs/assets/mobile-sessions.png" width="260" alt="Светлая тема на телефоне: открытая панель с проектами, закреплёнными и активными сессиями" /></a>
<a href="./docs/assets/mobile-session.png"><img src="./docs/assets/mobile-session.png" width="260" alt="Светлая тема на телефоне: план, завершённая задача и поле ввода" /></a>
</p>
<p align="center"><sub>Переключайтесь между сессиями · Продолжайте диалог</sub></p>
<p align="center">
<a href="./docs/assets/mobile-question.png"><img src="./docs/assets/mobile-question.png" width="260" alt="Тёмная тема на телефоне: варианты ответа и сообщение в очереди" /></a>
<a href="./docs/assets/mobile-report.png"><img src="./docs/assets/mobile-report.png" width="260" alt="Тёмная тема на телефоне: отчёт о поиске в просмотрщике Markdown" /></a>
</p>
<p align="center"><sub>Принимайте решения · Читайте результат</sub></p>
---
## Граница безопасности
CodexNest — локальное приложение для одного владельца. Запускайте его только на
самом хосте, в полностью доверенной частной LAN или в приватной сети
WireGuard/Tailscale владельца. Никогда не публикуйте порт `4310` через публичный
port forwarding, UPnP, reverse proxy, tunnel или правило cloud firewall.
Bearer token даёт права владельца CodexNest, а сервер имеет те же права на
файлы, что Linux-пользователь Codex CLI. Обычный HTTP не защищает token,
промпты, вывод, пути или решения по approval; используйте его только внутри
зашифрованной приватной VPN или в полностью доверенной LAN. В общей или иной
недоверенной сети используйте приватный HTTPS. Подробности приведены в
[инструкции по развёртыванию](./deploy/DEPLOYMENT.md) и
[предупреждении для Android](./apps/client/android/README.md).
## Архитектура и источники истины
```text
Браузер / Android-приложение Capacitor
|
authenticated HTTP + WebSocket
|
сервер CodexNest (Fastify)
| |
| +-- metadata CodexNest (SQLite + rollback JSON)
|
+-- daemon Codex app-server через локальный Unix socket (production)
или JSONL через stdio (разработка)
```
Только сервер общается с Codex app-server. В production можно использовать
managed daemon, чтобы активные turn переживали перезапуск CodexNest; прямой
stdio остаётся простым вариантом для разработки. Codex служит источником истины
для threads, turns и истории диалогов. CodexNest хранит только собственное
состояние: проекты, verifier токена, read/pin/outcome metadata, очереди,
настройки и состояние Team orchestration.
Репозиторий организован как npm workspace:
- `apps/server` — authenticated API/WebSocket server и мост к Codex;
- `apps/client` — React/Vite UI и Android-проект Capacitor;
- `apps/extension` — отдельно собираемое расширение для управления Chrome;
- `packages/protocol` — публичный DTO-контракт клиента и сервера; и
- `deploy` — installer, services, proxy, STT, update и recovery artifacts.
Текущая реализация и тесты определяют поведение продукта. Сгенерированные типы
app-server в `apps/server/src/codex/generated` закреплены через
`apps/server/src/codex/PROTOCOL_VERSION`. Этот README — основная точка входа в
продукт, а [deploy/DEPLOYMENT.md](./deploy/DEPLOYMENT.md) — источник истины для
эксплуатации.
## CodexNest Team
CodexNest Team — собственный механизм managed orchestration приложения, а не
нативный multi-agent или subagent mode Codex. Корневая сессия CodexNest
координирует managed child tasks через инструменты CodexNest и сохранённое
состояние `teamOrchestration`, отвечает за интеграцию и финальный ответ, и только
она имеет право делегировать. Дочерние сессии не могут создавать новых детей.
По умолчанию дочерние сессии работают без записи и сети. Корень может выдать
ограниченный доступ к сети или путям внутри репозитория; изменения обычно
изолированы в detached worktrees до интеграции корнем. В Team parent и child
sessions нативные agent tools отключены для сохранения этой границы. Нативные
subagents в других частях проекции Codex отделены и не реализуют Team.
## Браузерное расширение
Расширение Chrome даёт CodexNest инструменты управления браузером и полное
хранилище сетевых обменов.
Иконка расширения открывает компактный popup. Нажмите **Открыть сбоку**, чтобы
оставить те же элементы управления в Chrome Side Panel во
время работы со страницами. Панель следует за активной вкладкой и остаётся
открытой, пока вы не закроете её штатной кнопкой браузера; само расширение её не
открывает.
Скачайте `codexnest-browser-<version>.zip` из того же GitHub Release, что и сервер
CodexNest. Распакуйте архив, откройте `chrome://extensions`, включите режим
разработчика, нажмите **Загрузить распакованное расширение** и выберите полученную
папку. Зафиксированный ключ manifest сохраняет один ID расширения между релизами.
Откройте popup и укажите HTTP(S)-адрес CodexNest и токен владельца. Для текущей
вкладки выберите существующую доступную корневую сессию. CodexNest поддерживает
одну группу вкладок Chrome на сессию; через popup и боковую панель можно
управлять несколькими сессиями и открывать их чат.
Расширение использует `chrome.debugger` и намеренно даёт подключённой сессии Codex
доступ ко всем обычным вкладкам Chrome: навигации, кликам, вводу, JavaScript,
скриншотам, метаданным консоли/сети и загрузке файлов. Устанавливайте его только в
доверенный профиль Chrome. Токен владельца хранится в `chrome.storage.local`, а
обычный HTTP раскрывает его в недоверенной сети.
### Захват сетевых запросов
Для каждого сохранённого запроса CodexNest записывает полные исходные события
провайдера, все поля и заголовки запроса и ответа, а также оба тела без
редактирования. Бинарные тела выдаются в base64 вместе с SHA-256. Хранятся
последние 1 000 полных обменов на каждую подключённую вкладку. Размер одного
тела ограничен 100 МиБ, хранилище одной привязки — 1 ГиБ, а один фрагмент чтения
тела — 512 КиБ. Если обмен невозможно получить целиком или он превышает лимит,
он полностью отбрасывается и учитывается в счётчике пропусков.
Отключение сохраняет вкладки, убирает их группу CodexNest и отсоединяет браузерный
адаптер. Сервер сохраняет владельца привязки, поэтому повторно подключить её
может только тот же экземпляр расширения. Переноса или восстановления после
потери данных профиля расширения нет.
## Уведомления
Android-уведомления полностью self-hosted. Foreground service держит
authenticated WebSocket к серверу CodexNest владельца, переподключается после
потери сети или перезагрузки и создаёт локальные уведомления. Поэтому при
активной фоновой доставке Android показывает постоянное низкоприоритетное
уведомление о соединении. Firebase, Google Play Services, сторонний push provider
и дополнительные credentials для уведомлений не требуются.
Браузерные уведомления используют тот же WebSocket. Вкладка должна оставаться
открытой или свёрнутой, а правила безопасности браузера могут требовать HTTPS
для выдачи разрешения на уведомления.
## Распознавание речи
Голосовые записи можно распознавать моделью OpenAI Audio API или локальным
сервисом. Оба поддерживаемых локальных backend используют единый контракт
`CODEXNEST_STT_LOCAL_URL`:
- HTTP-сервер `whisper.cpp`; или
- входящий в репозиторий адаптер
[`deploy/local-stt-server.py`](./deploy/local-stt-server.py) на базе
`faster-whisper`.
На настроенном endpoint должен работать только один локальный backend. Provider,
язык, timeout и необязательное улучшение локального текста через Codex можно
настроить в UI или окружении сервера. Установка и service examples для обоих
backend описаны в [инструкции по развёртыванию](./deploy/DEPLOYMENT.md#speech-to-text).
## Разработка и тестирование
Требуются Node.js 24 LTS, npm 10 или новее и авторизованный Codex CLI. Для
Android также нужны JDK 21 и Android SDK.
Перед изменением UI откройте [дизайн-кит](./docs/design-kit.md): общие токены,
паттерны элементов, оговорённые исключения и проверка новой фичи.
CI проверяет форматирование, lint, модульные тесты, сборку, зависимости через audit
и скрипты установщика. Типы протокола, клиента и расширения проверяются при сборке;
типы сервера — отдельной командой. Браузерные тесты, проверки совместимости Codex
и проверки установщика на разных платформах доступны для локального запуска.
Для Android в CI собирается только подписанный release APK.
Pull request запускает `verify`. Push в `codex/mvp` публикует rolling-релиз после
`verify`, тег `v*` — версионный релиз. Задания публикации используют готовую сборку
клиента и ZIP расширения из `verify`, без повторной сборки. Push остальных веток
не запускает CI.
```bash
npm install
npm run protocol:generate
npm run dev
```
Vite запускает браузерный UI на `http://localhost:5173`; API по умолчанию
слушает `http://127.0.0.1:4310`. До обращения к защищённым endpoint создайте
token единственного владельца:
```bash
npm run auth:generate -w @codexnest/server
```
Обычная проверка использует локальные fixtures и не обращается к OpenAI:
```bash
npm run format:check
npm run lint
npm run typecheck
npm test
npm run build
```
Реальный integration-набор app-server запускается только явно. Он обращается к настроенному
провайдеру модели, создаёт и удаляет временные сессии и проверяет как протокольный smoke path,
так и осмысленный следующий ход после переноса неизменённой нативной компактизации в чистый тред:
```bash
RUN_CODEX_INTEGRATION=1 npm run test:integration -w @codexnest/server
```
Чтобы дополнительно проверить полный сценарий на большой существующей сессии, укажите отдельный
флаг и путь к rollout. Тест сначала делает изолированный снимок, проверяет неизменность его размера,
mtime и inode, а затем удаляет только снимок и созданные им новые треды:
```bash
RUN_CODEX_INTEGRATION=1 \
RUN_CODEX_COMPACTION_ACCEPTANCE=1 \
CODEXNEST_COMPACTION_SOURCE_PATH=/absolute/path/to/rollout.jsonl \
npm run test:integration -w @codexnest/server
```
Собрать папку для load-unpacked и детерминированный Chrome ZIP:
```bash
npm run package:build -w @codexnest/extension
```
E2E-тест расширения с постоянным профилем Chromium:
```bash
npm exec -w @codexnest/extension -- playwright install chromium
NODE_ENV=test npm run test:e2e -w @codexnest/extension
```
## Установка и эксплуатация
Установка последней успешной rolling-сборки описана в
[быстром старте](#быстрый-старт) выше. Настройка и дальнейшая эксплуатация:
- [Развёртывание, конфигурация, обновление, backup и recovery](./deploy/DEPLOYMENT.md)
- [Сборка, подпись, сеть и уведомления Android](./apps/client/android/README.md)
- [Участие в разработке](./CONTRIBUTING.md)
- [Обновление скриншотов и обложек README](./docs/media/README.md)
## Лицензия
CodexNest распространяется по [Apache License 2.0](./LICENSE). Лицензии
встроенных шрифтов находятся рядом с font assets в
`apps/client/src/assets/fonts`.