📘 תיעוד 98

הגדרת כלי ה-Bash בארגז חול

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

ארגז החול של Bash מאפשר ל-Claude להריץ את רוב פקודות המעטפת (shell) בלי לעצור כדי לבקש רשות. במקום לאשר כל פקודה, אתם מגדירים באילו קבצים ובאילו מתחמי רשת (domains) פקודות יכולות לגעת, ומערכת ההפעלה אוכפת את הגבול הזה עבור כל פקודת Bash ותהליכי הצאצא שלה.

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

#תחילת העבודה

ארגז החול מובנה בתוך Claude Code ופועל ב-macOS, Linux ו-WSL2. מערכת Windows מקומית (native) אינה נתמכת. ב-Windows, הריצו את Claude Code בתוך הפצת WSL2.

ב-macOS אין צורך להתקין דבר: ארגז החול משתמש בתשתית Seatbelt המובנית. ב-Linux וב-WSL2, ארגז החול מסתמך על שתי חבילות, המפורטות בסעיף הגדרת Linux ו-WSL2. גם אם עדיין לא התקנתם אותן, תוכלו להתחיל עם /sandbox, מכיוון שהלוח שלו מציג אם חסר משהו.

1. הריצו את /sandbox: התחילו הפעלה של Claude Code והריצו את הפקודה /sandbox:

   העתק

   /sandbox

   פעולה זו פותחת את לוח ארגז החול עם שלוש לשוניות, ובנוסף לשונית Dependencies ב-Linux כאשר מסנן ה-seccomp האופציונלי חסר:

   • Mode: בחירת האופן שבו פקודות בארגז חול מאושרות, מוסבר בשלב הבא
   • Overrides: בחירה האם פקודות שנכשלות תחת ארגז החול יכולות לסגת להרצה ללא ארגז חול. זוהי ההגדרה allowUnsandboxedCommands
   • Config: צפייה בהגדרות ארגז החול הסופיות שנפתרו

   אם הלוח מציג רק את לשונית Dependencies, חבילה נדרשת חסרה. התקינו אותה כמתואר בסעיף הגדרת Linux ו-WSL2, הפעילו מחדש את Claude Code, והריצו שוב את /sandbox.

2. בחרו מצב: בלשונית Mode, בחרו ב-auto-allow או ב-regular permissions. מצב auto-allow מריץ פקודות בארגז חול ללא בקשת אישור, ומצב regular permissions שומר על בקשות האישור הרגילות גם כאשר פקודות מבודדות בארגז חול. ראו מצבי ארגז חול לגבי אילו פקודות עדיין מבקשות אישור במצב auto-allow.

3. הריצו פקודת Bash: בקשו מ-Claude להריץ פקודה, כגון בנייה (build) או סדרת בדיקות (test suite). כברירת מחדל, פקודות בתוך ארגז החול יכולות לכתוב לתיקיית העבודה, לתיקייה הזמנית של ההפעלה, ולכל תיקייה שהוספתם באמצעות --add-dir, /add-dir, או permissions.additionalDirectories. בפעם הראשונה שפקודה זקוקה למתחם רשת חדש, Claude Code מבקש אישור, או שבמצב auto הוא שולח את הבקשה למסווג (classifier).

   פקודות שאינן יכולות לרוץ בארגז חול נסוגות לתהליך ההרשאות הרגיל. Claude Code מכתיר את בקשת האישור שלהן בכותרת "Bash command (unsandboxed)" במקום "Bash command", כדי שתוכלו לדעת אילו פקודות רצו מחוץ לארגז החול. כדי להרחיב או לצמצם את מה שארגז החול מאפשר, ראו הגדרת ארגז החול.

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

כאשר אתם בוחרים מצב בלוח, Claude Code שומר אותו בהגדרות המקומיות של הפרויקט שלכם בנתיב .claude/settings.local.json, החלות על הפרויקט הנוכחי. Claude Code מוסיף את הקובץ הזה ל-gitignore הגלובלי שלכם כאשר הוא שומר בו הגדרה. כדי להפעיל את ארגז החול בכל הפרויקטים שלכם, הגדירו את sandbox.enabled כ-true בהגדרות המשתמש שלכם בנתיב ~/.claude/settings.json. כדי לאכוף ארגז חול עבור כל מפתח בארגון, השתמשו בהגדרות מנוהלות.

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

#הגדרת Linux ו-WSL2

ב-Linux וב-WSL2, ארגז החול מסתמך על שתי חבילות:

• bubblewrap: כלי ארגז החול ללא הרשאות ניהול (unprivileged) שאוכף בידוד של מערכת הקבצים.
• socat: הממסר (relay) המשמש לניתוב תעבורת רשת דרך ה-proxy של ארגז החול.

התקינו אותן באמצעות מנהל החבילות של ההפצה שלכם:

Ubuntu/Debian:

sudo apt-get install bubblewrap socat

Fedora:

sudo dnf install bubblewrap socat

כאשר תלות מסוימת חסרה, לשונית Dependencies ב-/sandbox מפרטת אילו מבין ripgrep, bubblewrap, socat ומסנן ה-seccomp חסרים בפלטפורמה שלכם. אם אינכם רואים את הלשונית לאחר ההתקנה וההפעלה מחדש של Claude Code, כל התלויות קיימות.

הכלי ripgrep מצורף לקובץ הבינארי המקורי של Claude Code. מסנן ה-seccomp הוא אופציונלי ומוסיף חסימה של שקעי דומיין של יוניקס (Unix domain sockets). התקינו אותו באמצעות npm install -g @anthropic-ai/sandbox-runtime אם הוא חסר.

כאשר תלות נדרשת חסרה, לשונית Dependencies היא הלשונית היחידה שמוצגת עד שתתקינו אותה. כאשר רק מסנן ה-seccomp האופציונלי חסר, לשונית Dependencies מופיעה לצד הלשוניות האחרות. בדיקת התלויות מתבצעת בעת ההפעלה, לכן הפעילו מחדש את Claude Code לאחר התקנת חבילות כדי ש-/sandbox יזהה אותן.

#Ubuntu 24.04 ואילך: מתן הרשאה ל-bubblewrap ליצור user namespaces

ב-Ubuntu 24.04 ואילך, מדיניות ברירת המחדל של AppArmor מונעת מ-bubblewrap ליצור את ה-user namespaces הדרושים לו לצורך בידוד.

כדי לבדוק האם הסביבה שלכם אוכפת הגבלה זו, כולל בתוך WSL2, הריצו sysctl kernel.apparmor_restrict_unprivileged_userns. אם הפקודה מחזירה 0, דלגו על שלב זה. אם היא מדפיסה שגיאת No such file or directory, המפתח אינו קיים ותוכלו לדלג על שלב זה. אם היא מחזירה 1, הוסיפו פרופיל AppArmor המעניק ל-bwrap יכולת זו:

sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF

הפרופיל חל רק על bwrap עצמו, ולא על הפקודות שהוא מריץ בתוך ארגז החול. טענו מחדש את AppArmor כדי להחיל אותו:

sudo systemctl reload apparmor

#הערות לגבי WSL2

בדקו את גרסת ה-WSL שלכם באמצעות wsl -l -v מתוך PowerShell. אם אתם רואים Sandboxing requires WSL2, ההפצה שלכם מריצה WSL1. שדרגו אותה ל-WSL2 או הריצו את Claude Code ללא ארגז חול.

ב-WSL2, מערכת WSL מעבירה הפעלה של קובץ בינארי של Windows כגון cmd.exe, powershell.exe, או כל דבר תחת /mnt/c/ למארח ה-Windows דרך שקע Unix. לכן, השאלה האם פקודה בארגז חול יכולה להפעיל קובץ כזה תלויה בהגדרות שקע ה-Unix של ארגז החול: יש להתקין את מסנן ה-seccomp האופציונלי כדי לחסום את השקע מלכתחילה. כדי לאפשר הפעלות אלו, הגדירו את allowAllUnixSockets. כדי להשאיר אותן מחוץ לארגז החול לחלוטין, הוסיפו את הפקודה ל-excludedCommands.

#מצבי ארגז חול

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

#מצב Auto-allow

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

גם במצב auto-allow, הכללים הבאים עדיין חלים:

• חוקי חסימה מפורשים (deny rules) מכובדים תמיד
• פקודות rm או rmdir המכוונות לנתיב קריטי עדיין עוברות דרך תהליך ההרשאות הרגיל
• חוקי בקשת אישור ממוקדי תוכן (ask rules) כמו Bash(git push *) עדיין כופים בקשת אישור אפילו עבור פקודות בארגז חול
• חוק ask פשוט של Bash, או התבנית השקולה Bash(*), נפסח עבור פקודות שרצות בארגז חול. הוא עדיין חל על פקודות שנסוגות לתהליך ההרשאות הרגיל. במצב plan, החוק אינו נפסח: הוא מבקש אישור גם עבור פקודות בארגז חול, כולל פקודות לקריאה בלבד. לפני גרסה v2.1.212, הדילוג חל גם במצב plan

