پیکربندیِ ابزارِ سندباکس‌شده‌ی Bash

Learn how Claude Code’s sandboxed Bash tool provides filesystem and network isolation for safer, more autonomous agent execution.

سندباکسِ Bash به Claude اجازه می‌دهد بیشترِ دستورهای شل را بدون توقف برای کسبِ مجوز اجرا کند. به‌جای تأییدِ تک‌تکِ دستورها، تو تعیین می‌کنی که دستورها به کدام فایل‌ها و دامنه‌های شبکه دسترسی داشته باشند، و سیستم‌عامل این مرز را برای هر دستورِ Bash و فرایندهای فرزندِ آن اعمال می‌کند.

این صفحه پوشش می‌دهد که چطور:

سندباکس را فعال کنی و انتخاب کنی دستورهای سندباکس‌شده چگونه تأیید شوند
پیکربندی کنی که دستورها به کدام مسیرها و دامنه‌های شبکه برسند
سندباکس را با قواعدِ دسترسی و حالت‌های دسترسی ترکیب کنی
سندباکس را در کلِ یک سازمان اعمال کنی با تنظیماتِ مدیریت‌شده

Get started

سندباکس درونِ Claude Code تعبیه شده و روی macOS، Linux و WSL2 اجرا می‌شود. ویندوزِ بومی پشتیبانی نمی‌شود. روی ویندوز، Claude Code را درونِ یک توزیعِ WSL2 اجرا کن.

روی macOS چیزی برای نصب نیست: سندباکس از چارچوبِ توکارِ Seatbelt استفاده می‌کند. روی Linux و WSL2، سندباکس به دو بسته متکی است که در Set up Linux and WSL2 پوشش داده شده. حتی اگر هنوز آن‌ها را نصب نکرده‌ای، می‌توانی با /sandbox شروع کنی، چون پنلِ آن نشان می‌دهد چیزی کم است یا نه.

اجرای /sandbox

یک نشستِ Claude Code را شروع کن و دستورِ /sandbox را اجرا کن:

/sandbox

این کار پنلِ سندباکس را با سه تب باز می‌کند:

Mode: انتخاب کن دستورهای سندباکس‌شده چگونه تأیید شوند، که در گامِ بعدی پوشش داده شده
Overrides: انتخاب کن آیا دستورهایی که زیرِ سندباکس شکست می‌خورند می‌توانند به اجرای بدونِ سندباکس بازگردند یا نه. این همان تنظیمِ allowUnsandboxedCommands است
Config: تنظیماتِ نهاییِ سندباکس را ببین

اگر پنل فقط یک تبِ Dependencies نشان می‌دهد، یک بسته‌ی لازم کم است. آن را همان‌طور که در Set up Linux and WSL2 توضیح داده شده نصب کن، Claude Code را دوباره راه‌اندازی کن، و دوباره /sandbox را اجرا کن.

انتخاب یک حالت

در تبِ Mode، یکی از auto-allow یا regular permissions را انتخاب کن. حالتِ auto-allow دستورهای سندباکس‌شده را بدونِ پرسش اجرا می‌کند، و regular permissions حتی وقتی دستورها سندباکس‌شده‌اند، همان درخواست‌های مجوزِ معمول را نگه می‌دارد. برای اینکه ببینی کدام دستورها در حالتِ auto-allow همچنان درخواستِ مجوز می‌دهند، Sandbox modes را ببین.

اجرای یک دستورِ Bash

از Claude بخواه دستوری اجرا کند، مثلِ یک build یا یک مجموعه‌آزمون. به‌طورِ پیش‌فرض، دستورهای درونِ سندباکس فقط می‌توانند در دایرکتوریِ کاری و دایرکتوریِ موقتِ نشست بنویسند. اولین باری که یک دستور به یک دامنه‌ی شبکه‌ی جدید نیاز دارد، Claude Code برای تأیید درخواست می‌دهد.

دستورهایی که نمی‌توانند سندباکس‌شده اجرا شوند، به جریانِ مجوزِ معمول بازمی‌گردند. برای گشاد یا تنگ‌کردنِ این مرزها، Configure sandboxing را ببین.

انتخابِ یک حالت در پنل، در تنظیماتِ محلیِ پروژه‌ات در .claude/settings.local.json نوشته می‌شود، که فقط روی پروژه‌ی فعلی اعمال می‌شود و در git ثبت نمی‌شود. برای فعال‌کردنِ سندباکس در همه‌ی پروژه‌هایت، sandbox.enabled را در تنظیماتِ کاربریِ خود در ~/.claude/settings.json روی true بگذار. برای اعمالِ سندباکس روی هر توسعه‌دهنده‌ای در یک سازمان، از managed settings استفاده کن.

Set up Linux and WSL2

روی Linux و WSL2، سندباکس به دو بسته متکی است:

bubblewrap: ابزارِ سندباکسِ غیرِامتیازی که ایزوله‌سازیِ فایل‌سیستم را اعمال می‌کند
socat: رله‌ای که برای هدایتِ ترافیکِ شبکه از طریقِ پروکسیِ سندباکس استفاده می‌شود

آن‌ها را با مدیرِ بسته‌ی توزیعِ خود نصب کن:

