📘 תיעוד 139

מדריך מהיר לסביבות באירוח עצמי

הגדרת הסביבה הראשונה באירוח עצמי: התקנת Claude Code, יצירת הסביבה, הפעלת runner, והפניית סשן אליו.

[!NOTE]

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

סביבה באירוח עצמי מריצה סשני ענן של Claude Code על תשתית שהארגון שלכם מפעיל, והם מבוצעים על ידי תהליכי runner שאתם פורסים. המדריך המהיר הזה מקים את הראשונה שלכם, הקטנה ביותר שעובדת: runner אחד על מארח יחיד, שמריץ סשן בדיקה אחד. יש שני שלבים: יצירת הסביבה, הפעלת runner, והפניית סשן אליו, ואז שליחת הודעה לסשן הזה מהטרמינל. תעברו בין שני משטחים: claude.ai ליצירת הסביבה, לבדיקת הסטטוס שלה ולהפניית סשן, וטרמינל על המארח לכל מה שה-runner עושה.

בסוף תהיה לכם סביבה בדף הניהול Cloud environments, runner שסורק עבודה, וסשן שרץ על המארח שלכם. לפני שתחברו מאגרים אמיתיים או מערכות פנימיות, עברו על פריסה לייצור, שמכסה את מצב האבטחה, בקרת egress, אישורי git, ותזמור.

#דרישות מקדימות

#ארגון ותפקידים

הצד של claude.ai צריך:

• Allow self-hosted environments מופעל על ידי Owner בדף הניהול Cloud environments. כפתור New לא מופיע עד שזה מופעל. אם אין לכם את התפקיד, מישהו שיש לו יכול ליצור את הסביבה ולמסור לכם את הסוד שלה. שלבי ה-runner והטרמינל בדף הזה לא דורשים תפקיד ב-claude.ai, ובמקום שבו שלב בודק סטטוס בממשק הניהול, שורות הלוג של ה-runner עצמו נותנות את אותו אות.
• מחבר GitHub מופעל על ידי Owner, וחיבור GitHub של כל מפתח, כדי שיוכלו לבחור מאגרים ב-github.com כשהם מתחילים סשנים.

#מארח ורשת

מארח ה-runner צריך:

• מארח או קונטיינר Linux או macOS עם HTTPS יוצא אל api.anthropic.com, אל claude.ai ואל מארחי ההורדה שאליהם הוא מפנה עבור שלב ההתקנה למטה, ואל מארח ה-git שלכם עבור השכפול. טבלת דרישות הרשת מכילה את הרשימה המלאה. Windows אינו נתמך כמארח runner. הריצו את ה-runner בקונטיינר Linux. תחנות עבודה של מפתחים אינן מושפעות, כי הסשנים מתחילים מ-claude.ai בדפדפן.
• מאגר לסשן הבדיקה: מאגר ציבורי, או מאגר שהמארח הזה כבר יכול לשכפל לפי כתובת ה-HTTPS שלו בלי בקשת אישורים. מפתח SSH לבדו אינו מספיק, כי ה-runner משכפל את כתובת ה-https:// של המאגר. כדי לשכפל דרך SSH, ראו שכתוב כתובות git לרשתות פרטיות.
• שעון שמסונכרן לזמן אמת, למשל עם NTP.

#תוכנה על מארח ה-runner

התקינו על המארח לפני שמתחילים:

• Claude Code בגרסה v2.1.224 או חדשה יותר, בכל אחת משיטות ההתקנה הסטנדרטיות. ה-runner הוא חלק מהבינארי הסטנדרטי claude, וגרסאות מוקדמות יותר לא מזהות את תת הפקודה self-hosted-runner. runner שמשרת סשני Claude Tag צריך גרסה v2.1.229 או חדשה יותר, ו-python3 ב-PATH שלו, כי ה-hooks שמישור הבקרה מספק לסשנים האלה מריצים python3. כדי לקבע את הגרסה המדויקת שהצי שלכם מריץ, ראו התקנת גרסה מסוימת. לתמונות קונטיינר, ראו את ה-Dockerfile בפריסה לייצור.
• Git 2.24 או חדש יותר. חלק מאפשרויות git בדף הפריסה דורשות גרסאות חדשות יותר. הגדרת git מציינת את הרצפה של כל אחת.

