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 במקום שבו נמצאים הפרויקטים והכלים, ואז השתמשו בממשק הדפדפן שלו מקומית או מרחוק. שרת הקצה מספק גישה למערכת הקבצים, פעולות Git, אימות ומסירת אירועים. השירות המשותף של OpenCode הוא הבעלים של השיחות וההרצה; הוא אינו שרת־בן שיש לעצור כשהדפדפן מתנתק.
אותו ממשק תומך ב־מספר לשוניות פרויקט ו־worktrees, ב־משפחות שיחה ופעילות רקע, ב־טעינת היסטוריה תחומה, חיפוש וניווט בציר הזמן, ב־לוח פקודות וקיצורים, וב־משימות. גישה מדפדפן ומטאבלט אינה מעבירה את ההרצה מהמארח.
הכנת המארח
- התקינו Node.js 24 LTS ו־npm; סביבת הבנייה המקובעת במאגר היא 24.20.0. חבילות שולחן העבודה כוללות Node/npm.
- הוסיפו Git ל־PATH של תהליך שרת הקצה. Git בתוך WSL בלבד אינו מספיק לשרת קצה ב־Windows.
- התקינו או בחרו OpenCode: המינימום הנדרש הוא 2.1.2, ו־2.1.3 היא הגרסה המומלצת לבדיקה. בניות חדשות או מותאמות עוברות בדיקות תאימות, לא רשימת היתר של גרסאות שנבדקו. ראו הגדרת 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 רק פותח דפדפן; הוא אינו הופך את השרת לדמון. לזמינות ללא השגחה, הריצו אותה פקודה במנהל תהליכים/שירותים של מערכת ההפעלה עם תצורה, תיקיית עבודה, סביבה ומדיניות הפעלה מחדש מפורשות. אל תכניסו סודות ליומני שירות או לקובץ יחידת שירות ציבורי.
סגירת דפדפן אינה עוצרת שרת קצה עצמאי הפועל בנפרד. סגירת לשונית פרויקט מסירה את חיבור CodeNomad של אותו פרויקט, אך הסשנים ממשיכים ב־OpenCode; פתחו את הפרויקט מחדש כדי למצוא אותם שוב. CodeNomad לעולם אינו פורק את ה־Location המקורי שלו. סגירת חלון שלם, יציאה או טעינה מחדש משמרות את חיבורי הפרויקטים לשחזור. גם כיבוי שרת הקצה משאיר את שירות OpenCode פועל. תכונות התלויות בשרת הקצה אינן זמינות עד חזרת CodeNomad; ראו משימות למשך החיים הנפרד של תזמון מקורי.
כתובות ויציאות
בהפעלה מודפסים Local Connection URL, ו־Remote Connection URL כשזמין, וכן Other Accessible URLs כשמתאים. השתמשו בסכמה וביציאה המודפסות, לא בכתובת מנוחשת. כתובת loopback נגישה רק באותו מחשב; כתובת 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 מנורמל ל־loopback של IPv4. מזהי אזור 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 המתארח בשירות. הגדירו מקור 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 המנוהל לאחר עדכון; בדקו שוב את כתובותיו המודפסות.
ראו עדכונים לתחזוקת שולחן העבודה, תמיכה לפקודות בנייה מקוד מקור, ו־ספקים לשימוש בתוכניות ספקים.