Ubuntu/Debian
Fedora

sudo apt-get install bubblewrap socat

sudo dnf install bubblewrap socat

پس از نصب، تبِ Dependencies در /sandbox نشان می‌دهد که آیا ripgrep، bubblewrap، socat و فیلترِ seccomp روی پلتفرمت در دسترس‌اند. ripgrep همراهِ باینریِ بومیِ Claude Code عرضه می‌شود. فیلترِ seccomp اختیاری است و مسدودسازیِ سوکتِ دامنه‌ی Unix را اضافه می‌کند. اگر کم بود، آن را با npm install -g @anthropic-ai/sandbox-runtime نصب کن.

وقتی یک وابستگیِ لازم کم باشد، تبِ Dependencies تنها تبِ نمایش‌داده‌شده است تا آن را نصب کنی. بررسیِ وابستگی هنگامِ راه‌اندازی اجرا می‌شود، پس بعد از نصبِ بسته‌ها Claude Code را دوباره راه‌اندازی کن تا /sandbox آن‌ها را تشخیص دهد.

اوبونتو ۲۴.۰۴ و بالاتر: اجازه بده bubblewrap فضای‌نامِ کاربری بسازد

روی اوبونتو ۲۴.۰۴ و بالاتر، سیاستِ پیش‌فرضِ AppArmor جلوی bubblewrap را می‌گیرد که فضاهای‌نامِ کاربریِ موردِنیازش برای ایزوله‌سازی را بسازد.

برای بررسیِ اینکه آیا محیطت این محدودیت را اعمال می‌کند — از جمله درونِ WSL2 — دستورِ sysctl kernel.apparmor_restrict_unprivileged_userns را اجرا کن. اگر کلید وجود نداشت یا 0 برگرداند، این گام را رد کن. اگر 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، دستورهای سندباکس‌شده نمی‌توانند باینری‌های ویندوز مثلِ cmd.exe، powershell.exe یا هر چیزِ زیرِ /mnt/c/ را اجرا کنند. WSL این‌ها را از طریقِ یک سوکتِ Unix به میزبانِ ویندوز تحویل می‌دهد، که سندباکس آن را مسدود می‌کند. اگر یک دستور نیاز دارد یک باینریِ ویندوز را فراخوانی کند، آن را به excludedCommands اضافه کن تا بیرونِ سندباکس اجرا شود.

Sandbox modes

Claude Code دو حالتِ سندباکس ارائه می‌دهد:

حالت Auto-allow: دستورهای Bash تلاش می‌کنند درونِ سندباکس اجرا شوند و به‌طورِ خودکار، بدونِ نیاز به مجوز، اجازه داده می‌شوند. دستورهایی که نمی‌توانند سندباکس شوند — مثلِ آن‌هایی که به دسترسیِ شبکه به میزبان‌های غیرمجاز نیاز دارند — به جریانِ مجوزِ معمول بازمی‌گردند، جایی که Claude Code قواعدِ دسترسی‌ات را بررسی می‌کند و برای هر دستوری که آن قواعد از پیش اجازه نداده‌اند، از تو درخواستِ مجوز می‌کند.

حتی در حالتِ auto-allow، موارد زیر همچنان برقرارند:

قواعدِ صریحِ deny همیشه رعایت می‌شوند
دستورهای rm یا rmdir که /، دایرکتوریِ خانگی‌ات، یا دیگر مسیرهای حیاتیِ سیستم را هدف می‌گیرند، همچنان درخواستِ مجوز را فعال می‌کنند
قواعدِ ask محتوامحور مثلِ Bash(git push *) همچنان حتی برای دستورهای سندباکس‌شده درخواستِ مجوز را الزامی می‌کنند
یک قاعده‌ی askِ خالیِ Bash، یا شکلِ معادلِ آن Bash(*)، برای دستورهایی که سندباکس‌شده اجرا می‌شوند نادیده گرفته می‌شود؛ این قاعده همچنان روی دستورهایی که به جریانِ مجوزِ معمول بازمی‌گردند اعمال می‌شود

حالت Regular permissions: همه‌ی دستورهای Bash از جریانِ مجوزِ معمول عبور می‌کنند، حتی وقتی سندباکس‌شده‌اند. این کنترلِ بیشتری می‌دهد اما تأییدهای بیشتری می‌طلبد.

در هر دو حالت، سندباکس همان محدودیت‌های فایل‌سیستم و شبکه را اعمال می‌کند. تفاوت فقط در این است که آیا دستورهای سندباکس‌شده به‌طورِ خودکار تأیید می‌شوند یا مجوزِ صریح می‌طلبند.

دایرکتوریِ موقتِ نشست، در کنارِ دایرکتوریِ کاری، به‌طورِ پیش‌فرض درونِ سندباکس قابلِ‌نوشتن است. Claude Code برای دستورهای سندباکس‌شده $TMPDIR را به این دایرکتوری تنظیم می‌کند، پس ابزارهایی که فایل‌های موقت می‌نویسند بدونِ پیکربندیِ اضافه کار می‌کنند. دستورهای بدونِ سندباکس $TMPDIRِ شلِ تو را دست‌نخورده به ارث می‌برند، یعنی دستورهای سندباکس‌شده و بدونِ سندباکس، $TMPDIR را به دایرکتوری‌های متفاوتی تحلیل می‌کنند. برای ردوبدلِ فایل‌های موقت بینِ این دو، به‌جای آن آن‌ها را زیرِ دایرکتوریِ کاری بنویس.