מידע: מצב auto-allow פועל ללא תלות בהגדרת מצב ההרשאות שלכם, למעט חריג אחד: מצב plan. גם אם אינכם במצב "accept edits", פקודות Bash בארגז חול רצות אוטומטית כאשר auto-allow מופעל. המשמעות היא שפקודות Bash המשנות קבצים בתוך גבולות ארגז החול מתבצעות ללא בקשת אישור, אפילו במצב Manual, שבו כלי עריכת הקבצים היו מבקשים אישור.

במצב plan, מצב auto-allow אינו מרחיב אישורים. ראו מצב plan לגבי האופן שבו Claude Code מגביל פקודות בזמן שאתם מתכננים. לפני גרסה v2.1.212, auto-allow הריץ פקודות בארגז חול ללא בקשת אישור גם במצב plan.

#מצב Regular permissions

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

#פתח המילוט לניסיון חוזר ללא ארגז חול

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

הפקודה שמורצת שוב רצה מחוץ לארגז החול, ולכן עוברת דרך תהליך ההרשאות הרגיל. במצב Manual תקבלו בקשת אישור. במצב auto, המסווג מעריך את הפקודה שמתחתיה. כאשר permissions.blockReadsOutsideWorkingDirectories מופעל, ניסיון חוזר הזקוק לאישור להרצה מחוץ לארגז החול מציג לכם בקשת אישור במקום זאת. כדי לקבל בקשת אישור בכל ניסיון חוזר ללא ארגז חול אפילו במצב auto, הוסיפו חוק ask עבור Bash(dangerouslyDisableSandbox:true).

באפשרותכם להשבית פתח מילוט זה על ידי הגדרת "allowUnsandboxedCommands": false בהגדרות ארגז החול שלכם. כאשר פתח המילוט מושבת, Claude Code מתעלם מהפרמטר dangerouslyDisableSandbox, וכל פקודה ש-Claude מריץ חייבת לרוץ בארגז חול אלא אם רשמתם אותה ב-excludedCommands. לשונית Overrides ב-/sandbox מציגה הגדרה זו כ-Strict sandbox mode.

מצב Strict sandbox mode חל על הפקודות ש-Claude מריץ. פקודות שאתם מקלידים בעצמכם בשורת הפקודה של מצב shell עם קידומת ! רצות מחוץ לארגז החול, אלא אם ההפעלה היא אחת מאלו:

• הפעלה ברקע: מצב strict sandbox חל גם על פקודות במצב shell
• הפעלת Linux שבה מוגדר CLAUDE_CODE_SUBPROCESS_ENV_SCRUB: כל פקודה רצה בארגז חול, כולל פקודות במצב shell

לפני גרסה v2.1.260, מצב strict sandbox החיל ארגז חול על פקודות מצב shell בכל הפעלה.

#תיקיות זמניות

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

#הגדרת ארגז החול

התאימו אישית את התנהגות ארגז החול דרך קובץ settings.json שלכם. ראו הגדרות למדריך ההגדרות המלא.

כברירת מחדל, פקודות בארגז חול יכולות לכתוב לתיקיית העבודה הנוכחית, לתיקייה הזמנית של ההפעלה, ולכל תיקייה שהוספתם באמצעות --add-dir, /add-dir, או permissions.additionalDirectories. אם פקודות של תהליכי משנה כגון kubectl, terraform, או npm צריכות לכתוב מחוץ לתיקיות אלו, השתמשו ב-sandbox.filesystem.allowWrite כדי להעניק גישה לנתיבים ספציפיים:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

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

כאשר אתם מגדירים את אותו מערך של מערכת קבצים במספר טווחי הגדרות (settings scopes), Claude Code ממזג אותם, ומשלב נתיבים מכל טווח במקום להחליף מערך של טווח אחד במערך של טווח אחר.

אם אתם מחריגים מקור באמצעות --setting-sources ב-CLI או settingSources ב-Agent SDK, Claude Code מתעלם מרשומות ה-sandbox.filesystem שלו, מחוקי הרשאת Edit שלו, ומחוקי חסימת Read שלו בעת בניית הגדרות ארגז החול. דורש Claude Code בגרסה v2.1.246 ואילך.

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

קידומות נתיבים קובעות כיצד נתיבים נפתרים:

תחביר זה שונה מחוקי הרשאות Read ו-Edit, המשתמשים ב-//path עבור נתיב מוחלט וב-/path עבור נתיב יחסי לפרויקט. נתיבי מערכת הקבצים של ארגז החול משתמשים במוסכמות סטנדרטיות: /tmp/build הוא מוחלט. לגבי האופן שבו Claude Code מתייחס לקו נטוי מסיים או לתו כללי (wildcard) בנתיבים אלה, ראו קידומות נתיבים בארגז חול.

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

הדוגמה שלהלן חוסמת קריאה מכל תיקיית הבית תוך המשך התרת קריאה מהפרויקט הנוכחי. מקמו אותה ב-.claude/settings.json של הפרויקט שלכם, מכיוון שהנתיב היחסי . נפתר לשורש הפרויקט רק כאשר ההגדרה נמצאת בהגדרות פרויקט:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

אם הייתם ממקמים את אותה הגדרה ב-~/.claude/settings.json, הנתיב . היה נפתר ל-~/.claude במקום זאת, וקובצי הפרויקט היו נשארים חסומים על ידי חוק ה-denyRead.

כדי למנוע מפקודות בארגז חול גישת קריאה לתיקיות בית ולכוננים מעוגנים (mounted volumes) תוך שמירה על תיקיות העבודה כניתנות לקריאה, הגדירו את permissions.blockReadsOutsideWorkingDirectories במקום לכתוב חוקי נתיבים.

#השבתת בידוד מערכת הקבצים

הגדירו את sandbox.filesystem.disabled ל-true כדי לדלג על בידוד מערכת הקבצים תוך שמירה על בידוד הרשת. הדוגמה שלהלן מכבה את בידוד מערכת הקבצים תוך שמירה על רשימת היתרים של מתחמי רשת:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "disabled": true
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

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

ההגדרה כבויה כברירת מחדל וחלה בפלטפורמות שבהן ארגז החול פועל: macOS, Linux ו-WSL2. דורש Claude Code בגרסה v2.1.216 ואילך.

אזהרה: כאשר בידוד מערכת הקבצים כבוי ופקודות מאושרות אוטומטית (auto-allowed), פקודה בארגז חול יכולה לכתוב קבצים שפקודות מאוחרות יותר מריצות או קוראות, כגון קובצי אתחול של המעטפת, קבצים להפעלה ב-$PATH, או ~/.claude/settings.json, ולהשתמש בהם כדי להרחיב את הגישה של עצמה בהרצה הבאה. הגדירו את filesystem.disabled ל-true רק עבור עומסי עבודה שאתם סומכים עליהם שלא יסלימו את הגישה שלהם בעצמם. נעילת מתחמי רשת באמצעות allowManagedDomainsOnly מצמצמת את הסיכון אך אינה מסירה אותו, מכיוון שנעילה זו חלה רק על פקודות הרצות בתוך ארגז החול.

#אילו הגדרות יכולות להשבית אותו

מכיוון שכיבוי בידוד מערכת הקבצים מרחיב את מה שפקודות בארגז חול יכולות לעשות, Claude Code מכבד את filesystem.disabled ממקורות הגדרה אלה בלבד:

• הגדרות משתמש, הגדרות מנוהלות, ודגל ה-CLI בשם --settings יכולים להגדיר אותו. הגדרות פרויקט ב-.claude/settings.json וב-.claude/settings.local.json אינן יכולות, ולכן פרויקט ששוכפל (checked-out) אינו יכול לכבות את בידוד מערכת הקבצים.
• כאשר הגדרות מנוהלות מגדירות את sandbox.filesystem כלל, או מפרטות רשומת sandbox.credentials.files כלשהי עם "mode": "deny", רק הגדרות מנוהלות יכולות להגדיר מפתח זה. הדבר שומר על תוקפן של מגבלות מערכת הקבצים שנפרסו על ידי מנהל מערכת. כדי להקל על פריסה כזו, הגדירו "disabled": true בהגדרות מנוהלות.
• כאשר CLAUDE_CODE_SUBPROCESS_ENV_SCRUB מוגדר, Claude Code מתעלם מ-filesystem.disabled מכל מקור, כולל הגדרות מנוהלות, ומשאיר את בידוד מערכת הקבצים מופעל.

