رفتن به محتوا
Claude Code Docs غیر رسمی

کانتینرهای توسعه

یک development container یا همان dev container، به تو اجازه می‌دهد محیطی یکسان و ایزوله تعریف کنی که هر مهندسِ تیمت بتواند اجرایش کند. وقتی Claude Code داخل آن کانتینر نصب باشد، دستورهایی که Claude اجرا می‌کند داخلِ همان کانتینر اجرا می‌شوند، نه روی ماشینِ میزبان؛ در همان حال، ویرایش‌هایی که روی فایل‌های پروژه انجام می‌شود، حین کار در مخزنِ محلیِ تو ظاهر می‌شود.

این صفحه نصب Claude Code در یک dev container و موضوع‌های پیکربندیِ پس از آن را پوشش می‌دهد. هر موضوع مستقل است، پس مستقیم به آن‌هایی برو که با نیازِ راه‌اندازیِ تو می‌خواند:

dev containerها چطور با ویرایشگرت کار می‌کنندDiagram showing an editor on the host connecting to a Docker dev container. Claude Code, the terminal, and build tools run inside the container. The host repository is bind-mounted into the container as the workspace.

یک dev container به‌صورت یک کانتینرِ Docker اجرا می‌شود، یا روی ماشینِ تو یا روی یک میزبانِ ابری مثل GitHub Codespaces. ویرایشگری که از مشخصاتِ Dev Containers پشتیبانی می‌کند — مثل VS Code، GitHub Codespaces، یک IDE از JetBrains یا Cursor — به آن کانتینر متصل می‌شود: تو مثل همیشه فایل‌ها را در ویرایشگر مرور و ویرایش می‌کنی، اما ترمینالِ یکپارچه، language serverها و ابزارهای build همگی داخلِ کانتینر اجرا می‌شوند، نه روی میزبانت. ویرایشگرهای بدون پشتیبانی از dev container، مثل Vimِ ساده، بخشی از این ورک‌فلو نیستند.

Claude Code داخلِ کانتینر اجرا می‌شود، پس همان فایل‌ها، وابستگی‌ها و ابزارهایی را می‌بیند که بقیه‌ی زنجیره‌ابزارِ پروژه‌ات می‌بیند. در VS Code می‌توانی یا از پنلِ افزونه‌ی Claude Code استفاده کنی یا claude را در ترمینالِ یکپارچه اجرا کنی؛ هردو داخلِ کانتینر اجرا می‌شوند و همان پیکربندیِ ~/.claude را به اشتراک می‌گذارند.

افزودن Claude Code به dev container

Section titled “افزودن Claude Code به dev container”

Claude Code از طریقِ قابلیتِ Dev Container مخصوصِ Claude Code روی هر dev containerی نصب می‌شود.

این تنظیمات با هر ابزاری که از مشخصاتِ Dev Containers پشتیبانی می‌کند کار می‌کند، مثل VS Code، GitHub Codespaces یا IDEهای JetBrains. گام‌های زیر VS Code را به‌عنوان نمونه به کار می‌برند.

وقتی کانتینر را در VS Code یا Codespaces باز می‌کنی، این قابلیت افزونه‌ی Claude Code برای VS Code را هم اضافه می‌کند؛ سایر ویرایشگرها آن بخش را نادیده می‌گیرند.

ساختن یا به‌روزرسانی devcontainer.json

موارد زیر را به‌عنوان .devcontainer/devcontainer.json در مخزنت ذخیره کن، یا بلوکِ features را به فایلِ موجودت اضافه کن.

تگِ نسخه در انتها، مثل :1.0، اسکریپتِ نصبِ این قابلیت را پین می‌کند، نه نسخه‌ی انتشارِ Claude Code را. این قابلیت آخرین نسخه‌ی Claude Code را نصب می‌کند و Claude Code به‌صورت پیش‌فرض خودش را داخلِ کانتینر خودکار به‌روز می‌کند.

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

{
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}
  }
}

خطِ image را با ایمیجِ پایه‌ی پروژه‌ات جایگزین کن، یا اگر فایلِ موجودت از Dockerfile استفاده می‌کند آن را حذف کن.

