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.
6.2 KiB
Instalar CodeNomad
Elige un equipo de escritorio local o ejecuta el servidor independiente. En ambos casos, OpenCode es propietario del servicio nativo compartido y del historial.
Descargas de escritorio
- Abre la última versión.
- Elige la compilación que corresponda a tu sistema operativo y procesador.
- Extrae el ZIP o instala/ejecuta el paquete de la plataforma y, después, inicia CodeNomad.
| Plataforma | Versión Electron | Versión Tauri | Notas de la plataforma |
|---|---|---|---|
| macOS | ZIP, Intel o Apple Silicon | ZIP, Intel o Apple Silicon | El entorno de ejecución incluido requiere macOS 13.5 o posterior. |
| Windows | ZIP, x64 | Instalador, x64 | Windows 10 o posterior; Tauri usa WebView2. |
| Linux | Paquete Debian, x64 | AppImage, x64 | Compilado y probado en Ubuntu 24.04; no se garantiza la compatibilidad con distribuciones anteriores. |
Las versiones de escritorio incluyen los recursos de ejecución necesarios para el backend y el instalador de OpenCode, por lo que no necesitas instalar Node.js/npm por separado para usarlas. Git no está incluido. La automatización nativa del navegador es compatible con Electron y Tauri para Windows; las demás plataformas Tauri usan vistas previas iframe.
Si una descarga verificada se bloquea al iniciarse, consulta la solución de problemas de la plataforma. Nunca ejecutes un archivo de origen no fiable solo para eludir una advertencia.
Instalar en Linux
Desde la carpeta que contiene la versión descargada, sustituye la versión y el nombre de archivo por los reales:
sudo apt install ./CodeNomad-Electron-linux-x64-<version>.deb
Para la AppImage de Tauri:
chmod +x CodeNomad-Tauri-linux-x64-<version>.AppImage
./CodeNomad-Tauri-linux-x64-<version>.AppImage
Si FUSE no está disponible, usa el modo de extracción y ejecución de la AppImage:
./CodeNomad-Tauri-linux-x64-<version>.AppImage --appimage-extract-and-run
La instalación Debian de Electron configura el aislamiento de Chromium. No desactives ese aislamiento para solucionar un problema de instalación. Los problemas gráficos de Tauri en Linux tienen una solución específica de WebKit.
Requisitos
| Requisito | Dónde debe estar disponible | Requisito actual |
|---|---|---|
| CLI de OpenCode | Equipo de ejecución seleccionado, incluida la distribución WSL seleccionada cuando corresponda | Mínimo 2.1.2; 2.1.4 es la versión recomendada/verificada. Las versiones más nuevas o personalizadas pasan una validación de contratos en lugar de prohibirse por no haberse probado. |
| Git | PATH de la cuenta del backend de CodeNomad |
Necesario para la identidad del repositorio, las operaciones Git y los worktrees. |
| Node.js/npm | Equipo del servidor independiente y de compilación desde el código fuente | Node.js 24 LTS; las compilaciones reproducibles desde el código fuente usan .node-version (24.20.0). Incluido con los recursos de ejecución/instalación de escritorio. |
| Carpeta del espacio de trabajo | Disco accesible para el backend | Una carpeta física abierta explícitamente, no una carpeta local del dispositivo deducida por un navegador remoto. |
En Windows, instala Git for Windows con el acceso desde la línea de comandos/aplicaciones de terceros activado. Basta con una instalación por usuario en la que este pueda escribir. En macOS/Linux, sigue las instrucciones de Git para tu plataforma.
Después de cambiar PATH, sal completamente de la aplicación de escritorio y vuelve a iniciarla, o reinicia el backend independiente con la cuenta prevista. Recargar un navegador no actualiza el entorno del backend. Que Git esté disponible solo dentro de WSL no satisface el requisito de Git de un backend de Windows.
Sin Git, aún puedes abrir una carpeta física y usar conversaciones limitadas al directorio, incluso pedir ayuda de instalación al agente. Las operaciones de repositorio/worktree siguen sin estar disponibles; el acceso a las sesiones permanece limitado a esa carpeta exacta. CodeNomad informa al agente sobre la disponibilidad de Git en el backend antes de los mensajes/comandos personalizados y retira ese aviso tras la recuperación. El equipo de ejecución del agente puede ser distinto del equipo del backend, así que instala Git para el backend, no solo para el shell del agente.
Seleccionar OpenCode en el primer inicio
- Durante la configuración inicial, elige un ejecutable compatible existente o usa la acción de instalación de OpenCode ofrecida.
- Verifica el estado del entorno de ejecución antes de abrir un proyecto.
- Vuelve a Preferencias → OpenCode para gestionar por separado el ejecutable, la instalación y el servicio compartido.
CodeNomad prefiere ejecutables compatibles presentes en PATH y admite seleccionar explícitamente un ejecutable. Si PATH inicia un OpenCode anterior, la configuración ofrece reemplazar, previa confirmación, un OpenCode 1.x instalado con npm, o instalar OpenCode 2 para CodeNomad junto a una instalación hecha de otra forma, que nunca modifica; consulta la configuración de OpenCode. Instalar/actualizar una CLI no reinicia silenciosamente un servicio compartido que ya esté en ejecución. Consulta la configuración de OpenCode para conocer las consecuencias de reiniciar/recargar, WSL y el entorno de las sesiones.
Usar un navegador en su lugar
Instala Node.js/npm, Git y OpenCode en el equipo servidor y sigue los procedimientos de inicio del servidor. Conéctate con la dirección indicada, la autenticación configurada y un certificado de confianza. Un navegador/PWA necesita un backend activo; no es una copia sin conexión de tus proyectos.
Para puertos, direcciones de escucha y TLS, consulta acceso directo. Para emparejar un dispositivo sin abrir puertos entrantes, usa Control remoto. Para los comandos de desarrollo y empaquetado, consulta compilaciones desde el código fuente.