CLI של cc_server

כל דגל תהליך נקבע על ידי דגל CLI או משתנה סביבה; הדגל מנצח, אחריו הסביבה, ואחר כך ברירת המחדל. פרטי גישה של צד שלישי הם היוצא מן הכלל — ראו בהמשך.

ליבה

דגל	משתנה סביבה	ברירת מחדל	משמעות
`--data-dir`	`CC_SERVER_DATA_DIR`	תיקיית נתוני היישום לכל משתמש של מערכת ההפעלה (ראו בהמשך)	מסדי נתונים, סודות, מודלים ומדיה במטמון
`--port`	`CC_SERVER_PORT`	`9030`	פורט TCP (`0` = ארעי)
`--bind`	`CC_SERVER_BIND`	`loopback`	`loopback`, או `any`/`all`/`0.0.0.0` עבור כל ממשק (דורש TLS או `--insecure`)
`--repo-roots`	`CC_SERVER_REPO_ROOTS`	תיקיית הבית של משתמש השרת	ספריות בסיס מופרדות בפסיקים שלקוח רשאי לעיין בהן בעת רישום מאגר. עיון מעל ספריית בסיס נדחה
`--log-level`	`CC_SERVER_LOG_LEVEL`	`warning`	`debug`, `info`, `warning` או `error`. שורות העלייה והמוכנות תמיד מודפסות
`--server-name`	`CC_SERVER_NAME`	שם המארח של המכונה	השם שמוצג בבוררים, בגילוי ובמשטחי הצימוד

נגישות ו-TLS

דגל	משתנה סביבה	ברירת מחדל	משמעות
`--tls-cert`	`CC_SERVER_TLS_CERT`	לא מוגדר	שרשרת תעודות PEM. מגיש `wss://` בתוך התהליך כשהוא מוגדר יחד עם המפתח
`--tls-key`	`CC_SERVER_TLS_KEY`	לא מוגדר	מפתח פרטי PEM תואם לתעודה
`--insecure`	`CC_SERVER_INSECURE`	כבוי	מתיר אגדה בטקסט גלוי שאינה לולאה מקומית. רק מאחורי פרוקסי שמסיים TLS ברשת מהימנת; מתעלמים ממנו כש-TLS מוגדר
`--public-url`	`CC_SERVER_PUBLIC_URL`	נגזרת מהאגדה	כתובת ה-RPC שהשרת הזה מפרסם ללקוחות מצומדים. הגדירו אותה במפורש מאחורי פרוקסי, NAT או מנהרה — ברירת המחדל היא רק ניחוש של האגדה המקומית
`--allowed-origins`	`CC_SERVER_ALLOWED_ORIGINS`	`https://app.usectrl.dev`	מקורות דפדפן מופרדים בפסיקים שמורשים לחייג אל `/rpc` ממקור חוצה. לולאה מקומית ולקוחות נייטיביים תמיד מותרים
`--web-client-url`	`CC_SERVER_WEB_CLIENT_URL`	לא מוגדר	המקור של לקוח הווב המתארח שחזרות הכניסה המאוחדת חוזרות אליו
`--signaling-url`	`CC_SERVER_SIGNALING_URL`	`wss://signaling.usectrl.dev`	מתווך הממסר שהשרת הזה מצטרף אליו כדי שטלפון יוכל להגיע אליו בלי נתיב ישיר
`--mdns`	`CC_SERVER_MDNS`	`auto`	פרסום ב-LAN: `auto` (רק כשהאגדה חורגת מהלולאה המקומית), `on`, `off`. הגילוי מפרסם רק את הקיום — הצטרפות עדיין דורשת צימוד
`--tunnel`	`CC_SERVER_TUNNEL`	`off`	ספק מנהרה מנוהלת: `off`, `cloudflared`, `ngrok`, `tailscale`. חשיפה פומבית היא הסכמה מפורשת
`--tunnel-binary`	`CC_SERVER_TUNNEL_BINARY`	נפתר מ-`PATH`	נתיב מפורש לבינארי המנהרה
`--tunnel-sha256`	`CC_SERVER_TUNNEL_SHA256`	לא מוגדר	ה-SHA-256 הצפוי של אותו בינארי, מאומת לפני כל הפעלה
`--tunnel-args`	`CC_SERVER_TUNNEL_ARGS`	ריק	ארגומנטים נוספים מופרדים בפסיקים להפעלת המנהרה