rebuild کردنِ کانتینر

Command Palette در VS Code را با Cmd+Shift+P روی Mac یا Ctrl+Shift+P روی Windows و Linux باز کن و Dev Containers: Rebuild Container را اجرا کن.

برای ابزارهای دیگر، اقدامِ rebuild همان ابزار را دنبال کن: rebuild در GitHub Codespaces، Dev Containers CLI، یا مستنداتِ dev container مربوط به IDEات را ببین.

ورود به Claude Code

در کانتینرِ rebuild‌شده یک ترمینال باز کن و claude را اجرا کن، سپس پرامپتِ احراز هویت را دنبال کن.

آنچه در پرامپتِ احراز هویت می‌بینی به ارائه‌دهنده‌ات بستگی دارد:

  • Anthropic: از طریقِ مرورگر با حسابِ Claude یا Anthropic Console خود وارد شو
  • Amazon Bedrock، Google Vertex AI، یا Microsoft Foundry: Claude Code از اعتبارنامه‌های ارائه‌دهنده‌ی ابریِ تو استفاده می‌کند، بدونِ پرامپتِ مرورگر

برای ارائه‌دهنده‌های ابری، اعتبارنامه‌ها را از طریقِ containerEnv، یک سکرتِ Codespaces، یا workload identity ابرت به‌صورت متغیرهای محیطی به کانتینر بده، نه با mount‌کردنِ فایل‌های اعتبارنامه از میزبان. برای زنجیره‌ی اعتبارنامه‌ای که Claude Code می‌خواند، Amazon Bedrock، Google Vertex AI، یا Microsoft Foundry را ببین.

برای تصمیم‌گیری درباره‌ی اینکه کدام مسیر با سازمانت می‌خواند، انتخاب ارائه‌دهنده‌ی API را ببین.

حفظ احراز هویت و تنظیمات در طولِ rebuildها

Section titled “حفظ احراز هویت و تنظیمات در طولِ rebuildها”

به‌صورت پیش‌فرض، دایرکتوریِ home کانتینر هنگامِ rebuild دور ریخته می‌شود، پس مهندس‌ها باید هر بار دوباره وارد شوند. Claude Code توکنِ احراز هویت، تنظیماتِ کاربر و تاریخچه‌ی نشست‌ها را زیرِ ~/.claude ذخیره می‌کند. یک volumeِ نام‌دار را روی آن مسیر mount کن تا این وضعیت در طولِ rebuildها حفظ شود.

نمونه‌ی زیر یک volume را روی دایرکتوریِ home کاربرِ node mount می‌کند:

"mounts": [
  "source=claude-code-config,target=/home/node/.claude,type=volume"
]

/home/node را با دایرکتوریِ home همان remoteUser کانتینرت جایگزین کن. اگر volume را جایی غیر از ~/.claude mount کنی، CLAUDE_CONFIG_DIR را روی مسیرِ mount تنظیم کن تا Claude Code همان‌جا بخواند و بنویسد.

برای اینکه وضعیت را به‌جای اشتراک‌گذاریِ یک volume بینِ همه‌ی مخزن‌ها، به‌ازای هر پروژه ایزوله کنی، متغیرِ ${devcontainerId} را در نامِ source بگنجان. پیکربندیِ مرجع برای همین منظور از source=claude-code-config-${devcontainerId} استفاده می‌کند.

در GitHub Codespaces، ~/.claude در طولِ توقف و شروعِ دوباره‌ی codespace حفظ می‌شود، اما هنگامِ rebuild کانتینر همچنان پاک می‌شود، پس همان mountِ volumeِ بالا آنجا هم کاربرد دارد. برای انتقالِ احراز هویت بینِ codespaceها، یک ANTHROPIC_API_KEY یا یک CLAUDE_CODE_OAUTH_TOKEN از claude setup-token را به‌صورت سکرتِ Codespaces ذخیره کن؛ Codespaces سکرت‌ها را به‌صورت خودکار به‌شکلِ متغیرهای محیطی داخلِ کانتینر در دسترس می‌گذارد.

اعمالِ سیاستِ سازمان

Section titled “اعمالِ سیاستِ سازمان”