بعضی دستورها اصلاً نمی‌توانند درونِ سندباکس اجرا شوند، مثلِ ابزارهایی که با آن ناسازگارند یا به میزبانی نیاز دارند که اجازه‌اش را نداده‌ای. به‌جای شکست‌دادنِ کار یا واداشتنِ تو به خاموش‌کردنِ سندباکس، Claude Code یک راهِ گریز دارد: وقتی دستوری به‌خاطرِ محدودیت‌های سندباکس شکست می‌خورد، Claude شکست را تحلیل می‌کند و ممکن است دستور را با پارامترِ dangerouslyDisableSandbox دوباره اجرا کند. دستورِ دوباره‌اجراشده بیرونِ سندباکس اجرا می‌شود، پس از جریانِ مجوزِ معمول عبور می‌کند و تأییدِ تو را می‌طلبد.

می‌توانی این راهِ گریز را با تنظیمِ "allowUnsandboxedCommands": false در تنظیماتِ سندباکس خود غیرفعال کنی. وقتی غیرفعال است — که تبِ Overridesِ /sandbox آن را به‌صورتِ Strict sandbox mode نشان می‌دهد — پارامترِ dangerouslyDisableSandbox کاملاً نادیده گرفته می‌شود و همه‌ی دستورها باید سندباکس‌شده اجرا شوند یا صراحتاً در excludedCommands فهرست شوند.

Configure sandboxing

رفتارِ سندباکس را از طریقِ فایلِ settings.json خود سفارشی کن. برای مرجعِ کاملِ پیکربندی، Settings را ببین.

به‌طورِ پیش‌فرض، دستورهای سندباکس‌شده فقط می‌توانند در دایرکتوریِ کاریِ فعلی و دایرکتوریِ موقتِ نشست بنویسند. اگر دستورهای زیرفرایندی مثلِ kubectl، terraform یا npm نیاز دارند بیرونِ این دایرکتوری‌ها بنویسند، از sandbox.filesystem.allowWrite برای اعطای دسترسی به مسیرهای مشخص استفاده کن:

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

این مسیرها در سطحِ سیستم‌عامل اعمال می‌شوند، پس همه‌ی دستورهایی که درونِ سندباکس اجرا می‌شوند — از جمله فرایندهای فرزندشان — آن‌ها را رعایت می‌کنند. این رویکردِ توصیه‌شده است وقتی یک ابزار به دسترسیِ نوشتن در یک مکانِ مشخص نیاز دارد، به‌جای آنکه ابزار را کاملاً با excludedCommands از سندباکس بیرون بگذاری.

وقتی همان آرایه‌ی فایل‌سیستم در چند دامنه‌ی تنظیمات تعریف شده باشد، آرایه‌ها ادغام می‌شوند: مسیرها از هر دامنه با هم ترکیب می‌شوند، نه آنکه جایگزین شوند.

پیشوندهای مسیر کنترل می‌کنند که مسیرها چگونه تحلیل شوند:

پیشوند	معنی	مثال
`/`	مسیرِ مطلق از ریشه‌ی فایل‌سیستم	`/tmp/build` همان `/tmp/build` می‌ماند
`~/`	نسبت به دایرکتوریِ خانگی	`~/.kube` به `$HOME/.kube` تبدیل می‌شود
`./` یا بدونِ پیشوند	نسبت به ریشه‌ی پروژه برای تنظیماتِ پروژه، یا به `~/.claude` برای تنظیماتِ کاربری	`./output` در `.claude/settings.json` به `<project-root>/output` تحلیل می‌شود

این نحو با قواعدِ دسترسیِ Read و Edit فرق دارد، که //path را برای مطلق و /path را برای نسبت‌به‌پروژه به کار می‌برند. مسیرهای فایل‌سیستمِ سندباکس از قراردادهای استاندارد استفاده می‌کنند: /tmp/build مطلق است.

همچنین می‌توانی با sandbox.filesystem.denyWrite و sandbox.filesystem.denyRead دسترسیِ نوشتن یا خواندن را رد کنی، و با sandbox.filesystem.allowRead مسیرهای مشخصی را درونِ یک ناحیه‌ی رد‌شده دوباره مجاز کنی.

مثالِ زیر خواندن از کلِ دایرکتوریِ خانگی را مسدود می‌کند ولی همچنان خواندن از پروژه‌ی فعلی را مجاز می‌گذارد. آن را در .claude/settings.jsonِ پروژه‌ات بگذار، چون مسیرِ نسبیِ . تنها وقتی به ریشه‌ی پروژه تحلیل می‌شود که پیکربندی در تنظیماتِ پروژه باشد:

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

. در allowRead به ریشه‌ی پروژه تحلیل می‌شود چون این پیکربندی در تنظیماتِ پروژه قرار دارد. اگر همین پیکربندی را در ~/.claude/settings.json می‌گذاشتی، . به‌جای آن به ~/.claude تحلیل می‌شد، و فایل‌های پروژه به‌خاطرِ قاعده‌ی denyRead مسدود می‌ماندند.