השאלה האם רשומת credentials.files מנוהלת נועלת (pins) את filesystem.disabled, ונועלת את המפתח להגדרות מנוהלות כך שמפתחים לא יוכלו לכבות את בידוד מערכת הקבצים, תלויה ב-mode של הרשומה ובמה שקורה לרשומה בעת הפעלת ארגז החול:

נסיגה (fallback) מתרחשת בעת הפעלת ארגז החול, לאחר ש-Claude Code כבר קרא את ההגדרות שעליהן פועלת בדיקת הנעילה, ולכן רשומה שנסוגה לעולם אינה נועלת. אימות כותב מחדש רשומה לא חוקית ל-deny בזמן טעינת ההגדרות, ולכן רשומה משונמכת נועלת בדיוק כמו רשומה שכתבתם כ-deny.

#מה משתנה כאשר בידוד מערכת הקבצים מושבת

הגדרת filesystem.disabled מסירה את ההגנות ששכבת מערכת הקבצים עצמה אוכפת. הגנות ששכבות אחרות אוכפות ממשיכות לחול:

שני דברים נוספים משתנים:

• פקודות בארגז חול יורשות את $TMPDIR של המעטפת שלכם במקום את התיקייה הזמנית של ההפעלה, מכיוון שכל תיקייה זמנית ניתנת לכתיבה ו-Claude Code אינו מפנה עוד פקודות לתיקייה של ההפעלה. ב-Linux המשתנה לרוב אינו מוגדר במעטפת האב, ולכן הוא עשוי להתרחב כריק בתוך פקודות בארגז חול. Claude Code מנחה את Claude דרך הוראות כלי ה-Bash שלו ליצור תיקיות עבודה זמניות באמצעות mktemp -d במקום להסתמך על $TMPDIR.
• autoAllowBashIfSandboxed עדיין מוגדר כברירת מחדל כ-true, ולכן פקודות בארגז חול ממשיכות לרוץ ללא בקשות אישור. הגדירו אותו כ-false כדי לבקש אישור עבור פקודות בארגז חול.

#הגנה על פרטי גישה

ההגדרה sandbox.credentials מצהירה על קובצי פרטי גישה ומשתני סביבה שיש להגן עליהם מפני פקודות בארגז חול. כל רשומה מציינת נתיב קובץ או משתנה סביבה ו-mode. בלוק ה-credentials הייעודי שומר על חוקי פרטי גישה מקובצים יחד ונפרדים מחוקי מערכת קבצים כלליים. דורש Claude Code בגרסה v2.1.187 ואילך.

עבור רשומות עם "mode": "deny", נתיבי קבצים נחסמים לקריאה בתוך ארגז החול, אותה הגבלה ש-filesystem.denyRead מחיל, ומשתני סביבה מוסרים (unset) לפני שכל פקודה בארגז חול רצה. הגנת הקבצים היא חלק משכבת מערכת הקבצים, ולכן היא אינה חלה אם תשביתו את בידוד מערכת הקבצים. הגנת משתני הסביבה עדיין חלה.

הדוגמה שלהלן חוסמת קריאות של קובץ פרטי הגישה של AWS ותיקיית ה-SSH, ומסירה את GITHUB_TOKEN ו-NPM_TOKEN מהסביבה של פקודות בארגז חול:

{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    }
  }
}

רשומות משתני סביבה ורשומות קבצים מקבלות גם "mode": "mask", המתואר תחת מיסוך פרטי גישה.

נתיבי קבצים מצייתים לאותם חוקי קידומות כמו הגדרות sandbox.filesystem.*.

Claude Code ממזג את רשומות ה-deny מכל טווח הגדרות שההפעלה טוענת. רשומת deny רק מצמצמת גישה, כך שכל טווח יכול להוסיף רשומה כזו, אך שום טווח אינו יכול להסיר רשומה שטווח אחר הוסיף.

כאשר אתם מחריגים מקור הגדרות:

• הגדרות פרויקט או הגדרות מקומיות: Claude Code אינו מחיל אף אחת מרשומות ה-credentials שלהן. דורש Claude Code בגרסה v2.1.246 ואילך.
• הגדרות משתמש: Claude Code עדיין מחיל את רשומות ה-deny ב-~/.claude/settings.json ושומר על רשומות ה-mask של קבצים כמגבלות, אך משמיט את רשומות ה-mask של משתני סביבה.

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

ההגדרה sandbox.credentials משפיעה על פקודות Bash בארגז חול בלבד. כדי להסיר פרטי גישה מכל תהליכי המשנה ללא קשר לארגז החול, הגדירו את CLAUDE_CODE_SUBPROCESS_ENV_SCRUB.

#מיסוך פרטי גישה

מיסוך מרחיק לכת יותר מרשומת deny תחת הגנה על פרטי גישה. במקום לחסום פרטי גישה, Claude Code מציג לפקודות בארגז חול ערך ממלא מקום (placeholder), הנקרא זקיף (sentinel), וה-proxy של ארגז החול מחליף אותו בערך האמיתי בבקשות יוצאות למארחים שאישרתם. עבור קבצים, ההחלפה היא התנהגות ב-Linux וב-WSL2. ב-macOS הקובץ נחסם במקום זאת.

#מיסוך משתני סביבה

"mode": "mask" מגן על פרטי גישה תוך שמירה על תפקוד הכלים המאמתים מולם. הערך deny מסיר את המשתנה לחלוטין, מה שגם שובר כלים הזקוקים לו, כגון gh או npm. דורש Claude Code בגרסה v2.1.199 ואילך.

עם mask, הפקודה בארגז חול רואה ערך זקיף ייחודי להפעלה במקום הערך האמיתי. כל רשומת mask יכולה לציין injectHosts, המארחים שהערך האמיתי מורשה להגיע אליהם. כאשר בקשה יוצאת מארגז החול אל אחד מהם, ה-proxy של ארגז החול מחליף את הזקיף בערך האמיתי. הפקודה וכל דבר שהיא מתעדת ביומן לעולם אינם מחזיקים בפרטי הגישה האמיתיים, אך בקשותיה עדיין עוברות אימות בהצלחה.

ה-proxy מחליף את פרטי הגישה בתוך תוכן הבקשה, ולכן עליו לראות אותם. הגדירו את network.tlsTerminate כדי שה-proxy יסיים בעצמו את ה-TLS.

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

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

ה-proxy מזריק ערכים רק בחיבורים שרשימת ההיתרים של המתחמים מאשרת, ולכן כל יעד ב-injectHosts חייב להיות נגיש גם דרך network.allowedDomains.

הדוגמה שלהלן ממסכת שני אסימונים. GH_TOKEN מוחלף רק בבקשות אל api.github.com, בעוד של-NPM_TOKEN אין injectHosts והוא מוחלף בבקשות לכל מארח ב-network.allowedDomains.

{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com", "registry.npmjs.org"]
    },
    "credentials": {
      "envVars": [
        { "name": "GH_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] },
        { "name": "NPM_TOKEN", "mode": "mask" }
      ]
    }
  }
}

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

• network.allowedDomains: התבנית בסוגריים מרובעים שרשימות מתחמים משתמשות בה, כגון "[::1]". ה-proxy בודק רשימה זו כדי לאשר את החיבור.
• injectHosts: הכתובת החשופה בצורתה הדחוסה הקנונית, כגון "::1" או "2001:db8::1". ה-proxy מתאים כל רשומה כנגד כתובת היעד החשופה של החיבור, תוך התעלמות מיציאות (ports), כך שאיות בסוגריים מרובעים, עם zone-ID, או בדחיסה שונה לעולם אינו מתאים וה-proxy לעולם אינו מזריק את פרטי הגישה לשם.

הפקודה claude doctor מסמנת רשומות injectHosts שלעולם אינן יכולות להתאים באזהרה Sandbox credential injectHosts entries can never match their destination. בדיקה זו דורשת Claude Code בגרסה v2.1.229 ואילך.

בניגוד ל-deny, מיסוך מסמיך את ה-proxy לשלוח את פרטי הגישה האמיתיים שלכם למארחים הרשומים, ולכן Claude Code מכבד זאת רק מהגדרות שאתם או מנהל המערכת שלכם שולטים בהן: הגדרות משתמש, הגדרות מנוהלות, ודגל ה-CLI בשם --settings. Claude Code מתעלם מרשומות mask ב-.claude/settings.json או ב-.claude/settings.local.json של מאגר. בקבצים אלה הוא מתעלם גם מ-network.tlsTerminate ומ-credentials.allowPlaintextInject, ההגדרה המאפשרת ל-proxy להזריק פרטי גישה לבקשות לא מוצפנות. אם אתם מחריגים הגדרות משתמש, Claude Code משמיט גם את רשומות ה-mask של משתני סביבה ב-~/.claude/settings.json.

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