אינדוקס ופרטי גישה של צד שלישי

דגל	משתנה סביבה	ברירת מחדל	משמעות
`--sandbox`	`CC_SERVER_SANDBOX`	`on`	האם הרצות סוכן נעטפות בארגז החול הנייטיבי של מערכת ההפעלה המארחת כשהוא זמין. בחירה לוותר, לא הפעלה — ראו בהמשך
`--code-index`	`CC_SERVER_CODE_INDEX`	`on`	מפסק חירום בשטח לאינדוקס גרף הקוד ברקע. `off` עולה נקי בלי בנייה מחדש
`--code-index-defer`	`CC_SERVER_CODE_INDEX_DEFER`	`15`	שניות להחזיק את סבב האינדוקס הראשון אחרי באנר המוכנות (מוגבל ל-0–300)
`--tool-deferral`	`CC_SERVER_TOOL_DEFERRAL`	`on`	האם הרצות רתמה שולחות קבוצה תושבת קטנה של כלים בתוספת מדד שמות, וטוענות את השאר בשימוש הראשון. ראו בהמשך
`--credential-gate`	`CC_SERVER_CREDENTIAL_GATE`	`900`	שניות שבהן הרצה חונה בהמתנה שאדם יתקן פרטי גישה שאינם יכולים לשרת אותה (מוגבל ל-0–3600). ראו בהמשך

ערך ריק של פרטי גישה נקרא ככזה שאינו מוגדר, ולכן נסיגת ברירת המחדל המובנית עדיין חלה. בנייה מקוד מקור אינה כוללת מלכתחילה שום פרטי גישה מובנים.

Google Calendar ובורר ה-GIF של Klipy הם דרך הסביבה בלבד — אין דגל --google-client-id / --klipy-app-key (דגלים לא מוכרים מדולגים). הגדירו GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET, ו-KLIPY_APP_KEY, בסביבה (או בקובץ .env לצד השרת). ערך ריק מכבה את התכונה הזו במקום להכשיל את העלייה.

`--sandbox`

השרת בודק את המארח פעם אחת בעלייה ועוטף את הרצת הפקודות של הסוכן בארגז החול הנייטיבי של מערכת ההפעלה כשהוא זמין: sandbox-exec (Seatbelt) ב-macOS, bwrap בתוספת socat ב-Linux וב-WSL2. במקום שאין כזה — Windows, או מארח Linux שחסרים בו הכלים האלה — ההרצות נופלות חזרה לניקוי הסביבה, למדיניות הפקודות ולמעקות הבטיחות על הפעולות, ויומן העלייה אומר איזה מצב חל.

--sandbox off הוא מפסק החירום בשטח למקרה שהבדיקה אינה יכולה לראות: מארח שפרופיל ארגז החול עצמו מתנהג בו שלא כשורה. הוא אינו דורש בנייה מחדש, והשרת רושם אזהרה למשך כל חיי התהליך כדי שהמצב לעולם לא יהיה שקט.

`--tool-deferral`

הרצות של הרתמה המובנית שולחות קבוצה תושבת קטנה של הגדרות כלים בתוספת מדד שמות בלבד לשאר, שטוענים את הסכימות שלהם בפעם הראשונה שמשתמשים בהם. זה מקצץ את בלוק הכלים בכ-78% ומשאיר את הקבוצה שנראית תמיד בתוך הטווח שבו מודלים בוחרים כלים באופן מהימן. כלים שנטענים לפי דרישה נשארים קריאים בשמם לאורך כל ההרצה, ו-search_tools מוצא אותם לפי כוונה. ראו הקשר כלים ומטמון הנחיות.

