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.
14 KiB
Eigenständiger Server
Betreiben Sie CodeNomad dort, wo Ihre Projekte und Werkzeuge liegen, und verwenden Sie dessen Browseroberfläche lokal oder entfernt. Das Backend bietet Dateisystemzugriff, Git-Vorgänge, Authentifizierung und Ereigniszustellung. OpenCodes gemeinsamer Dienst verwaltet Unterhaltungen und Ausführung; er ist kein untergeordneter Server, der bei Browsertrennung gestoppt werden soll.
Dieselbe Oberfläche unterstützt mehrere Projekt-Tabs und Worktrees, Unterhaltungsfamilien und Hintergrundaktivität, begrenztes Verlaufsladen, Suche und Timeline-Navigation, Befehlspalette und Tastenkürzel sowie Missionen. Browser- und Tablet-Zugriff verlagern die Ausführung nicht vom Host.
Host vorbereiten
- Installieren Sie Node.js 24 LTS und npm; die festgelegte Build-Laufzeit des Repositorys ist 24.20.0. Desktop-Pakete enthalten Node/npm.
- Stellen Sie Git im PATH des Backend-Prozesses bereit. Git allein in WSL genügt für ein Windows-Backend nicht.
- Installieren oder wählen Sie OpenCode: Erforderliches Minimum ist 2.1.2, empfohlenes Qualifizierungsziel 2.1.3. Neuere/angepasste Builds durchlaufen Kompatibilitätsprüfungen, keine Positivliste getesteter Versionen. Siehe OpenCode-Einrichtung.
- Wählen Sie den Startordner des Servers oder übergeben Sie
--workspace-rootausdrücklich.
Ohne Git bleiben Unterhaltungen nur im ausdrücklich geöffneten physischen Ordner verfügbar; Git- und Worktree-Vorgänge schlagen fehl. Installieren Sie Git und starten Sie das Backend nach einer PATH-Änderung neu. Das Arbeitsbereichs-Stammverzeichnis begrenzt Öffnen/Durchsuchen, nicht Agentenausführung: siehe Sicherheit.
Ausführen oder installieren
Wählen Sie eine Installationsmethode. Diese Erststartbeispiele verwenden lokale Ersteinrichtung statt eines Passworts im Shell-Verlauf:
Mit npx ausführen
npx @neuralnomads/codenomad --generate-token --launch
Global installieren
npm install -g @neuralnomads/codenomad
codenomad --generate-token --launch
In einem Projekt installieren
npm install @neuralnomads/codenomad
npx codenomad --generate-token --launch
npx codenomad verwendet die im Projekt installierte Programmdatei, falls vorhanden. Dies installiert das Paket im Projekt; Konfiguration oder OpenCode-Speicher werden dadurch nicht projektlokal.
- Öffnen Sie die ausgegebene Local Connection URL auf dem Host. Schließen Sie die lokale Ersteinrichtung ab und speichern Sie dann ein dauerhaftes Serverpasswort. Dieses Verfahren enthält eine reine Loopback-HTTP-Einrichtungsoption, falls noch kein HTTPS-Vertrauen eingerichtet ist.
- Lassen Sie bei späteren Starts
--generate-tokenweg; alternativ übergeben Sie bei jedem StartCODENOMAD_SERVER_PASSWORD. - Prüfen Sie mit
codenomad --helpdie Optionen der installierten CLI.
Die Befehle laufen im Vordergrund. Terminal-Schließen oder Ctrl+C stoppt dieses Backend und dessen Fernsteuerungsverbindung. --launch öffnet nur einen Browser; es macht den Server nicht zum Daemon. Für unbeaufsichtigte Verfügbarkeit führen Sie denselben Befehl über Ihre OS-Prozess-/Dienstverwaltung mit expliziter Konfiguration, Arbeitsverzeichnis, Umgebung und Neustartrichtlinie aus. Schreiben Sie keine Geheimnisse in Dienstlogs oder öffentliche Unit-Dateien.
Browser-Schließen stoppt kein separat laufendes eigenständiges Backend. Das Schließen eines Projekt-Tabs entfernt die CodeNomad-Verbindung dieses Projekts, aber Sitzungen laufen in OpenCode weiter; öffnen Sie das Projekt erneut, um sie wiederzufinden. CodeNomad entlädt niemals seine native Location. Das Schließen eines ganzen Fensters, Beenden oder Neuladen bewahrt Projektverbindungen für die Wiederherstellung. Auch Backend-Ende lässt den OpenCode-Dienst laufen. Backend-abhängige Funktionen fehlen bis zur Rückkehr von CodeNomad; die separate Lebensdauer nativer Planung erläutert Missionen.
Adressen und Ports
Beim Start werden Local Connection URL, gegebenenfalls Remote Connection URL sowie bei Bedarf Other Accessible URLs ausgegeben. Verwenden Sie ausgegebenes Schema und Port, keine geratene Adresse. Eine Loopback-URL ist nur auf diesem Rechner erreichbar; eine ausgegebene LAN-Adresse benötigt weiterhin Routing und Firewallzugriff.
HTTPS bevorzugt Port 9898, HTTP 9899. Ohne Portüberschreibung wird bei belegtem bevorzugtem Port ein OS-zugewiesener Port verwendet. Ein expliziter Nichtnull-Port weicht nicht aus; 0 fordert einen OS-zugewiesenen Port. Ports akzeptieren Ganzzahlen von 0 bis 65535.
Das Backend kann außerdem einen nicht angekündigten, authentifizierten HTTP-Listener auf einem zufälligen 127.0.0.1-Port für seine eigenen OpenCode-Plugins wie Missionen öffnen. Er wird nicht ausgegeben und ist keine Client-Adresse.
Listenerfreigabe, Zertifikate, VPN/SSH und Reverse-Proxys erläutert Direkter Fernzugriff. Für Zugriff ohne eingehenden Port verwenden Sie Fernsteuerung.
Öffentliche CLI-Referenz
Flags übersteuern ihre Umgebungsentsprechungen. Flags mit Wert verwenden das gezeigte Argument; Schalter nicht. HTTPS-/HTTP-Werte erkennen 1, true, yes, y und on unabhängig von Groß-/Kleinschreibung als aktiviert; verwenden Sie zur Klarheit explizites true/false. Automatische UI-Updates erkennen 1, true und yes.
Strikt boolesche Umgebungsvariablen (CLI_UNRESTRICTED_ROOT, CLI_UI_NO_UPDATE, CLI_LAUNCH, CODENOMAD_GENERATE_TOKEN und CODENOMAD_SKIP_AUTH) aktivieren ihre Schalter mit 1, true, yes oder on; Groß-/Kleinschreibung und umgebende Leerzeichen werden ignoriert. 0, false, no, off, leere oder nur aus Leerzeichen bestehende Werte sowie nicht gesetzte Variablen lassen die Schalter aus. Jeder andere Wert verhindert den Serverstart, auch mit dem entsprechenden CLI-Flag. Ein CLI-Flag aktiviert seinen Schalter trotz eines gültigen Aus-Werts; andernfalls gelten die folgenden false-Standards.
| Flag | Umgebung | Standard und Wirkung |
|---|---|---|
-h, --help |
— | Hilfe ausgeben und beenden. |
-v, --version |
— | Installierte Paketversion ausgeben und beenden. |
--host <host> |
CLI_HOST |
127.0.0.1; localhost wird auf IPv4-Loopback normalisiert. IPv6-Zonenkennungen werden abgelehnt. Siehe Bindungsmatrix. |
--https <enabled> |
CLI_HTTPS |
true; HTTPS-Listener. |
--http <enabled> |
CLI_HTTP |
false; HTTP-Listener. Mindestens ein Listener muss aktiviert sein. |
--https-port <number> |
CLI_HTTPS_PORT |
9898 bevorzugt; 0 automatisch. |
--http-port <number> |
CLI_HTTP_PORT |
9899 bevorzugt; 0 automatisch. |
--tls-key <path> |
CLI_TLS_KEY |
Nicht gesetzt; privater PEM-Schlüssel, benötigt --tls-cert. |
--tls-cert <path> |
CLI_TLS_CERT |
Nicht gesetzt; PEM-Zertifikat, benötigt --tls-key. |
--tls-ca <path> |
CLI_TLS_CA |
Nicht gesetzt; optionale PEM-CA-Kette für bereitgestellte Zertifikate. |
--tlsSANs <list> |
CLI_TLS_SANS |
Nicht gesetzt; zusätzliche kommaseparierte DNS-Namen/IPs für erzeugte Zertifikate. |
--workspace-root <path> |
CLI_WORKSPACE_ROOT |
Prozessarbeitsverzeichnis; Wurzel zum Öffnen von Arbeitsbereichen. |
--unrestricted-root |
CLI_UNRESTRICTED_ROOT |
false; erlaubt das Durchsuchen des gesamten Dateisystems. Keine Agenten-Sandbox-Einstellung. |
--config <path> |
CLI_CONFIG |
Aufgelöster aktiver Standard: ~/.config/codenomad/config.yaml. Akzeptiert Verzeichnis oder YAML-Datei für expliziten Speicherort. |
--log-level <level> |
CLI_LOG_LEVEL |
info; dokumentierte Stufen: trace, debug, info, warn, error. |
--log-destination <path> |
CLI_LOG_DESTINATION |
stdout; sonst in die gewählte Datei schreiben. |
--username <username> |
CODENOMAD_SERVER_USERNAME |
codenomad; Laufzeit-Authentifizierungsbenutzername. Eine gespeicherte Auth-Datei behält ihren Benutzernamen ohne Laufzeit-Passwortüberschreibung. |
--password <password> |
CODENOMAD_SERVER_PASSWORD |
Nicht gesetzt; reines Laufzeitpasswort mit Vorrang vor der verwalteten Auth-Datei. |
--auth-cookie-name <name> |
CODENOMAD_AUTH_COOKIE_NAME |
codenomad_session; Zeichen außer Buchstaben, Ziffern, _ und - werden _. |
--generate-token |
CODENOMAD_GENERATE_TOKEN |
false; einmaliges lokales Ersteinrichtungstoken mit 60 Sekunden Gültigkeit ausgeben. |
--dangerously-skip-auth |
CODENOMAD_SKIP_AUTH |
false; deaktiviert Direkt-Listener-Authentifizierung. Gefährlich: siehe Sicherheit. Fernsteuerung benötigt weiterhin Gerätekopplung. |
--ui-dir <path> |
CLI_UI_DIR |
public-Verzeichnis des Pakets; explizite Überschreibung liefert diese Oberfläche statt entfernter UI-Auflösung. |
--ui-dev-server <url> |
CLI_UI_DEV_SERVER |
Nicht gesetzt; UI über den HTTP-Listener weiterleiten. Für Entwicklung --https=false --http=true verwenden; der HTTPS-Listener leitet die Entwicklungs-UI nicht weiter. |
--ui-no-update |
CLI_UI_NO_UPDATE |
false; übersteuert automatische Updates und verwendet verfügbare zwischengespeicherte/gebündelte UI. |
--ui-auto-update <enabled> |
CLI_UI_AUTO_UPDATE |
true; beim Start auf kompatible entfernte UI prüfen. |
--ui-manifest-url <url> |
CLI_UI_MANIFEST_URL |
https://ui.codenomad.neuralnomads.ai/version.json; entferntes UI-Manifest. |
--launch |
CLI_LAUNCH |
false; nach Start lokale UI im Browser öffnen. |
--upgrade [version] |
— | Standardmäßig kein Upgrade. Auf Anfrage @neuralnomads/codenomad@latest oder die angegebene Version global installieren und beenden. |
Die öffentliche Referenz listet benutzerseitige Optionen; Desktop-Hosts verwalten ihre eigene private Startkoordination.
Zusätzliche Bereitstellungsumgebung
| Variable | Standard und Geltungsbereich |
|---|---|
CODENOMAD_GITHUB_REPO |
NeuralNomadsAI/CodeNomad; Repository für Release-Angebote. |
CODENOMAD_REMOTE_CONTROL_API |
Nicht gesetzt: gehostete OpenTunnel-API. Für selbst gehostetes Relay eine API-Origin setzen. |
NODE_EXTRA_CA_CERTS |
Optionale zusätzliche CA-Datei von Node; wird mit zulässiger Startumgebung beim Start eines fehlenden OpenCode-Daemons übergeben. Ändert keinen bereits laufenden Daemon. |
Anbieterspezifische Nutzungszugangsdaten behandelt Anbieter. Desktop-Datenprofilauswahl beschreibt Desktop; der Release-Kanal steuert sie nicht.
Konfiguration und Speicherzuständigkeit
Die folgenden Standardpfade verwenden das Home des Backend-Benutzers. Ein explizites --config-Verzeichnis ändert die Konfigurationsbasis; ein YAML-Dateiname wählt diese Datei mit benachbartem Zustand/Speicher. Verwenden Sie eine bewusste Konfigurationsidentität pro Bereitstellung und schützen Sie das ganze Verzeichnis mit OS-Rechten.
| Eigentümer/Daten | Standardort oder Regel |
|---|---|
| Stabile CodeNomad-Einstellungen | ~/.config/codenomad/config.yaml |
| Veränderlicher CodeNomad-Zustand | ~/.config/codenomad/state.yaml |
| CodeNomad-Instanzmetadaten | ~/.config/codenomad/instances/ |
| Passwort-Hash | auth.json neben der aktiven YAML-Konfiguration; appverwaltet. |
| Erzeugte TLS-Zertifikate und private Schlüssel | tls/ unter der Konfigurationsbasis. |
| Fernsteuerungsroute, Aktivierungsauswahl und Geräte-Hashes | remote-control-devices.json unter der Konfigurationsbasis. |
| Register und Ordner temporärer Arbeitsbereiche | temporary-workspaces.json und temporary-workspaces/ unter dieser Basis. |
| Installierte Panel-Erweiterungen und Berechtigungsbelege | panel-extensions/ und permission-receipts/ unter dieser Basis. |
| Heruntergeladener UI-Cache | ~/.config/codenomad/ui/; der UI-Resolver der CLI verwendet diesen Home-basierten Cache auch bei angepasstem --config. |
| OpenCode-Unterhaltungen, Nachrichten, Dienstregistrierung und Anbieterverbindungen | OpenCodes eigener globaler Speicher auf dem Ausführungshost, nicht das CodeNomad-Instanzverzeichnis. |
| Desktop-Wiederherstellungszustand | Standard ~/.codenomad/client-state/v2/; Profil-/Fensterumfang siehe Desktop. |
CodeNomad verbindet sich mit dem vorhandenen gemeinsamen Daemon oder startet ihn, falls er fehlt. Die Startumgebung betrifft nur einen neu gestarteten Daemon. Separat wird die konfigurierte vollständige Sitzungsumgebung vor jedem Prompt, benutzerdefinierten Befehl oder Sitzungs-Shell-Aufruf angewandt, nicht beim bloßen Ansehen/Bearbeiten von Einstellungen. Siehe OpenCode-Einrichtung.
Ereignisse und Wiederverbindungen
Das Backend konsumiert einen gemeinsamen nativen OpenCode-Ereignisstrom und verteilt Arbeitsbereichs-/CodeNomad-Ereignisse per Server-Sent Events an Browser-Clients. Zustellung ist live und flüchtig: Es gibt keine garantierte Ereigniswiederholung.
Nach Wiederverbindung liest die Oberfläche maßgeblichen Sitzungs- und Anfragezustand erneut; Datei-/Konfigurationsinvalidierungen lösen ebenfalls frische Lesevorgänge aus. Wiederverbindung erlaubt kein erneutes Senden, Löschen, Antworten oder andere Änderungen mit verlorener Antwort. Prüfen Sie zuerst den Ergebniszustand. Bekannte offene Anfragen und Entwürfe bleiben bei unvollständiger Wiederherstellung erhalten; siehe Berechtigungen und Fehlerbehebung.
Vorschaupakete und Wartung
Um das CLI-Vorschaupaket explizit auszuprobieren:
npx @neuralnomads/codenomad-dev --generate-token --launch
Verwenden Sie für isolierte CodeNomad-Einstellungen bewusst eine separate Konfiguration; Paketauswahl isoliert keinen gemeinsamen OpenCode-Speicher. Einstellungen → Info → Updates → Update-Kanal steuert angebotene Releases, nicht Backend-Datenidentität oder installiertes Paket.
codenomad --upgrade aktualisiert das globale stabile CLI-Paket mit dem erkannten npm-/pnpm-/bun-Manager (npm, falls keiner erkannt wird). Es startet weder einen laufenden Server neu noch aktualisiert es OpenCode. Aktualisieren Sie bei projektlokaler oder Vorschauinstallation ausdrücklich genau dieses npm-Paket. Starten Sie den verwalteten CodeNomad-Prozess nach dem Update bewusst neu und prüfen Sie seine ausgegebenen Adressen erneut.
Desktop-Wartung siehe Updates, Quellcode-Build-Befehle Support und Anbieterplannutzung Anbieter.