כאשר אותו משתנה רשום עם deny בטווח כלשהו, deny מקבל עדיפות.

מיסוך מחליף את כל ערך המשתנה כברירת מחדל, מה שמתאים לאסימון פשוט. שדות רשומה אופציונליים, הדורשים Claude Code בגרסה v2.1.224 ואילך, מטפלים בערכים בעלי מבנה:

• extract: ביטוי רגולרי ש-Claude Code מחיל על הערך, ומחליף רק את הטקסט שנלכד על ידי קבוצה 1 של כל התאמה, כך שכלי המנתח את הערך, כגון מחרוזת חיבור של DATABASE_URL, עדיין פועל בתוך ארגז החול. התבנית חייבת להכיל לפחות קבוצת לכידה אחת.
• onExtractNoMatch שולט במה שקורה כאשר התבנית אינה מתאימה לדבר:
  • warn, ברירת המחדל, מזהיר ומעביר את המשתנה ללא מיסוך
  • deny מסיר (unsets) את המשתנה בתוך ארגז החול
  • error עוצר את הגדרת ארגז החול עד שתתקנו את התצורה
• decode: "jwt": עבור משתנה המחזיק JSON Web Token (JWT). Claude Code מאמת שהערך הוא JWT ומחליף אותו באסימון מזויף תקין מבנית, כך שקוד בתוך ארגז החול המפענח את האסימון ממשיך לפעול. הוסיפו maskClaims כדי לפרט תביעות (claims) עליונות במטען למסך בנפרד במקום להחליף את כל האסימון. שאר התביעות נשארות קריאות. כאשר הערך אינו מאומת כ-JWT, או שאף תביעה רשומה אינה מתאימה, Claude Code מעביר את המשתנה ללא מיסוך עם אזהרה. לא ניתן לשלב את decode עם extract.

ראו את שורות credentials.envVars[] במדריך ההגדרות לרשימת השדות המלאה.

#חתימה מחדש על בקשות AWS

בקשות AWS נושאות חתימות SigV4 על תוכן הבקשה, לכן יש למסך את AWS_ACCESS_KEY_ID ו-AWS_SECRET_ACCESS_KEY יחד. ה-proxy מזהה בקשת SigV4 לפי הזקיף של מפתח הגישה וחותם עליה מחדש לאחר החלפת הערכים האמיתיים. מיסוך הסוד לבדו משאיר בקשות חתומות עם הזקיף, דבר שה-proxy אינו יכול לזהות, ולכן הן נכשלות ב-AWS. Claude Code מזהיר לגבי מקרה זה בעת ההפעלה, אך לא כאשר רק מזהה מפתח הגישה ממוסך. בקשה שזוהתה וה-proxy אינו יכול לחתום עליה מחדש, כגון בקשה שחסרה בה כותרת x-amz-date, נכשלת עם שגיאת proxy במקום להגיע לשרת עם חתימה שגויה.

Claude Code מקשר את המשתנים המקובלים AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, ו-AWS_SESSION_TOKEN לפרט גישה יחיד באופן אוטומטי כאשר אתם ממסכים את כל ערכם. אם פרטי הגישה שלכם ל-AWS נמצאים במשתנים בעלי שמות אחרים, קבצו אותם בעצמכם באמצעות credentials.awsPairs, הדורש Claude Code בגרסה v2.1.224 ואילך. דוגמה זו מוסיפה את הצימוד לתצורה שכבר ממסכת את כל הערך של MY_KEY_ID, MY_SECRET_KEY, ו-MY_SESSION_TOKEN, כפי שמופיע בתצורת המיסוך לעיל:

{
  "sandbox": {
    "credentials": {
      "awsPairs": [
        {
          "accessKeyIdVar": "MY_KEY_ID",
          "secretAccessKeyVar": "MY_SECRET_KEY",
          "sessionTokenVar": "MY_SESSION_TOKEN"
        }
      ]
    }
  }
}

כל רשומה מצייתת לכללים אלה:

• accessKeyIdVar ו-secretAccessKeyVar מציינים את שמות רשומות ה-envVars הממוסכות המחזיקות את מזהה מפתח הגישה ואת המפתח הסודי. השדה האופציונלי sessionTokenVar מציין את שם הרשומה המחזיקה את אסימון ההפעלה (session token) עבור פרטי גישה זמניים. כאשר הוא מוגדר, ה-proxy שולח את האסימון האמיתי כ-x-amz-security-token בבקשות שנחתמו מחדש.
• כל משתנה בעל שם חייב להיות רשומת mask הממסכת את כל ערכו, ללא extract או decode.
• ה-proxy חותם מחדש על בקשות במארחים המפורטים ב-injectHosts של רשומת מזהה מפתח הגישה.
• ציון שמו של אחד מהמשתנים המקובלים בצמד מחליף את הצימוד האוטומטי.

בדומה לרשומות mask, ההגדרה awsPairs מכובדת רק מהגדרות משתמש, הגדרות מנוהלות, ודגל ה-CLI בשם --settings.

שלוש תבניות בקשה של AWS נושאות חתימות שה-proxy אינו יכול לחשב מחדש. כאשר בקשה כזו חתומה עם זקיף של צמד ממוסך, ה-proxy מכשיל אותה במקום להעביר חתימה שגויה. בקשות החתומות בפרטי גישה שאינם ממוסכים אינן מושפעות לעולם. ההגדרה credentials.sigv4, הדורשת Claude Code בגרסה v2.1.224 ואילך, מקלה על כך לפי תבנית: הגדרת מפתח של תבנית ל-passthrough מעבירה הלאה את הבקשה עם החתימה שנגזרה מהזקיף, כך שהכלי הקורא מקבל את תגובת הדחייה של AWS עצמה במקום שגיאת proxy. בדומה ל-awsPairs, ההגדרה sigv4 מכובדת רק מהגדרות משתמש, הגדרות מנוהלות, ודגל ה-CLI בשם --settings.

#מיסוך קובצי פרטי גישה

רשומות קבצים מקבלות גם "mode": "mask", הדורש Claude Code בגרסה v2.1.221 ואילך. מה שפקודה בארגז חול רואה תלוי בפלטפורמה:

• Linux ו-WSL2: פקודות בארגז חול קוראות עותק זקיף של הקובץ, מעין תחליף שהסוד בו מוחלף בערך ממלא מקום, וה-proxy של ארגז החול מחליף את הערך האמיתי ביציאה.
• macOS: פקודות בארגז חול אינן יכולות לקרוא את הקובץ הרשום כלל. Claude Code אינו בונה עותק זקיף ואינו מחליף דבר ביציאה, ולכן כלים המאמתים באמצעות הקובץ אינם פועלים בתוך ארגז החול, אותה השפעה כמו deny. בניגוד לרשומת deny, חסימת הקריאה נשמרת אפילו כאשר אתם משביתים את בידוד מערכת הקבצים.

בכל פלטפורמה, Claude Code מחיל את דרישת network.tlsTerminate ואת injectHosts באותו אופן כמו עבור משתני סביבה ממוסכים, ומתעלם מהגדרות מאגר באותו אופן. אם אתם מחריגים הגדרות משתמש, Claude Code שומר על רשומות ה-mask של קבצים ב-~/.claude/settings.json כמגבלות, אך הרשומות אינן מסמיכות עוד את ה-proxy להחליף את הערך האמיתי.

הדוגמה שלהלן ממסכת אסימון GitHub המאוחסן ב-~/.config/gh/hosts.yml. תבנית ה-extract, המוסברת להלן, מציינת ל-Claude Code איזה חלק בקובץ הוא הסוד. ב-Linux וב-WSL2, פקודות בארגז חול הקוראות את הקובץ מקבלות זקיף במקום האסימון, וה-proxy מחליף את האסימון האמיתי בבקשות ל-api.github.com:

{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com"]
    },
    "credentials": {
      "files": [
        {
          "path": "~/.config/gh/hosts.yml",
          "mode": "mask",
          "extract": "oauth_token:\\s*(\\S+)",
          "injectHosts": ["api.github.com"]
        }
      ]
    }
  }
}

כדי לוודא שהמיסוך פעיל, בקשו מ-Claude להריץ cat ~/.config/gh/hosts.yml בפקודה בארגז חול: ב-Linux וב-WSL2 הפלט מציג ערך זקיף במקום האסימון, וב-macOS הקריאה נכשלת במקום זאת.

