CodeNomad Отдельный сервер
Запускайте 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 после обновления; снова проверьте напечатанные адреса.
Обслуживание настольного приложения см. в обновлениях, команды сборки — в поддержке, использование планов провайдеров — в провайдерах.