01b20b5b78
## Summary
- Qualify OpenCode **2.1.3** (latest stable, 22 October) with the
existing locked **2.1.0 client/plugin** dependencies, and **recommend**
it.
- Keep the technical **minimum at 2.1.2**: nothing CodeNomad consumes
changed, so the minimum has no new reason to move.
- A 2.1.2 daemon stays ready and gets an optional upgrade offer. 2.1.3
is the `tested` version. Newer and custom labels keep authenticated
contract recognition.
- The reviewed-contract fast path lists 2.1.3 beside the 2.1.2 minimum.
- The recommended version is updated in the help (all ten locales), both
READMEs, `dev-docs/OPENCODE_COMPATIBILITY.md` and the architecture
skill.
## Contract review (v2.1.2 → v2.1.3, 66 commits)
- **Authenticated OpenAPI:** 119 → **121 paths**, 144 → **146
operations**. Every consumed operation is unchanged. The only changes:
- added `GET /api/experimental/voice/models`;
- added `POST /api/experimental/voice/session/{sessionID}/instructions`;
- an optional hosted `session.id` in the `POST
/api/experimental/voice/session` response.
None of these is on the instance proxy allowlist, so they stay closed.
- **Published declarations:** the client adds only `voice.models` /
`voice.instructions`. The schema changes only typing (agent `color`
decoding, `Durable` as a tagged union). The plugin is unchanged.
- **Windows managed services** move their default port from **45278 to
28894** ([#57428](https://github.com/anomalyco/opencode/pull/57428)).
CodeNomad discovers the daemon through the selected CLI's `service
status` and the service registration, and assumes no port.
- Live check: this machine's shared daemon was upgraded to 2.1.3 and
restarted on 28894, and the running CodeNomad desktop kept working
through it.
- **Core:** mostly refactors, plus behaviour fixes that the native
suites below exercise:
- compaction summary output limit;
- `keepID` validated as a message ID;
- MCP media kept out of attachments;
- only changed instruction entries resent;
- relative-directory V1 migration;
- legacy `apply_patch` permission mapped to `edit`.
## Isolated Windows qualification
Base: dev `333d73452`, rebased on `853b14f2f` (#1097) for the final UI
unit run; Node **24.20.0**; exact official CLI **2.1.3**; 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 (9/9):**
- history from **2.0.3, beta-19271, 2.0.32, 2.1.0, 2.1.1 and 2.1.2** to
2.1.3;
- Git degraded/init;
- temporary workspaces.
- **Installation (3/3), with the 2.1.3 recommendation:**
- fresh install of the 2.1.2 minimum;
- native **2.0.15 → 2.1.3** upgrade, after which the already-running
daemon keeps its PID and 2.0.15 version;
- explicit OpenCode **1.18.10 → 2.1.3** replacement.
- **After the recommendation change:**
- admission/transport/update/setup units **36/36**;
- full server **2,463 passed, 8 skipped**, no failure or cancellation;
- UI units **1,694/1,694** (with #1097);
- 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.
The UI unit run on `333d73452` itself had two failures, in
`instances-pending-compaction.test.ts` (`toast.dismiss is not a
function`). They come from #1096 and also fail on unmodified `dev`;
#1097 fixes that fixture.
This is Windows automation evidence. In CI, `latest` now resolves to
2.1.3: 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.
17 KiB
スタンドアロンサーバー
プロジェクトとツールがある場所で CodeNomad を実行し、ローカルまたはリモートからブラウザー UI を使います。バックエンドはファイルシステムへのアクセス、Git 操作、認証、イベント配信を提供します。会話と実行は OpenCode の共有サービスが管理し、ブラウザー切断時に停止する子サーバーではありません。
同じ UI で、複数プロジェクトタブとワークツリー、会話ファミリーとバックグラウンドのアクティビティ、範囲制限付きの履歴読み込み、検索、タイムライン移動、コマンドパレットとショートカット、ミッションを利用できます。ブラウザーやタブレットからアクセスしても、実行はホストから移りません。
ホストを準備する
- Node.js 24 LTS と npm をインストールします。リポジトリの固定ビルドランタイムは 24.20.0 です。デスクトップパッケージには Node/npm が含まれます。
- バックエンドプロセスの PATH に Git を配置します。WSL 内だけの Git では Windows バックエンドの要件を満たしません。
- OpenCode をインストールまたは選択します。必須の最低バージョンは 2.1.2、推奨検証対象は 2.1.3 です。新しい／カスタムビルドは、テスト済みバージョンの許可リストではなく、互換性チェックを受けます。OpenCode のセットアップを参照してください。
- サーバーを起動するフォルダーを選ぶか、
--workspace-rootを明示します。
Git がない場合、会話は明示的に開いた物理フォルダー内だけで利用でき、Git とワークツリー操作は失敗します。Git をインストールし、PATH 変更後にバックエンドを再起動してください。ワークスペースルートは開く／参照する範囲の制限であり、エージェント実行の制限ではありません。セキュリティを参照してください。
実行・インストール
インストール方法を 1 つ選びます。以下の初回起動例は、シェル履歴にパスワードを残さず、ローカル初期設定を使います。
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 を開きます。ローカル初期設定を完了し、永続的なサーバーパスワードを保存します。まだ HTTPS の信頼を設定していない場合に使える、ループバック専用 HTTP の初期設定方法も含まれています。
- 以後の起動では
--generate-tokenを省くか、毎回CODENOMAD_SERVER_PASSWORDを指定します。 codenomad --helpで、インストール済み CLI のオプションを確認します。
コマンドはフォアグラウンドで実行します。ターミナルを閉じるか Ctrl+C を送ると、そのバックエンドとリモートコントロール接続が停止します。--launch はブラウザーを開くだけで、サーバーをデーモン化しません。無人で利用可能にするには、設定、作業ディレクトリ、環境、再起動ポリシーを明示して、OS のプロセス／サービス管理機能から同じコマンドを実行してください。サービスログや公開されたユニットファイルに秘密情報を入れないでください。
ブラウザーを閉じても、別に稼働するスタンドアロンバックエンドは停止しません。プロジェクトタブを閉じるとそのプロジェクトの CodeNomad 接続は削除されますが、セッションは OpenCode で続き、プロジェクトを開き直すと再び確認できます。CodeNomad がネイティブの Location を解放することはありません。ウィンドウ全体を閉じる、終了する、再読み込みする場合は、復元のためにプロジェクト接続が保持されます。バックエンドの終了時も同様に OpenCode サービスは稼働したままです。CodeNomad が戻るまで、バックエンド依存の機能は利用できません。独立したネイティブのスケジュールの寿命は、ミッションを参照してください。
アドレスとポート
起動時に Local Connection URL、利用可能なら Remote Connection URL、該当する場合は Other Accessible URLs を表示します。推測したアドレスではなく、表示されたスキームとポートを使用してください。ループバック URL はそのマシンからしか到達できず、表示された LAN アドレスも経路とファイアウォールの許可が必要です。
HTTPS は 9898、HTTP は 9899 を優先します。ポート指定がなく優先ポートが使用中なら、OS 割り当てポートにフォールバックします。ゼロ以外のポートを明示した場合はフォールバックせず、0 は OS 割り当てを要求します。ポートは 0〜65535 の整数を受け付けます。
バックエンドは、ミッションなど自身の OpenCode プラグインのために、ランダムな 127.0.0.1 ポートで、通知されない認証付きの HTTP リスナーを開く場合もあります。このリスナーは表示されず、クライアントの接続先アドレスではありません。
リスナー公開、証明書、VPN/SSH、リバースプロキシは、直接リモートアクセスを参照してください。受信ポートなしのアクセスには、リモートコントロールを使用します。
公開 CLI リファレンス
フラグは対応する環境変数より優先します。値を取るフラグには表示した引数を指定し、スイッチには指定しません。HTTPS/HTTP の値は、大文字小文字を区別せず 1、true、yes、y、on を有効と認識します。明確にするため true／false を明示してください。UI 自動更新は 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 ループバックに正規化。IPv6 ゾーン識別子は拒否。バインド表を参照。 |
--https <enabled> |
CLI_HTTPS |
true。HTTPS リスナー。 |
--http <enabled> |
CLI_HTTP |
false。HTTP リスナー。最低 1 つのリスナーを有効にする必要があります。 |
--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 |
未設定。指定証明書用の任意の PEM CA チェーン。 |
--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 解決ではなく、その UI を配信。 |
--ui-dev-server <url> |
CLI_UI_DEV_SERVER |
未設定。HTTP リスナー経由で UI をプロキシ。開発には --https=false --http=true を使用。HTTPS リスナーは開発 UI をプロキシしません。 |
--ui-no-update |
CLI_UI_NO_UPDATE |
false。自動更新を上書きし、利用可能なキャッシュ／同梱 UI を使用。 |
--ui-auto-update <enabled> |
CLI_UI_AUTO_UPDATE |
true。起動時に互換性のあるリモート UI を確認。 |
--ui-manifest-url <url> |
CLI_UI_MANIFEST_URL |
https://ui.codenomad.neuralnomads.ai/version.json。リモート UI マニフェスト。 |
--launch |
CLI_LAUNCH |
false。起動後にローカル UI をブラウザーで開く。 |
--upgrade [version] |
— | 既定では更新なし。要求時は @neuralnomads/codenomad@latest または指定バージョンをグローバルインストールして終了。 |
公開リファレンスはユーザー向けオプションを列挙しています。デスクトップホストは非公開の起動調整を自ら管理します。
追加の配備用環境変数
| 変数 | 既定値と範囲 |
|---|---|
CODENOMAD_GITHUB_REPO |
NeuralNomadsAI/CodeNomad。リリース提示の問い合わせ先リポジトリ。 |
CODENOMAD_REMOTE_CONTROL_API |
未設定ならホスト型 OpenTunnel API。セルフホストのリレー配備には API オリジンを指定。 |
NODE_EXTRA_CA_CERTS |
Node の任意の追加 CA ファイル。OpenCode デーモンがないため起動する際、許可された起動環境とともに渡します。既に稼働中のデーモンは変更しません。 |
プロバイダー固有の使用量認証情報は、プロバイダーで説明しています。デスクトップのデータプロファイル選択はデスクトップを参照してください。リリースフィードで制御するものではありません。
設定とストレージの管理元
以下の既定パスはバックエンドユーザーのホームを使用します。--config でディレクトリを明示すると設定ベースが変わり、YAML ファイル名を指定すると、そのファイルと隣接する状態／ストレージが選ばれます。1 つの配備には意図した 1 つの設定識別を使用し、ディレクトリ全体を OS 権限で保護してください。
| 管理元／データ | 既定の場所または規則 |
|---|---|
| 安定した CodeNomad 設定 | ~/.config/codenomad/config.yaml |
| 可変の CodeNomad 状態 | ~/.config/codenomad/state.yaml |
| CodeNomad インスタンスのメタデータ | ~/.config/codenomad/instances/ |
| パスワードハッシュ | アクティブな YAML 設定の隣の auth.json。アプリ管理。 |
| 生成 TLS 証明書と秘密鍵 | 設定ベース配下の tls/。 |
| リモートコントロールのルート、有効化の選択、端末ハッシュ | 設定ベース配下の remote-control-devices.json。 |
| 一時ワークスペースの登録簿とフォルダー | 同ベース配下の temporary-workspaces.json と temporary-workspaces/。 |
| インストール済みパネル拡張機能と権限の記録 | 同ベース配下の panel-extensions/ と permission-receipts/。 |
| ダウンロードした UI キャッシュ | ~/.config/codenomad/ui/。独自の --config でも、CLI の UI リゾルバーはこのホーム基準のキャッシュを使用。 |
| OpenCode の会話、メッセージ、サービス登録、プロバイダー接続 | CodeNomad インスタンスディレクトリではなく、実行ホスト上の OpenCode 自身のグローバルストレージ。 |
| デスクトップの復元状態 | 既定は ~/.codenomad/client-state/v2/。プロファイル／ウィンドウの範囲はデスクトップを参照。 |
CodeNomad は既存の共有デーモンに接続し、なければ起動します。起動環境は新たに起動したデーモンだけに影響します。これとは別に、設定した完全なセッション環境は、各プロンプト、カスタムコマンド、セッションシェルリクエストの前に適用されます。設定を表示・編集するだけでは適用しません。OpenCode のセットアップを参照してください。
イベントと再接続
バックエンドは共有の OpenCode ネイティブイベントストリームを受信し、Server-Sent Events でワークスペースと CodeNomad のイベントをブラウザークライアントに多重配信します。配信はライブかつ一時的で、イベントの再生は保証されません。
再接続後、UI は正規のセッションと保留リクエストの状態を再取得します。ファイル／設定の無効化通知も、新たな読み取りを起こします。再接続は、応答が消失した送信、削除、回答、その他の変更操作を繰り返す許可ではありません。まず結果の状態を確認してください。復旧が不完全なら、既知の保留リクエストと下書きを保持します。権限とトラブルシューティングを参照してください。
プレビューパッケージと保守
プレビュー CLI パッケージを明示的に試すには：
npx @neuralnomads/codenomad-dev --generate-token --launch
CodeNomad 設定を分離する必要がある場合は、意図的に別の設定を使用してください。パッケージの選択では共有 OpenCode ストレージは分離されません。設定 → 情報 → 更新 → アップデートチャネル が制御するのは、提示されるリリースであり、バックエンドのデータ識別やインストール済みパッケージではありません。
codenomad --upgrade は、検出した npm/pnpm/bun（検出できなければ npm）で、グローバルの安定版 CLI パッケージを更新します。稼働中のサーバーの再起動や OpenCode の更新はしません。プロジェクトローカルやプレビューのインストールでは、その正確な npm パッケージを明示的に更新します。更新後は、管理している CodeNomad プロセスを意図的に再起動し、表示アドレスを再確認してください。