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.
5.2 KiB
Install CodeNomad
Choose a local desktop host or run the standalone server. In both cases, OpenCode owns the shared native service and history.
Desktop downloads
- Open the latest release.
- Choose the build matching your operating system and processor.
- Extract the ZIP or install/run the platform package, then launch CodeNomad.
| Platform | Electron release | Tauri release | Platform notes |
|---|---|---|---|
| macOS | ZIP, Intel or Apple Silicon | ZIP, Intel or Apple Silicon | macOS 13.5 or later is required by the bundled runtime. |
| Windows | ZIP, x64 | Installer, x64 | Windows 10 or later; Tauri uses WebView2. |
| Linux | Debian package, x64 | AppImage, x64 | Built and tested on Ubuntu 24.04; compatibility with older distributions is not guaranteed. |
Desktop releases include the runtime resources needed by the backend and OpenCode installer, so you do not need a separate Node.js/npm installation to use them. Git is not bundled. Native browser automation is supported in Electron and Windows Tauri; other Tauri platforms use iframe previews.
For a verified download blocked at launch, see platform troubleshooting. Never run an untrusted archive merely to bypass a warning.
Install on Linux
From the folder containing your downloaded release, substitute its actual version and filename:
sudo apt install ./CodeNomad-Electron-linux-x64-<version>.deb
For the Tauri AppImage:
chmod +x CodeNomad-Tauri-linux-x64-<version>.AppImage
./CodeNomad-Tauri-linux-x64-<version>.AppImage
If FUSE is unavailable, use the AppImage's extraction-and-run mode:
./CodeNomad-Tauri-linux-x64-<version>.AppImage --appimage-extract-and-run
The Electron Debian installation configures Chromium's sandbox. Do not disable the sandbox as an installation workaround. Linux Tauri graphics issues have a targeted WebKit workaround.
Requirements
| Requirement | Where it must be available | Current requirement |
|---|---|---|
| OpenCode CLI | Selected execution host, including the selected WSL distribution where applicable | Minimum 2.1.2; 2.1.3 is the recommended/qualified target. Newer or custom versions undergo contract validation rather than an untested-version ban. |
| Git | CodeNomad backend account's PATH |
Required for repository identity, Git operations and worktrees. |
| Node.js/npm | Standalone-server and source-build host | Node.js 24 LTS; reproducible source builds use .node-version (24.20.0). Bundled with desktop runtime/installation resources. |
| Workspace folder | Backend-accessible disk | An explicitly opened physical folder, not a device-local folder inferred by a remote browser. |
On Windows, install Git for Windows with command-line/third-party access enabled. A user-writable, per-user installation is sufficient. On macOS/Linux, use Git's platform instructions.
After changing PATH, fully quit and relaunch the desktop app, or restart the standalone backend under the intended account. Reloading a browser does not update the backend environment. Git available only inside WSL does not satisfy a Windows backend's Git requirement.
Without Git, you can still open a physical folder and use directory-only conversations, including asking the agent for installation help. Repository/worktree operations remain unavailable; session access stays limited to that exact folder. CodeNomad tells the agent about backend Git availability before prompts/custom commands and removes that advisory after recovery. The agent's execution host can differ from the backend host, so install Git for the backend, not only for the agent's shell.
Select OpenCode on first launch
- In setup, choose a compatible existing executable or use the offered OpenCode installation action.
- Verify the runtime status before opening a project.
- Revisit Preferences → OpenCode to manage the executable, installation and shared service separately.
CodeNomad prefers compatible executables on PATH and supports an explicitly selected executable. If PATH starts an older OpenCode, setup offers to replace an npm-installed OpenCode 1.x after confirmation, or to install OpenCode 2 for CodeNomad beside an installation made another way, which it never modifies; see OpenCode setup. Installing/updating a CLI does not silently restart an already running shared service. See OpenCode setup for restart/reload consequences, WSL and session environment.
Use a browser instead
Install Node.js/npm, Git and OpenCode on the server host, then use the server launch procedures. Connect with the printed address, configured authentication and a trusted certificate. A browser/PWA needs a live backend; it is not an offline copy of your projects.
For ports, bindings and TLS, use direct access. To pair a device without opening inbound ports, use Remote Control. For development and packaging commands, see source builds.