אשרו שהמארח מוכן:

claude self-hosted-runner --help

מארח מוכן מדפיס את טקסט השימוש של ה-runner, ומפרט דגלים כמו --environment-secret-file. בגרסאות ישנות מ-2.1.224, הפקודה מדפיסה את הפלט הכללי של claude --help. אם אתם רואים את הפלט הזה, עדכנו את Claude Code. אם אתם מריצים את claude מתמונת קונטיינר, בנו מחדש את התמונה עם גרסה 2.1.224 או חדשה יותר.

#הגדרת סביבה ו-runner

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

#הרצת ההגדרה המודרכת

ההגדרה המודרכת מלווה אתכם ביצירת הסביבה בממשק הניהול, מפעילה runner מקומי עם קובץ הסוד שאתם שומרים, מאשרת שה-runner נרשם, וכותבת דף עזר אל ./runner-setup/CHEAT-SHEET.md. לפני שתריצו אותה, אשרו את הכניסה ואת הגרסה:

• כניסה: הריצו אותה על מכונה שבה נכנסתם עם claude auth login באמצעות חשבון שמחזיק בתפקיד Owner. עם מפתח API בלבד או ספק מודל צד שלישי, הסשן מתחיל אבל בדיקות הארגון שלו נכשלות.
• גרסה: אשרו שבדיקת הגרסה עברה. בגרסאות ישנות מ-2.1.224, פקודת ההגדרה מתחילה סשן Claude עם המילים בתור הפרומפט במקום ההגדרה המודרכת.

כדי להתחיל את ההגדרה המודרכת, הריצו את תת הפקודה setup במעטפת ועקבו אחרי ההנחיות:

claude self-hosted-runner setup

ההגדרה עצמה לא מתחילה סשן בדיקה: היא אומרת לכם להתחיל אחד ב-claude.ai/code. השלב האחרון של ההגדרה עוצר את ה-runner שהיא הפעילה. אם תעזבו את ההגדרה לפני השלב הזה, ה-runner ממשיך לרוץ. כדי להמשיך אחרי השלב האחרון, הפעילו את ה-runner שוב במעטפת עם הפקודה ב-./runner-setup/CHEAT-SHEET.md, ואז הפנו סשן לסביבה.

#הגדרה ידנית

צרו את הסביבה ב-claude.ai, הפעילו את ה-runner מטרמינל על המארח, ואז חזרו ל-claude.ai כדי לאשר שה-runner מופיע ולהפנות סשן אליו. אם מישהו שמחזיק בתפקיד Owner כבר יצר את הסביבה ומסר לכם את הסוד שלה, התחילו בשלב 2.

1. יצירת סביבה

עברו אל דף Cloud environments בהגדרות הניהול. תחת Self-hosted environments, בחרו New, תנו שם לסביבה, ובחרו Create. בשלב השני של האשף, בחרו Copy environment key כדי להעתיק את סוד הסביבה, שממשק הניהול מכנה environment key. claude.ai מציג את הסוד פעם אחת, ואי אפשר לאחזר אותו אחר כך. הוא פג תוקף 365 ימים אחרי היצירה. מזהה ccpool_... של הסביבה נשאר גלוי בתיבת הפרטים שלה. תצטרכו אותו לבדיקת aud באימות אסימון ולשיגור סשני בדיקה מ-CI.

אם הסוד אבד או שצריך לסובב אותו, צרו סוד חדש מלשונית Configuration של הסביבה, פרסו את הסוד החדש אל ה-runners שלכם, ואז בטלו את הישן. runners שמחזיקים סוד שבוטל נכשלים בסקר המאומת הבא שלהם ויוצאים, ורושמים poll auth failed, והמתזמר שלכם מפעיל אותם מחדש עם הסוד החדש.

2. הפעלת runner