How sandboxing works

Filesystem isolation

ابزارِ Bashِ سندباکس‌شده دسترسیِ فایل‌سیستم را به دایرکتوری‌های مشخص محدود می‌کند:

رفتارِ نوشتنِ پیش‌فرض: دسترسیِ خواندن و نوشتن به دایرکتوریِ کاریِ فعلی و زیردایرکتوری‌هایش، به‌علاوه‌ی دایرکتوریِ موقتِ نشست که $TMPDIR به آن اشاره می‌کند
رفتارِ خواندنِ پیش‌فرض: دسترسیِ خواندن به کلِ کامپیوتر، به‌جز برخی دایرکتوری‌های رد‌شده. توجه کن که این پیش‌فرض همچنان خواندنِ فایل‌های اعتبارنامه مثلِ ~/.aws/credentials و ~/.ssh/ را مجاز می‌گذارد. برای مسدودکردنشان آن‌ها را به denyRead اضافه کن.
دسترسیِ مسدودشده: بدونِ مجوزِ صریح نمی‌تواند فایل‌های بیرونِ دایرکتوریِ کاریِ فعلی و دایرکتوریِ موقتِ نشست را تغییر دهد، از جمله فایل‌های پیکربندیِ شل مثلِ ~/.bashrc و باینری‌های سیستمی در /bin/
Git worktrees: وقتی دایرکتوریِ کاری یک git worktreeِ پیوندی است، سندباکس همچنین نوشتن در دایرکتوریِ مشترکِ .gitِ مخزنِ اصلی را مجاز می‌گذارد تا دستورهایی مثلِ git commit بتوانند refها و indexها را به‌روز کنند. نوشتن در hooks/ و config درونِ آن دایرکتوری همچنان رد‌شده می‌ماند.
قابلِ‌پیکربندی: مسیرهای مجاز و رد‌شده‌ی سفارشی را از طریقِ تنظیمات تعریف کن

می‌توانی با sandbox.filesystem.allowWrite در تنظیماتت به مسیرهای بیشتری دسترسیِ نوشتن بدهی. این محدودیت‌ها در سطحِ سیستم‌عامل اعمال می‌شوند، پس روی همه‌ی دستورهای زیرفرایندی — از جمله ابزارهایی مثلِ kubectl، terraform و npm — اعمال می‌شوند، نه فقط ابزارهای فایلِ Claude.

Network isolation

دسترسیِ شبکه از طریقِ یک سرورِ پروکسی که بیرونِ سندباکس اجرا می‌شود کنترل می‌شود:

محدودیت‌های دامنه: هیچ دامنه‌ای از پیش مجاز نیست. اولین باری که یک دستور به دامنه‌ای جدید نیاز دارد، Claude Code برای تأیید درخواست می‌دهد. برای پرهیز از درخواست، دامنه‌ها را با allowedDomains از پیش مجاز کن.
قفلِ مدیریت‌شده: اگر allowManagedDomainsOnly در تنظیماتِ مدیریت‌شده تنظیم شده باشد، دامنه‌های غیرمجاز به‌جای درخواست به‌طورِ خودکار مسدود می‌شوند، و فقط allowedDomainsهای تنظیماتِ مدیریت‌شده رعایت می‌شوند.
پشتیبانی از پروکسیِ سفارشی: کاربرانِ پیشرفته می‌توانند قواعدِ سفارشی روی ترافیکِ خروجی پیاده کنند
پوششِ جامع: محدودیت‌ها روی همه‌ی اسکریپت‌ها، برنامه‌ها و زیرفرایندهایی که دستورها ایجاد می‌کنند اعمال می‌شوند

OS-level enforcement

ابزارِ Bashِ سندباکس‌شده از اولیه‌های امنیتیِ سیستم‌عامل بهره می‌گیرد:

macOS: از Seatbelt برای اعمالِ سندباکس استفاده می‌کند
Linux: از bubblewrap برای ایزوله‌سازی استفاده می‌کند
WSL2: از bubblewrap استفاده می‌کند، مثلِ Linux

WSL1 پشتیبانی نمی‌شود چون bubblewrap به قابلیت‌های هسته‌ای نیاز دارد که فقط در WSL2 در دسترس‌اند. این محدودیت‌های سطحِ سیستم‌عامل تضمین می‌کنند که همه‌ی فرایندهای فرزندی که دستورهای Claude Code ایجاد می‌کنند، همان مرزهای امنیتی را به ارث ببرند.

همین اولیه‌ها به‌صورتِ بسته‌ی مستقلِ @anthropic-ai/sandbox-runtime هم در دسترس‌اند، که صفحه‌ی Sandbox environments آن را به‌عنوان رویکردی جدا برای پوشاندنِ کلِ فرایندِ Claude Code پوشش می‌دهد.

How sandboxing relates to permissions and permission modes

سندباکس، قواعدِ دسترسی و permission modes لایه‌های مکمل‌اند. بخش‌های زیر پوشش می‌دهند که سندباکس با هرکدام چگونه تعامل می‌کند.

Permission rules

قواعدِ دسترسی و سندباکس چیزهای متفاوتی را کنترل می‌کنند:

قواعدِ دسترسی کنترل می‌کنند که Claude Code کدام ابزارها را می‌تواند به کار ببرد و پیش از اجرای هر ابزار ارزیابی می‌شوند. روی همه‌ی ابزارها اعمال می‌شوند: Bash، Read، Edit، WebFetch، MCP و دیگران.
سندباکس اعمالِ سطحِ سیستم‌عاملی فراهم می‌کند که محدود می‌کند دستورهای Bash در سطحِ فایل‌سیستم و شبکه به چه چیزی دسترسی داشته باشند. فقط روی دستورهای Bash و فرایندهای فرزندشان اعمال می‌شود.

این دو لایه در نحوه‌ی اعمال‌شدن هم فرق دارند. Claude Code تصمیم‌های مجوز را پیش از اجرای دستور می‌گیرد، بر اساسِ رشته‌ی دستور و — در حالتِ auto — قضاوتِ یک دسته‌بندِ جداگانه درباره‌ی اینکه آیا دستور امن است یا نه. سیستم‌عامل مرزِ سندباکس را روی فرایندِ در‌حالِ‌اجرا اعمال می‌کند، پس این مرز فارغ از آنکه مدل چه چیزی را برای اجرا انتخاب کرده برقرار می‌ماند، حتی اگر یک دستورِ مجاز کاری بیش از آنچه نامش نشان می‌دهد انجام دهد.

محدودیت‌های فایل‌سیستم و شبکه هم از طریقِ تنظیماتِ سندباکس و هم قواعدِ دسترسی پیکربندی می‌شوند:

تنظیم یا قاعده	چه کاری می‌کند
`sandbox.filesystem.allowWrite`	به زیرفرایندها دسترسیِ نوشتن به مسیرهای بیرونِ دایرکتوریِ کاری می‌دهد
`sandbox.filesystem.denyWrite` و `sandbox.filesystem.denyRead`	دسترسیِ زیرفرایند به مسیرهای مشخص را مسدود می‌کند
`sandbox.filesystem.allowRead`	خواندنِ مسیرهای مشخص را درونِ یک ناحیه‌ی `denyRead` دوباره مجاز می‌کند
قواعدِ allowِ `Edit`	به مسیرهای مشخص دسترسیِ نوشتن می‌دهد، به همان شکلی که `sandbox.filesystem.allowWrite` می‌دهد
قواعدِ denyِ `Read` و `Edit`	دسترسی به فایل‌ها یا دایرکتوری‌های مشخص را مسدود می‌کند
قواعدِ allow و denyِ `WebFetch`	دسترسیِ دامنه را کنترل می‌کند
`allowedDomains`ِ سندباکس	کنترل می‌کند که دستورهای Bash به کدام دامنه‌ها برسند
`deniedDomains`ِ سندباکس	دامنه‌های مشخص را مسدود می‌کند، حتی وقتی یک `allowedDomains`ِ گسترده با wildcard وگرنه آن‌ها را مجاز می‌کرد

مسیرها هم از تنظیماتِ sandbox.filesystem و هم قواعدِ دسترسی با هم در پیکربندیِ نهاییِ سندباکس ادغام می‌شوند.

دایرکتوریِ examplesِ مخزنِ claude-code شاملِ پیکربندی‌های آغازینِ تنظیمات برای سناریوهای رایجِ استقرار است، از جمله مثال‌های مخصوصِ سندباکس. این‌ها را به‌عنوان نقطه‌ی شروع به کار ببر و آن‌ها را برای متناسب‌شدن با نیازهایت تنظیم کن.

Permission modes

/sandbox یک permission mode نیست. permission modeها تصمیم می‌گیرند که آیا یک فراخوانیِ ابزار اجرا شود و آیا اول از تو پرسیده شود، در حالی که سندباکس محدود می‌کند که یک دستورِ Bash پس از اجرا به چه چیزی دسترسی داشته باشد. این دو در آنچه کنترل می‌کنند و آنچه جایگزینِ درخواستِ هر‌اقدام می‌شود فرق دارند:

	چه چیزی را کنترل می‌کند	چه چیزی جایگزینِ درخواست می‌شود
`/sandbox`	اینکه یک دستورِ Bash پس از اجرا به چه چیزی دسترسی دارد	خودِ مرزِ سندباکس، در حالتِ auto-allow
Auto mode	اینکه آیا هر فراخوانیِ ابزار اجرا می‌شود	یک دسته‌بند که اقدام‌ها را بازبینی می‌کند
`--dangerously-skip-permissions`	اینکه آیا هر فراخوانیِ ابزار اجرا می‌شود	هیچ‌چیز. بررسی‌های Protected path هم رد می‌شوند؛ فقط قواعدِ صریحِ ask و حذفِ `/` یا دایرکتوریِ خانگی‌ات همچنان درخواستِ مجوز می‌دهند

حالتِ auto-allowِ سندباکس از auto mode جداست: auto-allow دستورهای Bash را تأیید می‌کند چون مرزِ سندباکس آن‌ها را در‌بر‌می‌گیرد، در حالی که auto mode از یک دسته‌بند برای بازبینیِ اقدام‌ها استفاده می‌کند. این دو مستقل کار می‌کنند و می‌توان آن‌ها را ترکیب کرد. برای انتخابِ یک مرزِ ایزوله‌سازی برای اجراهای بدونِ نظارت، Sandbox environments را ببین.