dev container جای مناسبی برای اعمالِ سیاستِ سازمان است، چون همان ایمیج و پیکربندی روی ماشینِ هر مهندسی اجرا می‌شود.

Claude Code فایلِ /etc/claude-code/managed-settings.json را روی Linux می‌خواند و آن را با بالاترین تقدم در سلسله‌مراتبِ تنظیمات اعمال می‌کند، پس مقدارهای آنجا بر هرچیزی که مهندس در ~/.claude یا دایرکتوریِ .claude/ پروژه تنظیم کند ارجح است. این فایل را از Dockerfile سرِ جایش کپی کن:

RUN mkdir -p /etc/claude-code
COPY managed-settings.json /etc/claude-code/managed-settings.json

چون Dockerfile در مخزن قرار دارد، هرکسی با دسترسیِ نوشتن می‌تواند این گام را تغییر دهد یا حذف کند. برای سیاستی که مهندس‌ها نتوانند با ویرایشِ فایل‌های مخزن دورش بزنند، تنظیماتِ مدیریت‌شده را به‌جایش از طریقِ تنظیماتِ مدیریت‌شده‌ی سمتِ سرور یا MDM خود برسان. برای کلیدهای موجود و سایر مسیرهای تحویل، فایل‌های تنظیماتِ مدیریت‌شده را ببین.

برای تنظیمِ متغیرهای محیطی که روی هر نشستِ Claude Code در کانتینر اعمال می‌شود، آن‌ها را به containerEnv در devcontainer.json خود اضافه کن. نمونه‌ی زیر از تله‌متری و گزارشِ خطا انصراف می‌دهد و جلوی به‌روزرسانیِ خودکارِ Claude Code پس از نصب را می‌گیرد:

"containerEnv": {
  "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
  "DISABLE_AUTOUPDATER": "1"
}

قابلیتِ Dev Container همیشه آخرین نسخه‌ی انتشارِ Claude Code را نصب می‌کند. برای پین‌کردنِ یک نسخه‌ی مشخص از Claude Code برای buildهای تکرارپذیر، به‌جای استفاده از این قابلیت، آن را از Dockerfile خود با npm install -g @anthropic-ai/claude-code@X.Y.Z نصب کن و DISABLE_AUTOUPDATER را همان‌طور که بالا نشان داده شد تنظیم کن.

برای فهرستِ کاملِ کنترل‌های سیاست شامل قواعدِ دسترسی، محدودیت‌های ابزار و فهرستِ مجازِ MCP serverها، راه‌اندازی Claude Code برای سازمانت را ببین.

برای در دسترس‌کردنِ MCP serverها داخلِ کانتینر، آن‌ها را در دامنه‌ی پروژه در یک فایلِ .mcp.json در ریشه‌ی مخزن تعریف کن تا کنارِ پیکربندیِ dev containerات در سورس‌کنترل وارد شوند. هر باینری‌ای که serverهای stdioِ محلی به آن وابسته‌اند را در Dockerfile خود نصب کن، و دامنه‌های serverهای ریموت را به فهرستِ مجازِ شبکه‌ات اضافه کن.

محدودکردنِ ترافیکِ خروجیِ شبکه

Section titled “محدودکردنِ ترافیکِ خروجیِ شبکه”

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

کانتینرِ مرجع شاملِ یک اسکریپتِ init-firewall.sh است که همه‌ی ترافیکِ خروجی را به‌جز دامنه‌هایی که Claude Code و ابزارهای توسعه‌ات نیاز دارند مسدود می‌کند. اجرای یک فایروال داخلِ کانتینر به دسترسی‌های اضافی نیاز دارد، پس مرجع قابلیت‌های NET_ADMIN و NET_RAW را از طریقِ runArgs اضافه می‌کند. اسکریپتِ فایروال و این قابلیت‌ها برای خودِ Claude Code لازم نیستند: می‌توانی آن‌ها را کنار بگذاری و به‌جایش به کنترل‌های شبکه‌ی خودت اتکا کنی.

اجرا بدون پرامپت‌های دسترسی

Section titled “اجرا بدون پرامپت‌های دسترسی”

