תיעוד 102

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

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

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

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

בסיום תהיה לך סביבה בדף הניהול Cloud environments, runner שמבצע תשאול (polling) לקבלת עבודה, ו-session שרץ על ה-host שלך. לפני שתחבר מאגרים (repositories) אמיתיים או מערכות פנימיות, פעל לפי פריסה לסביבת ייצור, שמכסה את מצב האבטחה, בקרת תעבורה יוצאת (egress), אישורי גישה ל-git, ותזמור (orchestration).

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

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

הצד של claude.ai דורש:

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

#מארח ורשת

מארח ה-runner דורש:

מארח או קונטיינר של Linux או macOS עם חיבור HTTPS יוצא אל api.anthropic.com, אל claude.ai ומארחי ההורדה שאליהם הוא מפנה עבור שלב ההתקנה בהמשך, ואל מארח ה-git שלך לצורך שכפול (clone); טבלת דרישות הרשת כוללת את הרשימה המלאה. מערכת Windows אינה נתמכת כמארח runner; הרץ את ה-runner בקונטיינר של Linux במקום זאת. תחנות עבודה של מפתחים אינן מושפעות, מכיוון ש-sessions מתחילים מ-claude.ai בדפדפן.
שעון מסונכרן לזמן אמת, למשל באמצעות NTP. תהליך האימות נכשל כאשר השעון סוטה ביותר מחמש דקות; ראה פתרון בעיות.

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

התקן במארח לפני שתתחיל:

Claude Code בגרסה 2.1.224 ומעלה, בכל אחת מ-שיטות ההתקנה הסטנדרטיות. ה-runner הוא חלק מהקובץ הבינארי הסטנדרטי של claude, וגרסאות מוקדמות יותר אינן מזהות את תת-הפקודה self-hosted-runner. ערוץ ברירת המחדל latest של המתקין המקורי מספק כל גרסה ברגע שהיא מתפרסמת; ערוץ stable, ה-cask של Homebrew בשם claude-code, ומאגרי ה-apt, dnf ו-apk היציבים מפגרים בכשבוע. כדי לקבע גרסה מדויקת שצי השרתים שלך מריץ, ראה התקנת גרסה ספציפית. עבור תמונות קונטיינר, ראה את ה-Dockerfile ב-פריסה לסביבת ייצור.
Git בגרסה 2.24 ומעלה. אפשרויות git מסוימות בדף הפריסה דורשות גרסאות חדשות יותר; הגדרת git מפרטת את רף המינימום עבור כל אחת.

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

claude self-hosted-runner --help

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

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

Claude Code כולל הגדרה מודרכת: session אינטראקטיבי של Claude Code שמלווה אותך ביצירת הסביבה בממשק הניהול, מפעיל runner מקומי עם קובץ ה-secret ששמרת, מוודא שה-runner נרשם, וכותב דף עזר אל ./runner-setup/CHEAT-SHEET.md. הרץ אותו במכונה שבה התחברת באמצעות claude auth login עם חשבון בעל תפקיד Owner; הוא אינו זמין בעבודה עם מפתחות API או ספקי מודלים של צד שלישי. במארחים שבהם session אינטראקטיבי אינו אפשרי, השתמש בשלבים הידניים להלן במקום זאת. ודא תחילה כי בדיקת הגרסה עברה בהצלחה: בגרסאות ישנות מ-2.1.224, פקודה זו מתחילה session רגיל של Claude עם המילים כהנחיה במקום ההגדרה המודרכת. כדי להתחיל בהגדרה המודרכת, הרץ את תת-הפקודה setup ופעל לפי ההנחיות:

claude self-hosted-runner setup

כדי להגדיר באופן ידני במקום זאת:

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