Configure the sandbox for your organization

مدیران می‌توانند سندباکس را برای هر کاربر الزامی کنند، نگذارند توسعه‌دهندگان سیاست را گشاد کنند، و ترافیکِ سندباکس را از طریقِ یک پروکسیِ شرکتی هدایت کنند.

Enforce sandboxing with managed settings

برای الزامی‌کردنِ سندباکس برای هر توسعه‌دهنده، کلیدهای sandbox را از طریقِ managed settings برسان، یا به‌صورتِ فایلی که MDMِ تو مدیریت می‌کند یا از طریقِ server-managed settings روی Claude.ai.

پیکربندیِ تنظیماتِ مدیریت‌شده‌ی زیر سندباکس را فعال می‌کند، اگر سندباکس نتواند مقداردهی شود از راه‌اندازیِ Claude Code سر باز می‌زند، و جلوی مدل را می‌گیرد که دستورها را بیرونِ سندباکس دوباره اجرا کند:

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

دو کلیدِ فراتر از enabled کنترل می‌کنند که وقتی سندباکس نمی‌تواند دستوری را اجرا کند چه اتفاقی می‌افتد:

failIfUnavailable: یک وابستگیِ گم‌شده مثلِ bubblewrap روی Linux جلوی راه‌اندازیِ Claude Code را می‌گیرد، به‌جای آنکه هشدار نشان دهد و به اجرای بدونِ سندباکس بازگردد
allowUnsandboxedCommands: false: راهِ گریزِ dangerouslyDisableSandbox نادیده گرفته می‌شود، پس دستورهایی که زیرِ سندباکس شکست می‌خورند نمی‌توانند بیرونِ آن دوباره اجرا شوند

دو افزوده در کنارِ این‌ها ارزشِ توجه دارند. برای هر ابزارِ تأییدشده‌ی سازمان که باید بدونِ ایزوله‌سازی اجرا شود، excludedCommands را اضافه کن. برای دایرکتوری‌های اعتبارنامه مثلِ ~/.aws و ~/.ssh که سیاستِ خواندنِ پیش‌فرض همچنان مجازشان می‌گذارد، ورودی‌های denyRead را اضافه کن.

سندباکس روی ویندوزِ بومی اجرا نمی‌شود، پس اگر ناوگانِ تو میزبان‌های ویندوزی دارد، این پیکربندی را به macOS و Linux محدود کن یا از آن کاربران بخواه Claude Code را درونِ WSL2 یا یک کانتینر اجرا کنند.

Keep developers from widening the policy

برای کلیدهای بولی مثلِ enabled و failIfUnavailable، Claude Code از مقدارِ مدیریت‌شده استفاده می‌کند و هر چیزی را که توسعه‌دهنده به‌صورتِ محلی تنظیم کند نادیده می‌گیرد. برای کلیدهای آرایه‌ای مثلِ excludedCommands و allowRead، Claude Code ورودی‌ها را از هر دامنه ادغام می‌کند، پس یک توسعه‌دهنده می‌تواند ورودی‌هایی اضافه کند که سیاست را گشاد می‌کنند.

allowManagedReadPathsOnly را در تنظیماتِ مدیریت‌شده روی true بگذار تا فقط ورودی‌های allowReadِ تنظیماتِ مدیریت‌شده رعایت شوند. ورودی‌های allowReadِ کاربری، پروژه و محلی نادیده گرفته می‌شوند. این مانعِ آن می‌شود که توسعه‌دهندگان دسترسیِ خواندن را فراتر از مسیرهای تأییدشده‌ی سازمان گشاد کنند. برای قفل‌کردنِ دامنه‌های شبکه به مقادیرِ مدیریت‌شده به همین شکل، allowManagedDomainsOnly را تنظیم کن.

excludedCommands معادلِ قفلِ مدیریت‌شده‌محورِ خود را ندارد، پس یک توسعه‌دهنده همیشه می‌تواند ورودی‌هایی اضافه کند که دستورهای بیشتری را بیرونِ سندباکس اجرا کنند. فهرستِ مدیریت‌شده را محدود نگه دار.

Custom proxy configuration

برای سازمان‌هایی که امنیتِ شبکه‌ی پیشرفته می‌طلبند، می‌توانی یک پروکسیِ سفارشی پیاده کنی تا:

ترافیکِ HTTPS را رمزگشایی و بازرسی کنی
قواعدِ فیلترِ سفارشی اعمال کنی
همه‌ی درخواست‌های شبکه را ثبت کنی
با زیرساختِ امنیتیِ موجود یکپارچه شوی

برای اشاره‌دادنِ Claude Code به پروکسیِ خود، پورت‌های پروکسی را در تنظیماتِ سندباکس تنظیم کن:

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

Troubleshooting

بعضی دستورها درونِ سندباکس شکست می‌خورند حتی اگر بیرونِ آن کار کنند. راه‌حل‌های زیر رایج‌ترین موارد را پوشش می‌دهند.