--tool-deferral off מחזיר להיות תושב כל כלי שהתקבל, ומייצר מחדש את הבקשות שהשרת שלח לפני שהטעינה לפי דרישה הייתה קיימת. זהו מפסק החירום למודל שמתמודד רע עם המשטח הדו־שכבתי — דגל ולא בנייה מחדש. הוא משפיע רק על הרתמה המובנית; ה-tools/list של MCP שלקוחות חיצוניים רואים הוא תמיד הקטלוג המלא.

`--credential-gate`

הרצה שפרטי הגישה של הספק שלה חסרים או מוצו חונה במקום להיכשל: המפעיל מקבל בקשה לתקן אותם, וההרצה ממשיכה אם הוא עושה זאת. מועד היעד המוגדר כברירת מחדל הוא 900 שניות (15 דקות), מוגבל ל-0–3600.

מועד היעד ארוך בכוונה בהרבה מזה של בקשת האישור: אישור הוא החלטה שמקבלים בשניות, ואילו תיקון פרטי גישה פירושו לפתוח מסוף, להתחבר ולחזור. התקרה היא מה שמונע מהרצה ללא השגחה — שלב בפייפליין, טריגר cron, webhook — להמתין למישהו שישן. כשהמועד פג, ההרצה נכשלת עם ההודעה שהיא הייתה נכשלת בה ממילא.

--credential-gate=0 הוא מפסק החירום: שום דבר לעולם אינו חונה, ופרטי גישה פגומים מסיימים את התור בדיוק כפי שהיה קורה לפני שהשער היה קיים.

תת־פקודות

פקודה	מה היא עושה
`cc_server`	מריץ את השרת עד `SIGINT`/`SIGTERM`
`cc_server pair`	מקצה מכשיר ומדפיס את המזהה שלו ואת מפתח הצימוד שלו. בטוח מול תיקיית נתונים ששרת כבר מגיש — השרת הרץ קולט את המכשיר בלי הפעלה מחדש
`cc_server calendar connect --workspace <id>`	מחבר חשבון Google לסביבת עבודה בזרימת קוד המכשיר, ואז יוצא
`cc_server update`	בודק, מוריד ומאמת מהדורה עצמאית חדשה יותר
`cc_server --version`	מדפיס את גרסת הבנייה ואת ה-SHA של git — אותה זהות ש-`/healthz` ולחיצת היד של RPC מפרסמים

`pair`

דגל	ברירת מחדל	משמעות
`--device`	`web-client`	מזהה המכשיר. הפלטפורמה נגזרת ממנו, ולכן `--device desktop` מקצה רשומת שולחן עבודה ו-`--device ios`/`android` רשומת טלפון; כל דבר אחר מטופל כווב
`--label`	שם הפלטפורמה בתוספת שם המארח של מכונה זו	שם התצוגה ברשימת המכשירים
`--host`	`localhost`, או `<this-host>` כשמאוגדים לכל ממשק	המארח שמוטמע בכתובת ה-URL המודפסת. הגדירו אותו לכתובת ה-IP ב-LAN או למארח המנהרה שלקוח באמת יחייג אליהם
`--client-url`	לא מוגדר	המקור של לקוח הווב המתארח. מוסיף קישור ישיר סריק ו-QR במסוף

pair מקבל גם את דגלי הליבה --data-dir, --port ו---bind: הם בוחרים את תיקיית הנתונים שאליה נכתב ומעצבים את כתובת השרת המודפסת (ws בלולאה מקומית, wss כשמשתמשים ב---bind any). הרצה חוזרת של pair עבור אותו --device מסובבת את המפתח שלו ומפילה את הסשנים החיים של המכשיר הזה. לפרטי גישה שמונפקים כאן אין תפוגה, שלא כמו 30 הימים שצימוד מתוך האפליקציה קובע.

`update`

--apply מחליף את ההתקנה; הוא נדחה כששרת עדיין עונה בפורט המוגדר, אלא אם תעבירו --force. --allow-downgrade מתיר מהדורה ישנה יותר.

הפקודה מסרבת מלכתחילה, בהסבר ולא בשגיאה, להתקנות שאינן בבעלותה:

סביבה	מזוהה לפי	מה היא אומרת
השרת המוטמע של שולחן העבודה	`CC_EMBEDDED=1` או `CC_BOOTSTRAP_DEVICE_ID`	עדכנו את האפליקציה במקום — המתקין מחליף את כל העץ
הוצאת קוד מקור שמורצת ב-`dart run`	נתיב הסקריפט מסתיים ב-`.dart`	עדכנו אותה עם git
Docker	סימני קונטיינר	משכו תמונה חדשה יותר

מחזור חיי התהליך

cc_server רץ עד SIGINT / SIGTERM. משתנה סביבה אחד נוסף שולט בכך, והוא נקבע על ידי שולחן העבודה ולא על ידכם:

משתנה	השפעה
`CC_EXIT_WITH_PARENT=1`	השרת יוצא כשתהליך האב שלו יוצא, כפי שמזוהה כשהאב סוגר את קצה הכתיבה של צינור ה-stdin שלו. שולחן העבודה מגדיר אותו כך שאפליקציה שקרסה לעולם לא תשאיר שרת יתום שאוחז בתיקיית הנתונים

הגדירו אותו בעצמכם רק אם אתם מפקחים על cc_server כתהליך בן ורוצים את אותה הבטחה.

פריסת תיקיית הנתונים

תיקיית הנתונים המוגדרת כברירת מחדל היא ~/Library/Application Support/control-center ב-macOS,‏ %APPDATA%\control-center ב-Windows ו-$XDG_DATA_HOME/control-center (אחרת ~/.local/share/control-center) בשאר המקומות. .cc_server יחסית לתיקיית העבודה הנוכחית משמשת רק כששום תיקיית בית או תיקיית נתוני יישום אינה נפתרת.

נתיב	תוכן
`global.db`	רישום סביבות העבודה, משתמשים, מכשירים מצומדים, עדכוני החדשות ותור הצי
`<workspaceId>/workspace.db`	מסד נתונים אחד לכל סביבת עבודה — סוכנים, מרחבים, כרטיסים, זיכרון וגרף הקוד
`<workspaceId>/chat_credentials/`	אסימוני בוט צ’אט, כ-JSON פשוט, כדי שייסעו יחד עם סביבת העבודה
`secrets.json`	מפתחות צימוד, זהות האפליקציה של הספק, אסימונים לפי משתמש ואסימוני Google, SSO (`0600`)
`backups/<timestamp>/`	תמונת מצב אחת של ההתקנה — `manifest.json`, `global.db` ועותק של כל סביבת עבודה
`backups/exports/`	ייצוא של סביבת עבודה בודדת, `<workspaceId>-<timestamp>.db`
`backups/transfer/`	אחסון ביניים להורדות והעלאות של גיבויים; מנוקה על ידי הנתיב שכותב אליו
`models/`	מודלי הטמעה, הפרדת דוברים ודיבור שעל המכשיר
`meetings/<meetingId>/`	שמע פגישות שנשמר
`rigs/images/`	תמונות דיסק מיובאות של תחנות (משטח שולחן העבודה של QEMU)
`rigs/smolvm/<rigId>/`	מצב ריצה של microVM לכל תחנה (סוד המתווך, `0600`)
`rigs/smolvm-packs/`	חבילות מכונה שחולצו מראש — המטמון שהופך אתחולים חוזרים של תחנות למהירים
`rigs/tls/`	רשות האישורים של דומיין הפיתוח עבור HTTPS של התחנות (מפתחות `0600`)
`rigs/run/<rigId>/`	שכבות-על של QEMU, תמונות זרע ומפתחות לכל VM (`0600`)

ראו גם

הפעלת שרת ללא ממשק — מתכון ההגדרה שהדגלים האלה שייכים לו
הפעלת worker בצי — הבינארי הנפרד cc_worker שנרשם לשרת הזה
גיבוי ושחזור — העתקת התיקייה הזו למקום בטוח
גיבוי, ייצוא וייבוא — פריסת תמונת המצב וכל פעולת גיבוי
התחברות לשרת מרוחק — כיוון לקוח אליו
פריסה ולקוחות — למה השרת מחזיק בהכול