אם איבדת את ה-secret או שאתה צריך לבצע רוטציה, צור secret חדש בלשונית Configuration של הסביבה, פרוס את ה-secret החדש ל-runners שלך, ולאחר מכן בטל את הישן. runners שמחזיקים ב-secret שבוטל ייכשלו בתשאול המאומת הבא שלהם ויסיימו את פעולתם, תוך רישום poll auth failed בלוג, והמתזמר שלך יפעיל אותם מחדש עם ה-secret החדש.
הפעלת runner צור את ספריית ה-secret. שלב זה והשלב הבא דורשים הרשאות root עבור הנתיב /etc/claude; כל נתיב שתהליך ה-runner מסוגל לקרוא יעבוד, לכן התאם את שתי הפקודות ואת הערך של --environment-secret-file יחד אם תשתמש בנתיב אחר.
```
mkdir -p /etc/claude
```
כתוב את ה-secret של הסביבה לקובץ. הפקודה שלהלן קוראת מהטרמינל שלך כדי שה-secret יישאר מחוץ להיסטוריית המעטפת (shell): הדבק את הערך שהעתקת, לחץ על Enter, ולאחר מכן על Ctrl-D, וה-umask של תת-המעטפת הופך את הקובץ לניתן לקריאה על ידי הבעלים שלו בלבד.
```
(umask 077 && cat > /etc/claude/environment-secret)
```
בחר ספריית בסיס, והחלף את <writable-dir> בפקודת ה-runner להלן בנתיב מוחלט שה-runner מסוגל לכתוב אליו או ליצור אותו. ה-runner יוצר את הספרייה בעת ההפעלה, ולאחר מכן מבצע checkout למאגרים ויוצר ספריות עבור כל session תחתיה. ללא --base-dir הוא משתמש ב-/workspace, שעובד רק אם הספרייה הזו כבר קיימת וניתנת לכתיבה, או אם אתה מפעיל את ה-runner כמשתמש root.

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

לאחר מכן הפעל את ה-runner עם --environment-secret-file ו---base-dir. ה-runner נרשם בסביבה שלך ומתחיל לבצע תשאול לקבלת עבודה. אם ה-runner יוצא, הפעל אותו מחדש ידנית. פריסות ייצור מריצות את ה-runner תחת מתזמר שמפעיל מחדש runners שיצאו, בדרך כלל עם מערכת קבצים נקייה בכל הפעלה מחדש; שימוש חוזר ב-checkout שהוכן מראש מכסה את הגדרת הדיסק הקבוע הנתמכת.
```
claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>'
```
אימות הופעת ה-runner חזור אל דף Cloud environments. הסטטוס של הסביבה שלך משתנה מ-No runners deployed ל-Healthy בתוך שניות ספורות מהפעלת ה-runner; פתח את הסביבה ובחר ב-Activity כדי לראות את ה-runner עצמו.
ניתוב session לסביבה התחל session בכתובת claude.ai/code ובחר את הסביבה שלך מתוך בורר הסביבות, שבו סביבות באירוח עצמי מופיעות לצד סביבות באירוח של Anthropic. ה-runner מבצע שכפול עם אישורי ה-git שכבר קיימים במארח, לכן בחר מאגר שהמארח הזה כבר מסוגל לשכפל, או מאגר ציבורי; אפשרויות לאישורי גישה עבור מאגרים פרטיים בסביבת ייצור מופיעות ב-הגדרת git. ה-runner הזמין הבא קולט את ה-session הממתין בתור ורושם בלוג Picked up session <session-id> יחד עם מספר ה-sessions הפעילים שלו והקיבולת שלו, כך שתוכל לוודא מתוך הפלט של ה-runner עצמו איזה מארח לקח את ה-session. עקוב אחר פעולת ה-session וקרא את תשובותיו של Claude בכתובת claude.ai/code. אם ה-session נשאר ממתין בתור במקום זאת, ראה פתרון בעיות.

ה-runner מתוכנן לצאת ברגע שה-sessions הפעילים שלו מסתיימים; ראה מחזור חיי runner. עבור סביבת ייצור, פרוס אותו תחת מתזמר שמפעיל אותו מחדש בעת יציאה. ראה פריסה לסביבת ייצור.

#שליחת הודעת המשך ל-session פעיל

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

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

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

#מה הלאה

פריסה לסביבת ייצור: הקשחת הפריסה, בקרת תעבורה יוצאת, הגדרת אישורי git, והרצת צי המארחים תחת Kubernetes או Compose
התאמה אישית של sessions: סקריפטים עוטפים (wrapper scripts), נקודות חיבור למחזור חיים (lifecycle hooks), runners לפי דרישה, שרתי MCP, והרשאות
בדיקה מקצה לקצה: בדיקת עשן ב-CI שמשגרת session וקוראת את התשובות של Claude