ב-Linux וב-WSL2, תבנית ה-extract היא מה ששומר על שאר hosts.yml כניתן לקריאה. Claude Code מחיל את הביטוי הרגולרי על כל הקובץ ומחליף רק את הטקסט שנלכד על ידי קבוצה 1 של כל התאמה, כך ש-gh עדיין מנתח את התצורה שלו ורק האסימון הוא ערך ממלא מקום. השתמשו ב-extract עבור כל קובץ מובנה שכלים מנתחים, כגון .netrc, JSON, או YAML. התבנית חייבת להכיל לפחות קבוצת לכידה אחת. ללא extract, Claude Code מחליף את כל תוכן הקובץ בערך זקיף אחד, מה שמתאים לקובץ המחזיק סוד פשוט יחיד ותו לא.

עבור קובץ המחזיק JSON Web Token (JWT), הגדירו decode: "jwt" במקום extract, או יחד איתו. השדה decode דורש Claude Code בגרסה v2.1.224 ואילך. Claude Code מאתר מועמדי JWT באמצעות תבנית מובנית, או באמצעות תבנית ה-extract שלכם כאשר היא מוגדרת, מאמת שכל מועמד הוא JWT, ומחליף אותו באסימון מזויף תקין מבנית, כך שקוד המפענח את האסימון בתוך ארגז החול ממשיך לפעול. הוסיפו maskClaims כדי למסך רק את התביעות העליונות הנקובות בתוך כל אסימון מאומת ולהשאיר את שאר התביעות קריאות. כאשר אף מועמד אינו מאומת, או שאף תביעה נקובה אינה מתאימה, השדה onExtractNoMatch להלן קובע את התוצאה, בדיוק כפי שהוא עושה עבור תבנית שאינה מתאימה לדבר.

שני שדות אופציונליים מדייקים את התנהגות ההתאמה. שניהם חלים רק כאשר mode הוא mask ומוגדר extract או decode. ב-macOS, Claude Code מחיל רשומות mask כ-deny לפני שהתבנית רצה בכל עת שבידוד מערכת הקבצים פועל, ולכן שדות אלה, ותוצאות אי-ההתאמה להלן, נכנסים לתוקף שם רק כאשר בידוד מערכת הקבצים מושבת:

• onExtractNoMatch שולט במה שקורה כאשר ההתאמה אינה מוצאת דבר למסך בקובץ:
  • warn, ברירת המחדל, מזהיר ומדלג על הרשומה, כך שפקודות בארגז חול יכולות לקרוא את הקובץ האמיתי ללא מיסוך. ברירת המחדל מתאימה לפרטי גישה שעשויים להיעדר באופן לגיטימי. אם הסוד עשוי להיות נוכח אך התבנית עלולה לפספס אותו, השתמשו ב-deny
  • deny הופך את הקובץ לבלתי ניתן לקריאה במקום זאת
  • error עוצר את הגדרת ארגז החול עד שתתקנו את התצורה Claude Code מתייחס ל-deny כאל error בכל פעם שחסימת הקריאה לא תיאכף: כאשר אתם משביתים את בידוד מערכת הקבצים, וכאשר רשומת filesystem.allowRead ממקור הגדרות כלשהו פותחת מחדש את נתיב הקובץ.
• maskDuplicates מחליף גם עותקים מדויקים של כל ערך פרטי גישה ממוסך, לכידת extract או אסימון מאומת decode, שנמצאו מחוץ לטווחי ההתאמה, עבור סוד שחוזר על עצמו במקומות שההתאמה אינה מגיעה אליהם. הוא מתאים מחרוזות משנה גולמיות, ולכן ערך קצר או נפוץ יוחלף בכל מקום שבו הוא מופיע. שמרו אותו עבור סודות ארוכים בעלי אנטרופיה גבוהה. ברירת מחדל: false.

הערך mask חל על קובץ יחיד, לכן רשמו כל קובץ פרטי גישה בנפרד. Claude Code נסוג ל-deny עבור רשומת mask שאינו יכול למסך בבטחה: נתיב תיקייה, תבנית glob, קובץ הגדול מ-8 MiB, או קובץ שאינו טקסט UTF-8. כתבו תיקיות כרשומות deny מפורשות במקום זאת. הטבלה תחת אילו הגדרות יכולות להשבית אותו מכסה האם כל תבנית נועלת את filesystem.disabled וכיצד היא מתנהגת כאשר בידוד מערכת הקבצים כבוי.

#כיצד ארגז החול פועל

#בידוד מערכת הקבצים

כלי ה-Bash בארגז חול מגביל את הגישה למערכת הקבצים לתיקיות ספציפיות:

• התנהגות כתיבה כברירת מחדל: גישת קריאה וכתיבה לתיקיית העבודה הנוכחית ותיקיות המשנה שלה, כל תיקייה שהוספתם באמצעות --add-dir, /add-dir, או permissions.additionalDirectories, בנוסף לתיקייה הזמנית של ההפעלה ש-$TMPDIR מצביע עליה.
• התנהגות קריאה כברירת מחדל: גישת קריאה למחשב כולו, למעט תיקיות מסוימות שנחסמו. שימו לב שברירת מחדל זו עדיין מתירה קריאת קובצי פרטי גישה כגון ~/.aws/credentials ו-~/.ssh/. השתמשו ב-sandbox.credentials כדי לחסום קריאות של קבצים אלה ולהסיר משתני סביבה סודיים, או הוסיפו את הנתיבים ל-denyRead.
• גישה חסומה: לא ניתן לשנות קבצים מחוץ לתיקיית העבודה, לתיקיות שנוספו, ולתיקייה הזמנית של ההפעלה ללא אישור מפורש, כולל קובצי הגדרות מעטפת כגון ~/.bashrc וקובצי מערכת בינאריים ב-/bin/.
• עצי עבודה של Git (worktrees): כאשר תיקיית העבודה היא עץ עבודה מקושר של git, ארגז החול מתיר גם כתיבה לתיקיית .git המשותפת של המאגר הראשי, כך שפקודות כגון git commit יכולות לעדכן מצביעים (refs) ואת האינדקס. כתיבה ל-hooks/ ול-config בתוך תיקייה זו נשארת חסומה.
• ניתן להגדרה: הגדרת נתיבים מותאמים אישית מורשים וחסומים דרך הגדרות.

כדי לדלג על בידוד מערכת הקבצים לחלוטין תוך שמירה על בידוד הרשת, הגדירו את sandbox.filesystem.disabled.

#נתיבים מוגנים

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

• בתיקיית העבודה שלכם ובתיקיות שמעליה: קובצי ההגדרות של .claude, התיקיות .claude/skills, .claude/agents, .claude/commands, ו-.claude/hooks, הקובץ .mcp.json, והקבצים ש-Claude Code מריץ בעצמו, כגון .claude/workflows ו-.claude/scheduled_tasks.json.
• בתיקיית העבודה שלכם בלבד: קובצי אתחול מעטפת כגון .bashrc ו-.zshrc, הקובץ .gitconfig, התיקיות .vscode ו-.idea, וכן hooks ו-config בתוך .git.
• קבצים שהיו הופכים את תיקיית העבודה שלכם למאגר git חשוף (bare git repository): HEAD, objects, ו-refs ברמה העליונה, וכן config ו-hooks שם כאשר הם כבר קיימים, אפילו כאשר תיקיית config שייכת לפרויקט שלכם ולא ל-git. ב-Linux וב-WSL2, ארגז החול מוחק קובץ HEAD או תיקיית objects או refs ברמה העליונה שמופיעים בזמן שפקודה בארגז חול רצה.
• בתוך ~/.claude, או התיקייה ש-CLAUDE_CONFIG_DIR מצביע עליה: רוב התוכן שלה, בתוספת ~/.claude.json ומאגר פרטי הגישה .credentials.json.

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

אין דרך להחריג אחד מנתיבים אלה: רשומת allowWrite או חוק הרשאת Edit המכסים את הנתיב אינם מסירים את ההגנה. הדרך היחידה לכבות את ההגנה היא filesystem.disabled, המכבה את בידוד מערכת הקבצים עבור כל נתיב. כדי לראות את רוב הנתיבים הללו כפי שנפתרו עבור המחשב שלכם, הריצו /sandbox ופתחו את לשונית Config, המפרטת אותם תחת Denied within allowed, כשהם מעורבבים עם רשומות ה-denyWrite שלכם.

אם git merge או git checkout נכשלים עם השגיאה unable to unlink old באחד מנתיבים אלה, ראו פתרון בעיות.

#בידוד רשת

גישת רשת נשלטת באמצעות שרת proxy הרץ מחוץ לארגז החול:

• מגבלות מתחם: Claude Code אינו מאשר מראש שום מתחם כברירת מחדל. בפעם הראשונה שפקודה זקוקה למתחם חדש, Claude Code מבקש אישור, או שבמצב auto הוא שולח את הבקשה למסווג. אם תבחרו Yes כאשר תתבקשו, Claude Code מתיר את המארח להמשך ההפעלה הנוכחית ואינו מבקש שוב בחיבורים מאוחרים יותר לאותו מארח. אם תבחרו "Yes, and don't ask again", Claude Code שומר חוק אישור מסוג WebFetch(domain:...) בהגדרות המקומיות שלכם, כך שהמארח נשאר מורשה בהפעלות עתידיות. אש רו מראש מתחמים באמצעות allowedDomains כדי להימנע מבקשת האישור לחלוטין. Claude Code גם מאשר מראש מתחמים מחוקי אישור מסוג WebFetch(domain:...), כמתואר בסעיף חוקי הרשאות.
• רשימת היתרים מחמירה (strict allowlist): אם תגדירו את strictAllowlist כ-true בהגדרות משתמש, בהגדרות מנוהלות, או בדגל --settings ב-CLI, Claude Code מונע מפקודות בארגז חול גישה לכל מארח מחוץ לרשימת ההיתרים במקום לבקש אישור. רשימת ההיתרים היא אותה רשימה שארגז החול מבקש אישור מולה במקרים אחרים: allowedDomains בתוספת מתחמים מחוקי אישור WebFetch(domain:...), או רק רשומות ההגדרות המנוהלות כאשר allowManagedDomainsOnly מוגדר. Claude Code אוכף זאת עבור פקודות בארגז חול בלבד. כלים הפועלים בתוך התהליך כגון WebFetch עדיין מצייתים לחוקי ההרשאות שלהם. להגדרה זו בתוך .claude/settings.json או .claude/settings.local.json של מאגר אין כל השפעה. דורש Claude Code בגרסה v2.1.219 ואילך.
• סגר מנוהל (managed lockdown): אם allowManagedDomainsOnly מוגדר בהגדרות מנוהלות, מתחמים שאינם מורשים נחסמים אוטומטית במקום להציג בקשת אישור, ורק allowedDomains וחוקי אישור WebFetch(domain:...) מהגדרות מנוהלות מכובדים.
• שרת proxy ארגוני: כאשר הרשת שלכם דורשת שתעבורה יוצאת תעבור דרך proxy ארגוני, הגדירו את HTTPS_PROXY, HTTP_PROXY, ו-NO_PROXY כפי שמתואר בהגדרת proxy, בבלוק ה-env של ההגדרות שלכם כדי שגם סוכני רקע יקבלו אותם, או בסביבה שממנה אתם מפעילים את Claude Code. Claude Code אוכף את רשימת ההיתרים של המתחמים ולאחר מכן מנתב חיבורים מורשים במנהרה (tunnels) דרך שרת ה-proxy במעלה הזרם.
• תמיכה ב-proxy מותאם אישית: משתמשים מתקדמים יכולים ליישם חוקים מותאמים אישית על תעבורה יוצאת.
• כיסוי מקיף: המגבלות חלות על כל התסריטים, התוכניות ותהליכי המשנה הנוצרים על ידי פקודות.

בחוק WebFetch(domain:...), ארגז החול מכבד שתי תבניות של תו כללי (wildcard): קידומת *., כגון *.example.com, ותו כללי בודד *. תבנית ה-* הבודד דורשת Claude Code בגרסה v2.1.186 ואילך. תו כללי בכל מיקום אחר, כגון WebFetch(domain:example.*), עדיין תואם לאחזורי רשת אך אין לו השפעה על פקודות בארגז חול.

הערה: שרת ה-proxy המובנה אוכף את רשימת ההיתרים על בסיס שם המארח המבוקש, וכברירת מחדל אינו מסיים ואינו בודק תעבורת TLS. ההגדרה הניסיונית network.tlsTerminate, הזמינה ב-Claude Code בגרסה v2.1.199 ואילך, גורמת ל-proxy המובנה לסיים TLS בעצמו, דרישה הנדרשת עבור רשומות פרטי גישה מסוג mask. ראו מגבלות אבטחה להשלכות של ברירת המחדל, ואת הגדרת שרת proxy מותאם אישית אם מודל האיומים שלכם דורש בדיקת TLS.

#כתובות IPv6 ברשימות מתחמים

רשימות המתחמים של ארגז החול הן allowedDomains, deniedDomains, וחוקי ה-WebFetch(domain:...) המזינים אותן. כדי להתאים כתובת IPv6 באחת מהן, כתבו את הערך המילולי בסוגריים מרובעים: "[::1]" מתאים לכתובת זו בכל יציאה, ו-"[::1]:443" מתאים לה ביציאה 443 בלבד. כתבו את היציאה כמספר מ-1 עד 65535 ללא אפסים מובילים. תבנית הסוגריים המרובעים דורשת Claude Code בגרסה v2.1.229 ואילך. לפני גרסה v2.1.229, כאשר הטקסט שאחרי הנקודתיים האחרונות ברשומה ללא סוגריים היה מספר יציאה, Claude Code קרא אותו ככזה, כך ש-::1:443 ציין את הכתובת ::1 ביציאה 443.

כאשר אתם בוחרים "Yes, and don't ask again" בבקשת אישור הרשת עבור כתובת IPv6, Claude Code שומר את חוק ה-WebFetch(domain:...) כשהכתובת בסוגריים מרובעים, כך שהחוק ימשיך להתאים לכתובת בהפעלות עתידיות.

רשומה ללא סוגריים מרובעים עם שני זוגות נקודתיים או יותר היא דו-משמעית: ::1:443 היא גם כתובת IPv6 מלאה וגם כתובת שאחריה יציאה. Claude Code אוכף איותים דו-משמעיים באופן שמרני במקום לנחש לאיזו משמעות התכוונתם:

• רשימות חסימה (deny lists): Claude Code חוסם כל משמעות שהרשומה מתפרשת לפיה, כך שכל משמעות שהתכוונתם אליה נחסמת. עבור רשומה שאין לה פירוש תקף, Claude Code אינו חוסם דבר.
• רשימות היתר (allow lists): Claude Code לעולם אינו מתיר יותר ממה שכתבתם. הוא כותב מחדש רשומה דו-משמעית לפירוש המארח-והיציאה שלה כאשר פירוש זה מתפרש בצורה נקייה, ועשוי להשמיט את הרשומה לחלוטין במקום להרחיב את רשימת ההיתרים.

הריצו claude doctor במסוף שלכם כדי למצוא את הרשומות המושפעות: האזהרה Sandbox network domain entries have unreliable spellings מציינת עד שלוש מהן ומונה את השאר. כתבו מחדש כל אחת מהן בצורה עם סוגריים מרובעים כדי לנקות את האזהרה. האזהרה מציינת גם רשומות שהאיות שלהן אינו אמין מסיבות אחרות, כגון תווים כמו @, תווי נתיב או שאילתה, או תווים כלליים בתוך סוגריים מרובעים.

#אכיפה ברמת מערכת ההפעלה

כלי ה-Bash בארגז חול משתמש ברכיבי אבטחה בסיסיים של מערכת ההפעלה:

• macOS: משתמש ב-Seatbelt לאכיפת ארגז החול
• Linux: משתמש ב-bubblewrap לצורך בידוד
• WSL2: משתמש ב-bubblewrap, בדיוק כמו ב-Linux

מערכת WSL1 אינה נתמכת מכיוון ש-bubblewrap דורש תכונות ליבה (kernel) הזמינות רק ב-WSL2.

אותם רכיבים בסיסיים זמינים כחבילה עצמאית בשם @anthropic-ai/sandbox-runtime, שדף סביבות ארגז חול מכסה כגישה נפרדת לעטיפת כל תהליך Claude Code.

#כיצד ארגז החול מתקשר להרשאות ולמצבי הרשאה

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

#חוקי הרשאות

חוקי הרשאות וארגז חול שולטים בדברים שונים:

• חוקי הרשאות שולטים באילו כלים Claude Code יכול להשתמש ומוערכים לפני שכל כלי רץ. הם חלים על כל כלי: Bash, Read, Edit, WebFetch, MCP, ואחרים, למעט העובדה שחוק deny או ask אינו יכול לחסום את EndConversation כל עוד כלי אחר נותר זמין.
• ארגז חול מספק אכיפה ברמת מערכת ההפעלה המגבילה את מה שפקודות Bash יכולות לגשת אליו ברמת מערכת הקבצים והרשת. הוא חל רק על פקודות Bash ותהליכי הצאצא שלהן.

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