دستورها با خطای host-not-allowed شکست می‌خورند: بسیاری از ابزارهای CLI نیاز دارند به میزبان‌های مشخصی برسند. اعطای مجوز هنگامِ درخواست، میزبان را به فهرستِ مجازت اضافه می‌کند تا ابزار در آینده درونِ سندباکس اجرا شود.
jest هنگ می‌کند یا شکست می‌خورد: watchman با سندباکس ناسازگار است. به‌جای آن jest --no-watchman را اجرا کن.
CLIهای مبتنی‌بر‌Go روی macOS در راستی‌آزماییِ TLS شکست می‌خورند: ابزارهایی مثلِ gh، gcloud و terraform ممکن است زیرِ Seatbelt در راستی‌آزماییِ TLS شکست بخورند. این ابزارها را در excludedCommands فهرست کن تا بیرونِ سندباکس اجرا شوند. اگر از httpProxyPort با یک پروکسیِ MITM و CAِ سفارشی استفاده می‌کنی، به‌جای آن enableWeakerNetworkIsolation را روی true بگذار.
دستورهای docker شکست می‌خورند: docker با سندباکس ناسازگار است. docker * را به excludedCommands اضافه کن تا بیرونِ سندباکس اجرا شود.
bubblewrap درونِ یک کانتینر شروع نمی‌شود: در یک کانتینرِ غیرِامتیازی، bubblewrap نمی‌تواند یک فایل‌سیستمِ /procِ تازه mount کند. enableWeakerNestedSandbox را روی true بگذار تا سندباکسِ درونی به‌جای آن /procِ موجودِ کانتینر را bind-mount کند. این تنظیم را فقط وقتی به کار ببر که کانتینرِ بیرونی از قبل مرزِ ایزوله‌سازیِ موردِ‌نیازت را فراهم می‌کند، چون اطلاعاتِ فرایند را به دستورهای سندباکس‌شده‌ای افشا می‌کند که یک mountِ تازه‌ی /proc آن را پنهان می‌کرد.
فیلترِ seccomp روی Linux: فیلترِ seccomp برای مسدودکردنِ سوکت‌های دامنه‌ی Unix لازم است. تبِ Dependencies در /sandbox نشان می‌دهد که آیا در دسترس است. اگر کم بود، npm install -g @anthropic-ai/sandbox-runtime را اجرا کن تا کمکی نصب شود.
--dangerously-skip-permissions به‌عنوانِ root شکست می‌خورد: این پرچم وقتی به‌عنوانِ root یا از طریقِ sudo روی Linux و macOS اجرا شود مسدود است، چون دسترسیِ root در کنارِ نبودِ درخواستِ مجوز می‌تواند هر فایل یا سرویسی روی سیستم را تغییر دهد. این بررسی درونِ یک سندباکسِ شناخته‌شده به‌طورِ خودکار رد می‌شود. برای اجرای خودکار در یک کانتینر، از پیکربندیِ dev container استفاده کن، که Claude Code را به‌عنوانِ کاربرِ غیرِroot اجرا می‌کند.

Limitations

سندباکس ریسک را کاهش می‌دهد اما یک مرزِ ایزوله‌سازیِ کامل نیست. پیش از اتکا به آن به‌عنوانِ یک کنترلِ امنیتیِ سفت‌وسخت، محدودیت‌های زیر را بازبینی کن.

Security limitations

فیلترِ شبکه: سیستمِ فیلترِ شبکه با محدودکردنِ دامنه‌هایی که فرایندها مجازند به آن‌ها وصل شوند کار می‌کند. پروکسیِ توکار ترافیکِ خروجی را نه پایان می‌دهد و نه بازرسیِ TLS انجام می‌دهد، پس محتوای اتصال‌های رمزشده بررسی نمی‌شود. مسئولیتِ اطمینان از اینکه فقط دامنه‌های مورد‌اعتماد در سیاستت مجازند با توست.

مجاز‌کردنِ دامنه‌های گسترده مثلِ github.com می‌تواند مسیرهایی برای استخراجِ غیرمجازِ داده ایجاد کند. چون پروکسی تصمیمِ مجاز‌بودن را از نامِ میزبانِ ارائه‌شده توسطِ کلاینت و بدونِ بازرسیِ TLS می‌گیرد، کدی که درونِ سندباکس اجرا می‌شود می‌تواند بالقوه از domain fronting یا تکنیک‌های مشابه برای رسیدن به میزبان‌های بیرونِ فهرستِ مجاز استفاده کند. اگر مدلِ تهدیدِ تو تضمین‌های قوی‌تری می‌طلبد، یک پروکسیِ سفارشی پیکربندی کن که TLS را پایان می‌دهد و ترافیک را بازرسی می‌کند، و گواهیِ CAِ آن را درونِ سندباکس نصب کن. ایزوله‌سازیِ شبکه‌ی قوی‌ترِ آگاه‌به‌TLS یک حوزه‌ی فعالِ توسعه است.

