CodexNest

English · Русский

> **Репозиторий устарел.** 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 продолжает работать. Перезагрузка компьютера не требуется.

Ваше рабочее пространство Codex. На компьютере и телефоне.
Управляйте проектами и диалогами Codex CLI на своей Linux-машине из браузера или Android-приложения.

Быстрый старт · Как это работает · Скриншоты · Android APK · Документация

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 на этом хосте; файлы проектов, инструменты разработки и выполняемые задачи остаются там. [![Один headless Linux-сервер с Codex и CodexNest backend связан через приватную VPN или доверенную LAN с любым числом браузерных и Android-клиентов владельца](./docs/assets/how-it-works-ru.png)](./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-session.png) ### Следующий шаг всегда под рукой Выберите вариант ответа или напишите свой, пока следующее сообщение ждёт в очереди. В светлой и тёмной темах одинаковое расположение элементов управления. [![Светлая тема на компьютере: уточняющий вопрос и сообщение в очереди](./docs/assets/desktop-queue.png)](./docs/assets/desktop-queue.png) ### Сохраняйте контекст решений Отправленные ответы сохраняют полный вопрос рядом с вашим выбором, в одной парящей карточке. Вернитесь к диалогу, чтобы увидеть, о чём договорились и почему. [![Светлая тема на компьютере: отправленные ответы с полными вопросами в одной парящей карточке](./docs/assets/desktop-answers.png)](./docs/assets/desktop-answers.png) ### Проверьте, что стоит за ответом Откройте ход работы, чтобы посмотреть команды, результаты тестов и изменения файлов рядом с ответом. Раскрывайте отдельные записи, когда нужны подробности. [![Раскрытый ход работы на компьютере: команда проверки, результат тестов и изменения файла](./docs/assets/desktop-activity.png)](./docs/assets/desktop-activity.png) ### То же рабочее пространство на телефоне Откройте список сессий, чтобы переключаться между проектами и диалогами. Прочитайте план, продолжите сессию, ответьте на уточнение или откройте готовый отчёт. Здесь показан мобильный веб-интерфейс, который также используется внутри Android-приложения.

_{Переключайтесь между сессиями · Продолжайте диалог}

_{Принимайте решения · Читайте результат}

--- ## Граница безопасности 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-.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`.