מגבלות מערכת הקבצים והרשת מוגדרות הן דרך הגדרות ארגז החול והן דרך חוקי הרשאות:

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

תיקיית הדוגמאות במאגר של claude-code כוללת תצורות הגדרות פתיחה לתרחישי פריסה נפוצים, כולל דוגמאות ספציפיות לארגז חול. השתמשו בהן כנקודות מוצא והתאימו אותן לצורכיכם.

#מצבי הרשאה

הפקודה /sandbox אינה מצב הרשאה. מצבי הרשאה קובעים האם קריאה לכלי תרוץ והאם תתבקשו לאשר אותה תחילה, בעוד שארגז החול מגביל את מה שפקודת Bash יכולה לגשת אליו לאחר שהיא רצה. הם נבדלים במה שהם שולטים בו ובמה שמחליף את בקשת האישור לכל פעולה:

מצב auto-allow של ארגז החול נפרד ממצב auto: מצב auto-allow מאשר פקודות Bash מכיוון שגבול ארגז החול מגביל אותן, בעוד שמצב auto משתמש במסווג כדי לבחון פעולות. השניים פועלים באופן עצמאי וניתן לשלב ביניהם. כדי לבחור גבול בידוד להרצות ללא השגחה, ראו סביבות ארגז חול. לטבלה של שילובי מצבי הרשאה וארגז חול נפוצים עם הדגלים המפעילים כל אחד מהם, ראו תצורות נפוצות.

#הגדרת ארגז החול עבור הארגון שלכם

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

#אכיפת ארגז חול באמצעות הגדרות מנוהלות

כדי לדרוש את ארגז החול עבור כל מפתח, העבירו את מפתחות ה-sandbox דרך הגדרות מנוהלות, בין אם כקובץ המנוהל על ידי ה-MDM שלכם ובין אם דרך הגדרות מנוהלות שרת ב-Claude.ai.

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

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

שני המפתחות מעבר ל-enabled שולטים במה שקורה כאשר ארגז החול אינו יכול להריץ פקודה:

• failIfUnavailable: תלות חסרה כגון bubblewrap ב-Linux חוסמת את הפעלת Claude Code במקום להציג אזהרה ולסגת להרצה ללא ארגז חול.
• allowUnsandboxedCommands: false: המערכת Claude Code מתעלמת מפתח המילוט dangerouslyDisableSandbox, כך שכאשר פקודה נכשלת תחת ארגז החול, Claude אינו יכול לנסות אותה שוב ללא ארגז חול.

כדאי לשקול שתי תוספות לצידם. הוסיפו את excludedCommands עבור כלים המאושרים על ידי הארגון שחייבים לרוץ ללא בידוד. הוסיפו רשומות sandbox.credentials עבור תיקיות פרטי גישה כגון ~/.aws ו-~/.ssh ועבור משתני סביבה סודיים, מכיוון שמדיניות הקריאה כברירת מחדל עדיין מתירה אותם.

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

ארגז החול אינו פועל ב-Windows טבעי, לכן אם הצי שלכם כולל מחשבי Windows, הגדירו תצורה זו עבור macOS ו-Linux או דאגו שמשתמשים אלה יריצו את Claude Code בתוך WSL2 או קונטיינר.

#מניעה ממפתחים להרחיב את המדיניות

עבור מפתחות בוליאניים כגון enabled ו-failIfUnavailable, Claude Code משתמש בערך המנוהל ומתעלם מכל מה שמפתח מגדיר מקומית. עבור מפתחות מערך כגון excludedCommands ו-allowRead, Claude Code ממזג רשומות מכל טווח שההפעלה טוענת, כך שמפתח יכול להוסיף רשומות המרחיבות את המדיניות.

הגדירו את allowManagedReadPathsOnly ל-true בהגדרות מנוהלות כך שרק רשומות allowRead מהגדרות מנוהלות יכובדו. הדבר מונע ממפתחים להרחיב את גישת הקריאה מעבר לנתיבים שאושרו על ידי הארגון. כדי לנעול מתחמי רשת לערכים המנוהלים באותו אופן, הגדירו את allowManagedDomainsOnly.

כאשר הגדרות מנוהלות מגדירות את sandbox.filesystem או רושמות רשומת sandbox.credentials.files כלשהי עם "mode": "deny", רק הגדרות מנוהלות יכולות להגדיר את filesystem.disabled, כך שמפתחים אינם יכולים לכבות מגבלות מערכת קבצים שהוגדרו על ידי מנהל מערכת. השאלה האם רשומת mask נועלת את המפתח תלויה באופן שבו היא נפתרת. הטבלה תחת אילו הגדרות יכולות להשבית אותו מכסה את ארבעת המקרים.

ל-excludedCommands אין נעילה מנוהלת שקולה, ולכן מפתח תמיד יכול להוסיף רשומות המריצות פקודות נוספות מחוץ לארגז החול. שמרו על הרשימה המנוהלת מצומצמת.

#הגדרת שרת proxy מותאם אישית

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

• לפענח ולבדוק תעבורת HTTPS
• להחיל חוקי סינון מותאמים אישית
• לרשום ביומן (log) את כל בקשות הרשת
• להשתלב בתשתית האבטחה הקיימת

כדי להפנות את Claude Code לשרת ה-proxy שלכם, הגדירו את יציאות ה-proxy בהגדרות ארגז החול:

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

#פתרון בעיות

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

• פקודות נכשלות עם שגיאת מארח לא מורשה (host-not-allowed): כלי CLI רבים צריכים לגשת למארחים ספציפיים. מתן הרשאה כאשר תתבקשו מוסיף את המארח לרשימת ההיתרים שלכם כך שהכלי ירוץ בתוך ארגז החול בעתיד.
• jest נתקע או נכשל: הכלי watchman אינו תואם לארגז החול. הריצו jest --no-watchman במקום זאת.
• כלי CLI מבוססי Go נכשלים באימות TLS ב-macOS: כלים כגון gh, gcloud, ו-terraform עלולים להיכשל באימות TLS תחת Seatbelt. רשמו כלים אלה ב-excludedCommands כדי להריץ אותם מחוץ לארגז החול. אם אתם משתמשים ב-httpProxyPort עם proxy מסוג MITM ותעודת CA מותאמת אישית, הגדירו את enableWeakerNetworkIsolation ל-true במקום זאת.
• פקודות open, osascript, או תהליכי אימות מבוססי דפדפן נכשלים עם שגיאה -600 ב-macOS: ארגז החול חוסם אירועי Apple Events כברירת מחדל. הגדירו את allowAppleEvents ל-true בהגדרות המשתמש, ההגדרות המנוהלות או הגדרות ה-CLI שלכם כדי לאפשר אותם. הגדרות פרויקט מתעלמות ממפתח זה. הפעלתו מסירה את בידוד הרצת הקוד, מכיוון שפקודות בארגז חול יכולות אז להפעיל יישומים אחרים ללא ארגז חול וללא בקשת אישור מהמשתמש ולשלוח פקודות AppleScript ליישומים רצים, בכפוף להודעת הסכמת האוטומציה של macOS (TCC). לחלופין, הוסיפו את הפקודה ל-excludedCommands כדי להריץ אותה מחוץ לארגז החול.
• פקודות docker נכשלות: הכלי docker אינו תואם לארגז החול. הוסיפו docker * ל-excludedCommands כדי להריץ אותו מחוץ לארגז החול.
• הפקודות pbcopy, xclip, או wl-copy אינן מעדכנות את לוח הגזירים (clipboard): כלי לוח אלה עשויים להיכשל בהגעה ללוח הגזירים של המערכת מתוך ארגז החול, ובמקרה זה הטקסט המוזרם אליהם אינו מגיע. כדי להציב את הפלט של Claude בלוח שלכם, בקשו מ-Claude להדפיס אותו בתשובתו, ולאחר מכן הריצו את הפקודה /copy, הכותבת ללוח מתהליך Claude Code עצמו ולא מפקודה בארגז חול. לחלופין, הוסיפו pbcopy *, wl-copy *, או xclip * ל-excludedCommands כדי להריץ את הפקודה מחוץ לארגז החול.
• פקודת git נכשלת עם unable to unlink old: הפקודות git merge, git checkout, ופקודות דומות נכשלות באופן זה כאשר הן צריכות להחליף קובץ שארגז החול מונע כתיבה אליו, בין אם קובץ זה נמצא תחת נתיב מוגן כגון .claude/skills, תחת אחת מרשומות ה-denyWrite שלכם, או מחוץ לתיקיות שארגז החול מאפשר לפקודות לכתוב אליהן כלל. ב-Linux וב-WSL2 השגיאה מסתיימת ב-Read-only file system. לאחר הכישלון, Claude עשוי להציע להריץ מחדש את הפקודה מחוץ לארגז החול. אשרו ניסיון חוזר זה, או הריצו את פקודת ה-git בעצמכם במסוף אחר. אם הגדרתם את allowUnsandboxedCommands ל-false, Claude אינו יכול להציע את הניסיון החוזר, לכן הריצו את הפקודה בעצמכם. אם אותה פקודת git נכשלת לעיתים קרובות, הוסיפו אותה ל-excludedCommands.
• הפעלת Bubblewrap נכשלת בתוך קונטיינר: בקונטיינר ללא הרשאות מיוחדות (unprivileged), הכלי bubblewrap אינו יכול לעגן (mount) מערכת קבצים /proc חדשה, ולכן פקודות בארגז חול נכשלות עם שגיאת bwrap כגון Can't mount proc on /newroot/proc: Operation not permitted. הגדירו את enableWeakerNestedSandbox ל-true כדי שארגז החול הפנימי יעגן (bind-mounts) את ה-/proc הקיים של הקונטיינר במקום זאת. השתמשו בהגדרה זו רק כאשר הקונטיינר החיצוני כבר מספק את גבול הבידוד הדרוש לכם, מכיוון שהיא חושפת לפקודות בארגז חול מידע על תהליכים שעיגון /proc חדש היה מסתיר.
• דגל --dangerously-skip-permissions נכשל בהרצה כמשתמש root: דגל זה חסום בעת הרצה כ-root או באמצעות sudo ב-Linux וב-macOS, מכיוון שגישת root בשילוב ללא בקשות אישור עלולה לשנות כל קובץ או שירות במערכת. הבדיקה מדולגת אוטומטית בתוך ארגז חול מזוהה. כדי לרוץ באופן אוטונומי בתוך קונטיינר, השתמשו בתצורת dev container, המריצה את Claude Code כמשתמש שאינו root.