צרו את ספריית הסוד. הפקודה הזו והבאה אחריה משתמשות ב-/etc/claude, שדורש root, וקובץ הסוד שהן יוצרות קריא רק למשתמש שמריץ אותן. אם ה-runner ירוץ כמשתמש אחר, הוא יוצא עם error: Failed to read environment secret file <path> (EACCES: permission denied, open '<path>'). במקרה הזה, הריצו את שתי הפקודות כמשתמש של ה-runner, עם ספרייה שהמשתמש הזה יכול לכתוב אליה במקום /etc/claude, והעבירו את אותו נתיב אל --environment-secret-file. כל נתיב שתהליך ה-runner יכול לקרוא עובד.

mkdir -p /etc/claude

כתבו את סוד הסביבה לקובץ. הפקודה למטה קוראת מהטרמינל שלכם כדי שהסוד יישאר מחוץ להיסטוריית המעטפת: הדביקו את הערך שהעתקתם, לחצו Enter, ואז Ctrl-D, וה-umask של תת המעטפת הופך את הקובץ לקריא רק לבעלים שלו.

(umask 077 && cat > /etc/claude/environment-secret)

בחרו ספריית בסיס, והחליפו את <writable-dir> בפקודת ה-runner למטה בנתיב מוחלט שה-runner יכול לכתוב אליו או ליצור אותו. ה-runner יוצר את הספרייה בעת ההפעלה, ואז מבצע checkout למאגרים ויוצר תחתיה ספריות לכל סשן. בלי --base-dir הוא משתמש ב-/workspace, וזה עובד רק אם הספרייה הזו כבר קיימת וניתנת לכתיבה, או שאתם מפעילים את ה-runner כ-root.

[!WARNING]

השתמשו בספרייה שמיועדת ל-runner, לא בספריית הבית שלכם או בספרייה של שכפולים משלכם. ה-runner מתייחס לכל מה שהוא מוצא ב-<writable-dir>/<repo-owner>/<repo> כאל שכפול משלו, ויכול לאפס אותו ולדרוס או למחוק קבצים בו.

אם ה-runner לא יכול ליצור את ספריית הבסיס או לכתוב אליה, הוא יוצא בעת ההפעלה עם שגיאה שמציינת את שם הספרייה, במקום להירשם. ראו פתרון בעיות.

אחר כך הפעילו את ה-runner עם --environment-secret-file ו---base-dir:

claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>'

ה-runner רושם Registered: runner_id=<runner-id> אחרי שנרשם לסביבה שלכם, ואז מתחיל לסרוק עבודה. כשהוא מופעל עם הפקודה הזו, הוא יוצא לפי התכנון אחרי ששירת סשן אחד, לא אחרי כל תור. כדי לשרת סשנים נוספים, הפעילו את ה-runner שוב בכל פעם שהוא יוצא. ראו אם ה-runner יוצא לגבי מתי זה קורה ומה ה-runner רושם.

3. אימות שה-runner מופיע

חזרו אל דף Cloud environments. הסטטוס של הסביבה שלכם משתנה מ-No runners deployed ל-Healthy בתוך כמה שניות מהפעלת ה-runner. פתחו את הסביבה ובחרו Activity כדי לראות את ה-runner עצמו. אם אין לכם גישה לדף הניהול, השורה Registered: runner_id=<runner-id> בלוג של ה-runner מהשלב הקודם נותנת את אותו אות.

4. הפניית סשן לסביבה

התחילו סשן ב-claude.ai/code ובחרו את הסביבה שלכם מבורר הסביבות, שבו סביבות באירוח עצמי מופיעות לצד סביבות באירוח Anthropic. למאגר, בחרו את זה מהדרישות המקדימות: מאגר ציבורי, או מאגר שהמארח הזה כבר יכול לשכפל לפי כתובת ה-HTTPS שלו בלי בקשת אישורים.

ה-runner הפנוי הבא קולט את הסשן שבתור ורושם Picked up session <session-id> יחד עם הספירה הפעילה והקיבולת שלו, כך שתוכלו לאשר מתוך הפלט של ה-runner עצמו איזה מארח לקח את הסשן. צפו בעבודה של הסשן וקראו את תשובות Claude ב-claude.ai/code.