چون کانتینر، Claude Code را به‌عنوان یک کاربرِ غیرروت اجرا می‌کند و اجرای دستور را به کانتینر محدود می‌کند، می‌توانی برای کارِ بدونِ نظارت --dangerously-skip-permissions را پاس بدهی. CLI این پرچم را وقتی به‌عنوان روت اجرا شود رد می‌کند، پس مطمئن شو remoteUser روی یک حسابِ غیرروت تنظیم شده است.

ردکردنِ پرامپت‌های دسترسی، فرصتِ بازبینیِ فراخوانی‌های ابزار را پیش از اجرا از تو می‌گیرد. Claude همچنان می‌تواند هر فایلی را در workspaceِ bind-mount‌شده تغییر دهد، که مستقیماً روی میزبانت ظاهر می‌شود، و به هرچیزی که سیاستِ شبکه‌ی کانتینر اجازه می‌دهد دسترسی پیدا کند. این پرچم را با محدودیت‌های ترافیکِ خروجیِ شبکه‌ی بالا جفت کن تا محدود کنی یک نشستِ دورزده‌شده به چه چیزی می‌تواند برسد.

اگر پرامپت‌های کمتری می‌خواهی بدون غیرفعال‌کردنِ بررسی‌های ایمنی، به‌جایش auto mode را در نظر بگیر، که یک طبقه‌بند، اقدام‌ها را پیش از اجرا بازبینی می‌کند. برای اینکه به‌کلی جلوی استفاده‌ی مهندس‌ها از --dangerously-skip-permissions را بگیری، در تنظیماتِ مدیریت‌شده مقدارِ permissions.disableBypassPermissionsMode را روی "disable" بگذار.

امتحانِ کانتینرِ مرجع

Section titled “امتحانِ کانتینرِ مرجع”

مخزنِ anthropics/claude-code شاملِ یک نمونه dev container است که CLI، فایروالِ خروجی، volumeهای ماندگار و یک شلِ مبتنی بر Zsh را با هم ترکیب می‌کند. این به‌عنوان یک نمونه‌ی کاربردی ارائه شده، نه یک ایمیجِ پایه‌ی نگه‌داری‌شده؛ از آن استفاده کن تا ببینی قطعه‌ها چطور کنارِ هم می‌نشینند، پیش از آنکه آن‌ها را روی پیکربندیِ خودت اعمال کنی.

نصبِ پیش‌نیازها

VS Code و افزونه‌ی Dev Containers را نصب کن.

کلونِ مرجع

مخزنِ Claude Code را کلون کن و در VS Code باز کن.

بازکردنِ دوباره داخلِ کانتینر

وقتی از تو خواسته شد، روی Reopen in Container کلیک کن، یا از Command Palette دستورِ Dev Containers: Reopen in Container را اجرا کن.

شروعِ Claude Code

وقتی build کانتینر تمام شد، با Ctrl+` یک ترمینال باز کن و claude را اجرا کن تا وارد شوی و اولین نشستت را شروع کنی.

برای استفاده از این پیکربندی با پروژه‌ی خودت، دایرکتوریِ .devcontainer/ را در مخزنت کپی کن و Dockerfile را برای زنجیره‌ابزارت تنظیم کن، یا به افزودن Claude Code به dev container برگرد تا فقط همان قابلیت را به راه‌اندازیِ موجودت اضافه کنی.

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

فایلهدف
devcontainer.jsonmountهای volume، قابلیت‌های runArgs، افزونه‌های VS Code، و containerEnv
Dockerfileایمیجِ پایه، ابزارهای توسعه، و نصبِ Claude Code
init-firewall.shهمه‌ی ترافیکِ خروجیِ شبکه را به‌جز دامنه‌های مجاز مسدود می‌کند

گام‌های بعدی

Section titled “گام‌های بعدی”

وقتی Claude Code در dev containerات در حالِ اجراست، صفحه‌های زیر بقیه‌ی استقرارِ سازمانی را پوشش می‌دهند: انتخابِ مسیرِ احراز هویت، رساندنِ سیاستِ مدیریت‌شده بیرون از مخزن، پایشِ استفاده، و درکِ آنچه Claude Code ذخیره و ارسال می‌کند.