39c0fa5833
## Summary
- Qualify OpenCode **2.1.4** (latest stable, 23 October) with the
existing locked **2.1.0 client/plugin** dependencies, and **recommend**
it.
- Keep the technical **minimum at 2.1.2**: no consumed contract changed,
so the minimum has no new reason to move.
- 2.1.2 and 2.1.3 daemons stay ready and get an optional upgrade offer.
2.1.4 is the `tested` version. Newer and custom labels keep
authenticated contract recognition.
- The reviewed-contract fast path lists the 2.1.2 minimum and the 2.1.4
target.
- The recommended version is updated in the help (all ten locales), both
READMEs, `CONTRIBUTING.md`, `dev-docs/OPENCODE_COMPATIBILITY.md` and the
architecture skill.
## Contract review (v2.1.3 → v2.1.4, 72 commits)
- **Authenticated OpenAPI:** 121 → **124 paths**, 146 → **149
operations**. No operation changed. The changes:
- added `POST /api/experimental/client-mcp/token`;
- added `GET /api/experimental/client-mcp` (WebSocket);
- added `POST /api/debug/heap-dump`;
- `Config.InfoEncoded` gains the opt-in
`experimental.background_compaction`.
The session event (`V2EventEncoded`) and message schemas are unchanged.
None of the new routes is on the instance proxy allowlist, and the proxy
relays WebSockets only for SideCars and previews.
- **Published declarations:**
- the client adds `mcp.client.token` and `debug.heapDump`;
- the schema and plugin changes are type refactors and unused-export
removals, among them `SessionID.descending`, `SessionEvent.Source` and
`PromptInput.FileAttachment.create`; `Session.Message.ID.fromEvent` now
takes any string instead of an event ID. CodeNomad uses none of these,
and every host module its native plugin bundles import
(`@opencode/plugin`, `/effect`, `/promise/adapter`, `/rpc`,
`@opencode/schema/location`, `/session`) still exists.
- **MCP elicitation forms**
([#58184](https://github.com/anomalyco/opencode/pull/58184)): an MCP
server asking for input during a tool call now creates a global-session
Form whose `form.created` event carries the server's location.
CodeNomad's live path requires that location for global Forms and shows
them as a **Project request**. Review found that the live path dropped
the location from the queued Form, so its reply lacked
`x-opencode-directory` and failed for a worktree or subdirectory until a
pending-request rescan. **#1127** fixes that; recovery already kept it.
A native probe (minimal stdio MCP server, a real Code Mode `execute`
call, CodeNomad-style reply) gives:
| Runtime | Form listed for the location | `form.created` carries the
location | Reply completes the tool |
| --- | --- | --- | --- |
| 2.1.3 | yes | **no** | yes |
| 2.1.4 | yes | **yes** | yes (`action: accept`, `channel: stable`) |
On 2.1.3 such a request only appeared after a pending-request rescan; on
2.1.4 it appears live. The probe sends the location header itself, so it
checks the runtime contract; #1127 covers CodeNomad's live reply path.
- **Other changes** are covered by the native suites below:
- compaction (oldest-first shortening, ignored buffers, overflow
detection);
- the agent's model for sessions without one;
- V2 agent files;
- V1 global-session import attribution;
- MCP lifecycle fixes.
- **Live check:** this machine's shared daemon runs 2.1.4, and the
CodeNomad desktop session works through it.
## Isolated Windows qualification
Base: dev `9ac792fff`; Node **24.20.0**; exact official CLI **2.1.4**;
unchanged locked client/plugin **2.1.0**.
- **Build and checks:** production server/UI/native plugin builds,
server and root typechecks, native bundle guard.
- **Native runtime (9/9):**
- Code Mode job ordering, plugin runtime, automation;
- complete pruning, history, ownership, worktree and event relay;
- loaded-only pending snapshot;
- Missions contract, family control, native and Compare/Wayfinder
trajectory.
- **Sessions (15/15):** environment, fork, aside, interrupt, lifecycle,
blank cleanup, prompt skills, provider usage/accounts/selection, service
usage, web search, plugin packages, output limit, Promise-tool failure.
- **Recurring (5/5):** all **11 recurring Mission journeys**, subagent
depth, **2 MiB** compaction, permission receipts.
- **Migrations (10/10):**
- history from **2.0.3, beta-19271, 2.0.32, 2.1.0, 2.1.1, 2.1.2 and
2.1.3** to 2.1.4;
- Git degraded/init;
- temporary workspaces.
- **Installation (3/3), with the 2.1.4 recommendation:**
- fresh install of the 2.1.2 minimum;
- native **2.0.15 → 2.1.4** upgrade, after which the already-running
daemon keeps its PID and 2.0.15 version;
- explicit OpenCode **1.18.10 → 2.1.4** replacement.
- **After the recommendation change:**
- admission, transport, update, installation and instance proxy units
**116 passed, 1 POSIX-only skipped**;
- full server **2,471 passed, 8 skipped**, no failure or cancellation;
- UI units **1,699/1,699**;
- focused browser **126/126**;
- native pruning with the real rendered UI;
- the exact CI invocation of the Code Mode regression (without tsx);
- ten-locale help checks (**9/9**).
This is Windows automation evidence. In CI, `latest` resolves to 2.1.4:
the compatibility job runs the native suites against the minimum and
latest on Windows, and the migration and Git-degraded certification runs
them on Ubuntu, Windows and macOS. WSL, packaged desktop,
installers/updater end-to-end and real mobile devices keep their
separate release gates.
22 KiB
Отдельный сервер
Запускайте CodeNomad там, где находятся проекты и инструменты, затем используйте браузерный интерфейс локально или удалённо. Серверная часть обеспечивает доступ к файловой системе, операции Git, аутентификацию и доставку событий. Общая служба OpenCode владеет разговорами и выполнением; это не дочерний сервер, останавливаемый при отключении браузера.
Тот же интерфейс поддерживает несколько вкладок проектов и worktree, семейства разговоров и фоновую активность, ограниченную загрузку истории, поиск и таймлайн, палитру команд и горячие клавиши, а также миссии. Доступ с браузера или планшета не переносит выполнение с хоста.
Подготовка хоста
- Установите Node.js 24 LTS и npm; закреплённая среда сборки репозитория — 24.20.0. Настольные пакеты включают Node/npm.
- Добавьте Git в PATH процесса серверной части. Одного Git внутри WSL недостаточно для серверной части Windows.
- Установите или выберите OpenCode: минимум 2.1.2, рекомендуемая проверенная цель — 2.1.4. Новые или пользовательские сборки проходят проверку совместимости, а не список разрешённых проверенных версий. См. настройку OpenCode.
- Выберите папку запуска сервера или явно передайте
--workspace-root.
Без Git разговоры доступны только в явно открытой физической папке; операции Git и worktree не работают. Установите Git и перезапустите серверную часть после изменения PATH. Корень рабочего пространства ограничивает открытие/просмотр, не выполнение агента: см. безопасность.
Запуск или установка
Выберите один способ установки. Примеры первого запуска используют локальную начальную настройку вместо записи пароля в историю оболочки:
Запуск через npx
npx @neuralnomads/codenomad --generate-token --launch
Глобальная установка
npm install -g @neuralnomads/codenomad
codenomad --generate-token --launch
Установка в проект
npm install @neuralnomads/codenomad
npx codenomad --generate-token --launch
npx codenomad использует установленный исполняемый файл проекта, если он есть. Это устанавливает пакет в проект; не делает конфигурацию или хранилище OpenCode локальными для проекта.
- Откройте напечатанный Local Connection URL на хосте. Выполните локальную начальную настройку, затем сохраните постоянный пароль сервера. Процедура включает вариант HTTP только на loopback, если доверие HTTPS ещё не настроено.
- При последующих запусках уберите
--generate-token; альтернатива — передавайтеCODENOMAD_SERVER_PASSWORDпри каждом запуске. - Используйте
codenomad --helpдля просмотра параметров установленного CLI.
Команды работают на переднем плане. Закрытие терминала или Ctrl+C останавливает серверную часть и её удалённое управление. --launch только открывает браузер; не превращает сервер в демон. Для доступности без присмотра запускайте ту же команду через менеджер процессов/служб ОС с явными конфигурацией, рабочим каталогом, окружением и политикой перезапуска. Не помещайте секреты в логи службы или публичный unit-файл.
Закрытие браузера не останавливает отдельно работающую серверную часть. Закрытие вкладки проекта убирает подключение CodeNomad к этому проекту, но сессии продолжают работать в OpenCode; откройте проект снова, чтобы найти их. CodeNomad никогда не выгружает его нативную Location. Закрытие всего окна, выход или перезагрузка сохраняют подключения проектов для восстановления. Завершение серверной части тоже оставляет службу OpenCode работающей. Зависимые от серверной части функции недоступны до возврата CodeNomad; отдельное время жизни нативного расписания описано в миссиях.
Адреса и порты
При запуске печатаются Local Connection URL, Remote Connection URL, если доступен, и Other Accessible URLs, когда применимо. Используйте напечатанную схему и порт, не угаданный адрес. Loopback-URL доступен только на этом компьютере; напечатанный LAN-адрес всё равно требует маршрутизации и доступа через брандмауэр.
HTTPS предпочитает порт 9898, HTTP — 9899. Без переопределения занятый предпочтительный порт заменяется назначенным ОС. Явный ненулевой порт не заменяется; 0 запрашивает назначение ОС. Порты принимают целые от 0 до 65535.
Серверная часть также может открыть необъявляемый HTTP-слушатель с аутентификацией на случайном порту 127.0.0.1 для собственных плагинов OpenCode, например миссий. Он не печатается и не является адресом для клиентов.
Доступность слушателей, сертификаты, VPN/SSH и обратные прокси описаны в прямом удалённом доступе. Для доступа без входящего порта используйте удалённое управление.
Общедоступный справочник CLI
Флаги имеют приоритет над соответствующими переменными окружения. Флаги со значением используют показанный аргумент; переключатели — нет. HTTPS/HTTP распознают 1, true, yes, y и on как включение без учёта регистра; для ясности используйте явные true/false. Автообновление интерфейса распознаёт 1, true и yes.
Переменные окружения со строгими булевыми значениями (CLI_UNRESTRICTED_ROOT, CLI_UI_NO_UPDATE, CLI_LAUNCH, CODENOMAD_GENERATE_TOKEN и CODENOMAD_SKIP_AUTH) включают свои переключатели при 1, true, yes или on, без учёта регистра и пробельных символов по краям. 0, false, no, off, пустые значения или значения только из пробельных символов, а также отсутствие переменной оставляют переключатели выключенными. Любое другое значение запрещает запуск сервера, даже с соответствующим флагом CLI. Флаг CLI включает переключатель вопреки допустимому выключающему значению; иначе действуют значения по умолчанию false, указанные ниже.
| Флаг | Окружение | Значение по умолчанию и эффект |
|---|---|---|
-h, --help |
— | Напечатать справку и выйти. |
-v, --version |
— | Напечатать версию установленного пакета и выйти. |
--host <host> |
CLI_HOST |
127.0.0.1; localhost нормализуется в IPv4 loopback. Идентификаторы зоны IPv6 отклоняются. См. матрицу привязок. |
--https <enabled> |
CLI_HTTPS |
true; HTTPS-слушатель. |
--http <enabled> |
CLI_HTTP |
false; HTTP-слушатель. Хотя бы один должен быть включён. |
--https-port <number> |
CLI_HTTPS_PORT |
Предпочтительно 9898; 0 автоматически. |
--http-port <number> |
CLI_HTTP_PORT |
Предпочтительно 9899; 0 автоматически. |
--tls-key <path> |
CLI_TLS_KEY |
Не задан; закрытый ключ PEM, требует --tls-cert. |
--tls-cert <path> |
CLI_TLS_CERT |
Не задан; сертификат PEM, требует --tls-key. |
--tls-ca <path> |
CLI_TLS_CA |
Не задан; необязательная цепочка CA PEM для переданных сертификатов. |
--tlsSANs <list> |
CLI_TLS_SANS |
Не задан; дополнительные DNS-имена/IP через запятую для генерируемых сертификатов. |
--workspace-root <path> |
CLI_WORKSPACE_ROOT |
Рабочий каталог процесса; корень открытия рабочих пространств. |
--unrestricted-root |
CLI_UNRESTRICTED_ROOT |
false; разрешить просмотр всей файловой системы. Не настройка песочницы агента. |
--config <path> |
CLI_CONFIG |
Итоговый активный путь по умолчанию: ~/.config/codenomad/config.yaml. Принимает каталог или YAML-файл для явного размещения. |
--log-level <level> |
CLI_LOG_LEVEL |
info; документированные уровни: trace, debug, info, warn, error. |
--log-destination <path> |
CLI_LOG_DESTINATION |
stdout; иначе писать в выбранный файл. |
--username <username> |
CODENOMAD_SERVER_USERNAME |
codenomad; имя пользователя для аутентификации, переданное при запуске. Сохранённый файл аутентификации сохраняет своё имя пользователя, если при запуске не передан другой пароль. |
--password <password> |
CODENOMAD_SERVER_PASSWORD |
Не задан; пароль, действующий только в текущем процессе, имеет приоритет над управляемым файлом аутентификации. |
--auth-cookie-name <name> |
CODENOMAD_AUTH_COOKIE_NAME |
codenomad_session; символы кроме букв, цифр, _ и - заменяются на _. |
--generate-token |
CODENOMAD_GENERATE_TOKEN |
false; напечатать одноразовый локальный токен настройки на 60 секунд. |
--dangerously-skip-auth |
CODENOMAD_SKIP_AUTH |
false; отключает аутентификацию прямых слушателей. Опасно: см. безопасность. Удалённому управлению всё ещё нужно сопряжение. |
--ui-dir <path> |
CLI_UI_DIR |
Каталог public пакета; явное переопределение предоставляет этот интерфейс вместо удалённого разрешения интерфейса. |
--ui-dev-server <url> |
CLI_UI_DEV_SERVER |
Не задан; проксирует интерфейс через HTTP-слушатель. Для разработки используйте --https=false --http=true; HTTPS-слушатель не проксирует интерфейс разработки. |
--ui-no-update |
CLI_UI_NO_UPDATE |
false; переопределяет автообновление и использует доступный кэшированный/встроенный интерфейс. |
--ui-auto-update <enabled> |
CLI_UI_AUTO_UPDATE |
true; проверять совместимый удалённый интерфейс при запуске. |
--ui-manifest-url <url> |
CLI_UI_MANIFEST_URL |
https://ui.codenomad.neuralnomads.ai/version.json; манифест удалённого интерфейса. |
--launch |
CLI_LAUNCH |
false; открыть локальный интерфейс в браузере после запуска. |
--upgrade [version] |
— | По умолчанию без обновления. По запросу глобально установить @neuralnomads/codenomad@latest или переданную версию и выйти. |
Общедоступный справочник перечисляет пользовательские параметры; настольные хосты сами управляют внутренней координацией запуска.
Дополнительное окружение развёртывания
| Переменная | Значение по умолчанию и область |
|---|---|
CODENOMAD_GITHUB_REPO |
NeuralNomadsAI/CodeNomad; репозиторий предложений релизов. |
CODENOMAD_REMOTE_CONTROL_API |
Не задана: размещённый API OpenTunnel. Укажите origin API для собственного ретранслятора. |
NODE_EXTRA_CA_CERTS |
Необязательный дополнительный файл CA Node; передаётся с разрешённым окружением запуска при запуске отсутствующего демона OpenCode. Не меняет уже работающий демон. |
Учётные данные использования провайдеров описаны в провайдерах. Выбор настольного профиля данных описан в настольном приложении, а не управляется каналом релизов.
Владение конфигурацией и хранилищем
Пути ниже используют домашний каталог пользователя серверной части. Явный каталог --config меняет базу конфигурации; имя YAML выбирает этот файл с соседними состоянием/хранилищем. Используйте одну намеренную идентичность конфигурации для развёртывания и защитите весь каталог правами ОС.
| Владелец/данные | Размещение по умолчанию или правило |
|---|---|
| Постоянные настройки CodeNomad | ~/.config/codenomad/config.yaml |
| Изменяемое состояние CodeNomad | ~/.config/codenomad/state.yaml |
| Метаданные экземпляров CodeNomad | ~/.config/codenomad/instances/ |
| Хэш пароля | auth.json рядом с активной конфигурацией YAML; управляется приложением. |
| Генерируемые сертификаты TLS и закрытые ключи | tls/ в базе конфигурации. |
| Маршрут удалённого управления, выбор включения и хэши устройств | remote-control-devices.json в базе конфигурации. |
| Реестр и папки временных рабочих пространств | temporary-workspaces.json и temporary-workspaces/ в этой базе. |
| Установленные расширения панели и квитанции разрешений | panel-extensions/ и permission-receipts/ в этой базе. |
| Кэш загруженного интерфейса | ~/.config/codenomad/ui/; разрешение интерфейса CLI использует этот домашний кэш даже с пользовательским --config. |
| Разговоры, сообщения, регистрация службы и подключения провайдеров OpenCode | Собственное глобальное хранилище OpenCode на хосте выполнения, не каталог экземпляра CodeNomad. |
| Состояние восстановления настольного приложения | По умолчанию ~/.codenomad/client-state/v2/; область профиля/окна см. в настольном приложении. |
CodeNomad подключается к существующему общему демону или запускает отсутствующий. Окружение запуска влияет только на новый демон. Отдельно полное настроенное окружение сессии применяется перед каждым запросом, пользовательской командой или запросом оболочки сессии, не при простом просмотре/изменении настроек. См. настройку OpenCode.
События и переподключения
Серверная часть читает общий нативный поток OpenCode и мультиплексирует события рабочего пространства и CodeNomad браузерным клиентам через Server-Sent Events. Доставка живая и недолговечная: гарантированного повтора событий нет.
После переподключения интерфейс заново читает достоверное состояние сессий и ожидающих запросов; инвалидирование файлов/конфигурации тоже запускает чтения. Переподключение не разрешает повторять отправку, удаление, ответ или другое изменение с потерянным ответом. Сначала проверьте результат. При неполном восстановлении известные ожидающие запросы и черновики сохраняются; см. разрешения и устранение неполадок.
Предварительные пакеты и обслуживание
Для явного испытания предварительного пакета CLI:
npx @neuralnomads/codenomad-dev --generate-token --launch
Используйте намеренно отдельную конфигурацию для изоляции настроек CodeNomad; выбор пакета не изолирует общее хранилище OpenCode. Настройки → Информация → Обновления → Канал обновлений управляет предлагаемыми релизами, не идентичностью данных серверной части или установленным пакетом.
codenomad --upgrade обновляет глобальный стабильный пакет CLI обнаруженным менеджером npm/pnpm/bun (npm, если не обнаружен). Он не перезапускает работающий сервер и не обновляет OpenCode. Для локальной проектной или предварительной установки явно обновляйте именно этот npm-пакет. Осознанно перезапустите управляемый процесс CodeNomad после обновления; снова проверьте напечатанные адреса.
Обслуживание настольного приложения см. в обновлениях, команды сборки — в поддержке, использование планов провайдеров — в провайдерах.