אם הסשן לא מתחיל לעבוד, התאימו למה שאתם רואים:

• הסשן נשאר בתור: ראו פתרון בעיות.
• הסשן נכשל בהתחלה עם שגיאת git: אם השגיאה כוללת את could not read Username for של git ואחריו את כתובת מארח ה-git שלכם, ל-runner לא היו אישורי HTTPS למארח הזה.
  • ספקו אישורי HTTPS: ראו הגדרת git
  • שכפול דרך SSH: אם למארח ה-runner כבר יש מפתח SSH, ראו שכתוב כתובות git לרשתות פרטיות
  • אחרי אחד משני התיקונים: הפעילו את ה-runner שוב וצפו בסשן שנכשל במקום להתחיל סשן חדש. אם הוא נכשל כמה פעמים, המתינו כמה דקות עד שה-runner ירשום Picked up session.
  • כדי להשתמש במאגר אחר: ארכבו או מחקו את הסשן שנכשל, ואז הפעילו את ה-runner שוב והתחילו סשן חדש. אחרת, ה-runner יכול לקלוט את הסשן שנכשל במקום את החדש.

#אם ה-runner יוצא

אם ה-runner יוצא במהלך המדריך המהיר הזה, הפעילו אותו שוב. ה-runner יכול לצאת מעצמו:

• לא נשאר דבר שרץ: הלוג מציג [runner:exit] account workload drained , exiting. ה-runner יוצא לפי התכנון אחרי שהוא כבר לא מריץ שום סשן, למשל:
  • ארכבתם או מחקתם את הסשן: הפעילו את ה-runner שוב
  • הסשן נכשל בהתחלה: תקנו את הסיבה, ואז הפעילו את ה-runner שוב
• אבד קשר: הלוג מציג שורת [runner:fatal] עם runner record gone server-side או עם poll auth failed. אם ה-runner מאבד קשר עם Anthropic לזמן מה, למשל כי המארח נכנס לשינה, הוא יכול לצאת בפעם הבאה שהוא מגיע ל-Anthropic.

תור שהסתיים לא מסיים את סשן הבדיקה שלכם. אחרי התור הראשון הסשן עדיין מחובר וה-runner עדיין פעיל, כך שאפשר לשלוח לסשן הודעת המשך בלי להפעיל מחדש את ה-runner קודם.

לייצור, פרסו את ה-runner תחת מתזמר שמפעיל אותו מחדש ביציאה וממתין זמן ארוך יותר בין הפעלות מחדש כשה-runner ממשיך לצאת מיד אחרי שהוא מתחיל. ראו פריסה לייצור ומתי ה-runner יוצא.

#שליחת הודעת המשך לסשן שרץ

אחרי שסשן רץ על הסביבה שלכם, שלחו לו המשך מ-CLI של claude בכל מכונה שבה אתם מחוברים עם claude auth login. הפקודה לא צריכה לרוץ מהמכונה שהתחילה את הסשן. הפקודה שולחת הודעה אחת:

claude -p "your message" --cloud <session-id>

עבור <session-id>, העבירו את מזהה session_... או cse_... החשוף, או את כתובת claude.ai/code של הסשן. שליחה שהצליחה מדפיסה Sent to cloud session. עם מזהה הסשן וקישור צפייה. צורות מזהה מקובלות, פלט JSON, ודרישות החשבון והמדיניות נמצאים בשליחת המשכים מה-CLI, כי הפקודה עובדת אותו דבר מול סשנים באירוח Anthropic.

#מה הלאה

• פריסה לייצור: הקשיחו את הפריסה, שלטו ב-egress, הגדירו אישורי git, והריצו את הצי תחת Kubernetes או Compose
• התאמת סשנים: סקריפטי מעטפת, hooks של מחזור חיים, runners לפי דרישה, שרתי MCP, והרשאות
• בדיקה מקצה לקצה: בדיקת עשן ב-CI שמשגרת סשן וקוראת את תשובות Claude