#מגבלות

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

#מגבלות אבטחה

• סינון רשת: ארגז החול מגביל לאילו מתחמים תהליכים יכולים להתחבר. כברירת מחדל ה-proxy המובנה אינו מסיים (terminate) ואינו בודק תעבורת TLS בתעבורה יוצאת, כך שתוכן של חיבורים מוצפנים אינו נבדק. ההגדרה הניסיונית network.tlsTerminate מסיימת TLS ב-proxy עבור החלפת פרטי גישה עם mask, אך אינה מוסיפה סינון תוכן. באחריותכם להבטיח שרק מתחמים מהימנים מורשים במדיניות שלכם.

אזהרה: התרת מתחמים רחבים כגון github.com עלולה ליצור נתיבים לדליפת נתונים (data exfiltration). מכיוון שה-proxy מקבל את החלטת ההיתר משם המארח שסופק על ידי הלקוח מבלי לבדוק TLS, קוד הרץ בתוך ארגז החול עשוי להשתמש בטכניקות כמו domain fronting או טכניקות דומות כדי להגיע למארחים מחוץ לרשימת ההיתרים. אם מודל האיומים שלכם דורש ערובות חזקות יותר, הגדירו proxy מותאם אישית שמסיים TLS ובודק תעבורה, והתקינו את תעודת ה-CA שלו בתוך ארגז החול. בידוד רשת מודע-TLS חזק יותר נמצא בפיתוח פעיל.

• הסלמת הרשאות דרך שקעי Unix (Unix sockets): התצורה allowUnixSockets עלולה להעניק בשוגג גישה לשירותי מערכת שעלולים להוביל לעקיפת ארגז החול. לדוגמה, התרת גישה ל-/var/run/docker.sock מעניקה למעשה גישה למערכת המארחת דרך שקע ה-Docker. שקלו היטב כל שקע Unix שאתם מאפשרים דרך ארגז החול.
• הסלמת הרשאות במערכת הקבצים: הרשאות כתיבה רחבות מדי במערכת הקבצים יכולות לאפשר התקפות הסלמת הרשאות. התרת כתיבה לתיקיות המכילות קובצי הפעלה ב-$PATH, לתיקיות הגדרות מערכת, או לקובצי הגדרות מעטפת של משתמש כגון .bashrc או .zshrc עלולה להוביל להרצת קוד בהקשרי אבטחה שונים כאשר משתמשים אחרים או תהליכי מערכת ניגשים לקבצים אלה.
• חוזק ארגז החול ב-Linux: המימוש ב-Linux מספק בידוד חזק של מערכת הקבצים והרשת, אך כולל מצב בשם enableWeakerNestedSandbox המאפשר לו לפעול בתוך סביבות Docker ללא namespaces בעלי הרשאות, או במארחי Linux שבהם namespaces של משתמשים ללא הרשאות מושבתים על ידי sysctl. אפשרות זו מחלישה באופן ניכר את האבטחה ויש להשתמש בה רק כאשר בידוד נוסף נאכף בדרך אחרת.
• אירועי Apple Events ב-macOS: ארגז החול ב-macOS חוסם אירועי Apple Events כברירת מחדל. ההגדרה allowAppleEvents מסירה הגבלה זו כך שכלים כמו open ו-osascript יעבדו, אך היא מסירה את בידוד הרצת הקוד: פקודות בארגז חול יכולות אז להפעיל יישומים אחרים ללא ארגז חול וללא בקשת אישור מהמשתמש, ויכולות לשלוח פקודות AppleScript ליישומים רצים, בכפוף להודעת הסכמת האוטומציה של macOS (TCC) לכל יישום. ההגדרה מכובדת רק מהגדרות משתמש, הגדרות מנוהלות או הגדרות CLI. הגדרות פרויקט אינן יכולות להפעיל אותה.

#תאימות פלטפורמות וכלים

• תמיכה בפלטפורמות: תומך ב-macOS, Linux ו-WSL2. מערכות WSL1 ו-Windows טבעי אינן נתמכות.
• תקורה בביצועים: מזערית, אך פעולות מסוימות במערכת הקבצים עשויות להיות מעט איטיות יותר.
• תאימות כלים: כלים מסוימים הדורשים דפוסי גישה ספציפיים למערכת עשויים לדרוש התאמות תצורה, או שיהיה צורך להריץ אותם מחוץ לארגז החול.

#היקף

ארגז החול מבודד תהליכי משנה של Bash. כלים אחרים פועלים תחת גבולות שונים:

• כלי קבצים מובנים: הכלים Read, Edit, ו-Write משתמשים במערכת ההרשאות ישירות במקום לרוץ דרך ארגז החול. ראו הרשאות.
• שימוש במחשב (Computer use): כאשר Claude פותח יישומים ושולט במסך שלכם, הוא פועל בשולחן העבודה האמיתי שלכם ולא בסביבה מבודדת. בקשות אישור לכל יישום מגבילות כל יישום. ראו שימוש במחשב ב-CLI או שימוש במחשב ב-Desktop.
• משתני סביבה: פקודות Bash בארגז חול יורשות את סביבת תהליך האב כברירת מחדל, כולל כל פרטי גישה המוגדרים שם. השתמשו ב-sandbox.credentials כדי להסיר או למסך משתנים ספציפיים עבור פקודות בארגז חול, או הגדירו את CLAUDE_CODE_SUBPROCESS_ENV_SCRUB כדי להסיר פרטי גישה מכל תהליכי המשנה.
• תת-סוכנים (Subagents): תת-סוכנים רצים באותו תהליך של הפעלת האב ומשתמשים באותה תצורת ארגז חול. פקודות Bash בתוך תת-סוכן מבודדות בארגז חול כאשר ארגז החול מופעל בהפעלת האב.

אזהרה: שימוש יעיל בארגז חול דורש הן בידוד של מערכת הקבצים והן בידוד של הרשת. ללא בידוד רשת, סוכן שנפגע עלול להדליף קבצים רגישים כגון מפתחות SSH. ללא בידוד מערכת הקבצים, בין אם ממדיניות מתירנית ובין אם מהשבתת שכבת מערכת הקבצים, סוכן שנפגע עלול לשתול דלת אחורית במשאבי מערכת כדי להשיג גישת רשת. כאשר אתם מרחיבים את ברירות המחדל, בדקו שנתיב allowWrite, רשומת allowedDomains רחבה, או החרגת excludedCommands אינם מבטלים הגבלה בצד השני.

#ראו גם

• סביבות ארגז חול: השוואת ארגז החול המובנה מול dev containers, קונטיינרים ומכונות וירטואליות
• אבטחה: תכונות אבטחה מקיפות ושיטות עבודה מומלצות
• הרשאות: הגדרת הרשאות ובקרת גישה
• מדריך הגדרות: כל מפתחות ההגדרות
• מדריך CLI: אפשרויות שורת הפקודה