تشدیدِ امتیاز از طریقِ سوکت‌های Unix: پیکربندیِ allowUnixSockets می‌تواند ناخواسته به سرویس‌های سیستمیِ قدرتمندی دسترسی بدهد که می‌توانند به دور‌زدنِ سندباکس بینجامند. برای مثال، مجاز‌کردنِ دسترسی به /var/run/docker.sock عملاً از طریقِ سوکتِ Docker به سیستمِ میزبان دسترسی می‌دهد. هر سوکتِ Unix را که از طریقِ سندباکس مجاز می‌کنی با دقت بسنج.
تشدیدِ مجوزِ فایل‌سیستم: مجوزهای نوشتنِ بیش‌از‌حد گسترده‌ی فایل‌سیستم می‌توانند حملاتِ تشدیدِ امتیاز را ممکن کنند. مجاز‌کردنِ نوشتن در دایرکتوری‌های دربردارنده‌ی فایل‌های اجرایی در $PATH، دایرکتوری‌های پیکربندیِ سیستم، یا فایل‌های پیکربندیِ شلِ کاربر مثلِ .bashrc یا .zshrc می‌تواند هنگامی که کاربران یا فرایندهای سیستمیِ دیگر به این فایل‌ها دسترسی پیدا می‌کنند، به اجرای کد در زمینه‌های امنیتیِ متفاوت بینجامد.
استحکامِ سندباکسِ Linux: پیاده‌سازیِ Linux ایزوله‌سازیِ قویِ فایل‌سیستم و شبکه فراهم می‌کند اما شاملِ یک حالتِ enableWeakerNestedSandbox است که آن را قادر می‌سازد درونِ محیط‌های Docker بدونِ فضاهای‌نامِ امتیازی، یا روی میزبان‌های Linux که فضاهای‌نامِ کاربریِ غیرِامتیازی با sysctl غیرفعال شده‌اند، کار کند. این گزینه امنیت را به‌میزانِ قابل‌توجهی ضعیف می‌کند و باید فقط وقتی به کار رود که ایزوله‌سازیِ بیشتری به‌گونه‌ای دیگر اعمال شده باشد.
محافظت از فایل‌های تنظیمات: سندباکس به‌طورِ خودکار دسترسیِ نوشتن به فایل‌های settings.jsonِ Claude Code در هر دامنه و به دایرکتوریِ تنظیماتِ مدیریت‌شده را رد می‌کند، پس یک دستورِ سندباکس‌شده نمی‌تواند سیاستِ خودش را تغییر دهد.

Platform and tool compatibility

پشتیبانیِ پلتفرم: از macOS، Linux و WSL2 پشتیبانی می‌کند. WSL1 و ویندوزِ بومی پشتیبانی نمی‌شوند.
سربارِ کارایی: حداقلی، اما برخی عملیاتِ فایل‌سیستم ممکن است کمی کندتر باشند.
سازگاریِ ابزار: برخی ابزارها که الگوهای دسترسیِ سیستمیِ خاصی می‌طلبند ممکن است به تنظیمِ پیکربندی نیاز داشته باشند، یا لازم باشد بیرونِ سندباکس اجرا شوند.

Scope

سندباکس زیرفرایندهای Bash را ایزوله می‌کند. ابزارهای دیگر زیرِ مرزهای متفاوتی عمل می‌کنند:

ابزارهای فایلِ توکار: Read، Edit و Write به‌جای اجرا از طریقِ سندباکس، مستقیماً از سیستمِ دسترسی استفاده می‌کنند. permissions را ببین.
Computer use: وقتی Claude برنامه‌ها را باز می‌کند و صفحه‌ی تو را کنترل می‌کند، به‌جای یک محیطِ ایزوله، روی دسکتاپِ واقعیِ تو اجرا می‌شود. درخواست‌های مجوزِ هر‌برنامه دروازه‌ی هر اپلیکیشن است. computer use in the CLI یا computer use in Desktop را ببین.
متغیرهای محیطی: دستورهای Bashِ سندباکس‌شده به‌طورِ پیش‌فرض محیطِ فرایندِ والد را به ارث می‌برند، از جمله هر اعتبارنامه‌ای که در آن تنظیم شده. برای حذفِ اعتبارنامه‌های Anthropic و ارائه‌دهندگانِ ابری از زیرفرایندها، CLAUDE_CODE_SUBPROCESS_ENV_SCRUB را تنظیم کن.
Subagents: ساب‌ایجنت‌ها در همان فرایندِ نشستِ والد اجرا می‌شوند و از همان پیکربندیِ سندباکس استفاده می‌کنند. دستورهای Bash درونِ یک ساب‌ایجنت وقتی سندباکس در نشستِ والد فعال باشد سندباکس‌شده‌اند.

سندباکسِ مؤثر هم به ایزوله‌سازیِ فایل‌سیستم و هم شبکه نیاز دارد. بدونِ ایزوله‌سازیِ شبکه، یک ایجنتِ به‌خطرافتاده می‌تواند فایل‌های حساس مثلِ کلیدهای SSH را استخراج کند. بدونِ ایزوله‌سازیِ فایل‌سیستم، یک ایجنتِ به‌خطرافتاده می‌تواند به منابعِ سیستمی backdoor بزند تا دسترسیِ شبکه به دست آورد. وقتی پیش‌فرض‌ها را گشاد می‌کنی، بررسی کن که یک مسیرِ allowWrite، یک ورودیِ گسترده‌ی allowedDomains، یا یک استثنای excludedCommands محدودیتی را در سمتِ دیگر خنثی نکند.