چیت‌شیت
ساندباکس‌های Docker برای ایجنت‌ها
Docker Sandboxes for Agents
اجرای یک ایجنت در microVM، کنترل شبکه و کلیدها، دریافت commitهای آن. sbx 0.47.0، docker-agent 1.149.0.
فهرست مطالب
چه چیزی کجا اجرا می‌شود
معمارییک درخواست از ساندباکس خارج می‌شود
گام‌به‌گام- sbx createدیمن sandboxd قالب را دریافت و microVM را بوت می‌کند.
- ایجنتدرخواست را به فوروارد پروکسی روی هاست می‌فرستد.
- اعتبارسنج (Authorizer)تطابق با deny اولویت دارد. نبود قانون allow معادل رد ضمنی (implicit deny) است.
- مسدودشدهپروکسی درون TLS با کد 403 و خطای «Approval required» پاسخ می‌دهد.
- مجازپروکسی ترافیک میزبان را به صورت
forward-bypassتونل می‌کند. - راز پیوندخوردهپروکسی مقدار نگهدارنده (sentinel) را با مقدار ذخیره‌شده جایگزین می‌کند.
- لاگ پالیسییک سطر برای هر هاست همراه با نوع پروکسی و قانون اعمال‌شده.
چرخه حیات ساندباکس
کار و کد| وظیفه | کد |
|---|---|
| ایجاد روی یک مخزن | sbx create shell <path> --name <name> |
| اتصال مجدد (Attach) | sbx run --name <name> |
| اجرای دستور در نقش root | sbx exec -u root <name> sh -c '<cmd>' |
| کپی کردن فایل به داخل | sbx cp <host-file> <name>:/tmp/in.txt |
| انتشار پورت | sbx ports <name> --publish 18081:8080 |
| متوقف‌سازی و حفظ وضعیت | sbx stop <name> |
| حذف ساندباکس‌های متوقف‌شده | sbx prune --force |
رازها، MCP و سلامت
کار و کد| وظیفه | کد |
|---|---|
| پیوند یک راز به هاست‌ها | sbx secret set-custom --host <host> --env <VAR> --value <value> |
| یافتن کلیدها در متغیرهای محیطی هاست | sbx secret import --dry-run |
| ثبت یک سرور MCP | sbx mcp add <name> --url <url> |
| اتصال آن به یک ساندباکس | sbx mcp load <name> --sandbox <sandbox> |
| اجرای 13 بررسی سلامت | sbx diagnose |
| ذخیره یک قالب | sbx template save <name> <tag> --output <file>.tar |
| اجرای فایل ایجنت درون ساندباکس | docker-agent run --sandbox --exec <agent-file> '<prompt>' |
چرخه رفت و برگشت حالت Clone
کدbash
sbx create --clone shell <repo> \ # کلون خصوصی، مخزن هاست فقط‌خواندنی
--name <name> # سورس‌کد در /run/sandbox/source
sbx exec <name> sh -c '<edit and git commit>' # ایجنت در کلون commit می‌زند
git -C <repo> remote -v # افزوده شدن sandbox-<name> توسط sbx
git -C <repo> fetch sandbox-<name> # بازگرداندن commitها
sbx rm --force <name> # حذف VM، وضعیت و رازهای محلی دامنه
دیباگ یک هاست مسدودشده
کدbash
sbx policy init balanced # یک‌بار، قبل از اولین ساندباکس
sbx create shell --name m101-policy # بدون mount فضای کاری
sbx exec m101-policy sh -c \
'curl -sS --max-time 10 https://example.com' # نیاز به تایید (Approval required)
sbx policy log m101-policy # فوروارد، پیش‌فرض مسدود (default deny)
sbx policy allow network \
--sandbox m101-policy example.com # قانون برای یک ساندباکس
sbx policy check network example.com \
--sandbox m101-policy --verbose --json # مجوز خواندن داده شد، قانون
آنچه ایجنت از درون می‌بیند
دستورها| دستور | عملکرد آن |
|---|---|
HTTPS_PROXY=http://gateway.docker.internal:3128 | فوروارد پروکسی برای HTTP و HTTPS |
ANTHROPIC_API_KEY=proxy-managed | نگهدارنده (Sentinel). کلید واقعی روی هاست باقی می‌ماند |
M101_RECV_KEY=sbx-cs-<rand> | نگهدارنده‌ی سفارشی برای راز |
SSH_AUTH_SOCK=/run/ssh-agent.sock | ایجنت SSH هاست، فورواردشده به‌طور پیش‌فرض |
forward-bypass | نوع لاگ پروکسی: تونل، بدون بازرسی محتوا |
transparent | نوع لاگ پروکسی: سایر اتصالات TCP، بدون تزریق |
"deny_kind": "explicit" | یک قانون آن را رد کرد. implicit یعنی عدم وجود مجوز |
مقادیر پیش‌فرض
پیش‌فرض‌ها| تنظیم | پیش‌فرض | نکته |
|---|---|---|
--name | <agent>-<workdir> | آن را تنظیم کنید تا دو ایجنت از هم جدا بمانند |
-m, --memory | 50% of host memory | محدود بین 512 MiB تا 32 GiB |
--pull | always | همچنین missing یا never |
--skills | readonly | همچنین off یا readwrite |
secret set --refresh | 55m | تازه‌سازی برای سورس‌کد داینامیک |
ssh.agentForwardingEnabled | true | برای ایجنت‌های غیرقابل اعتماد خاموش شود |
sandbox.disk.dockerVolume | 10g | حجم دایرکتوری /var/lib/docker |
kit.allowedSources | ["docker.io/"] | منابع مجاز کیت ریموت |
مفاهیم کلیدی
مفهوم‌ها- ساندباکس
- یک microVM با کرنل اختصاصی و Docker Engine خصوصی.
- حالت Clone
- فلگ
--clone. ایجنت روی یک کلون اختصاصی کار می‌کند. commitها از طریق Remote بازمی‌گردند. - پیش‌تنظیم (Preset)
- مقادیر
allow-all،balancedیاdeny-all، باsbx policy initیک‌بار تنظیم می‌شود. - دامنه پالیسی
- مقدار
globalبرای همه ساندباکس‌ها، یا یک ساندباکس خاص با--sandbox. - اولویت با رد (Deny wins)
- قانون deny بر قانون allow برای همان هاست اولویت دارد.
- نگهدارنده (Sentinel)
- مقداری صوری که ایجنت به جای کلید یا راز اصلی می‌بیند.
عیب‌یابی
عیب‌یابیApproval required for example.com:443.- علت
- هیچ قانون allow تطابق ندارد
- راه‌حل
sbx policy allow network --sandbox <name> <host>
شکست دستور curl به
::1با کد خطای 7- علت
- پورت به صورت
tcp4پابلیش شده است - راه‌حل
- پابلیش پورت به صورت
8080/tcpبرای هر دو پروتکل
copying between sandboxes is not supported- علت
- دستور
cpبه سمت هاست نیاز دارد - راه‌حل
- کپی از طریق هاست
رد شدن:
conflicts with existing allow rule- علت
- وجود همزمان allow و deny در یک دامنه
- راه‌حل
- ابتدا
sbx policy rm network --id <uuid>
عدم دریافت کلید API از
~/.zshrc- علت
- متغیرهای هاست از نسخه v0.35.0 به بعد خوانده نمی‌شوند
- راه‌حل
sbx secret setیاsbx secret import
ensure daemon: daemon exited unexpectedly- علت
- مشکل در دیمن sandboxd
- راه‌حل
sbx daemon status --json، بررسی فایلdaemon.log
پرسش و پاسخ
پرسش و پاسخ- آیا به Docker Desktop نیاز دارم؟
- خیر. نیاز به
sbx loginدارید. کانتینرهای ایجنت درdocker psهاست دیده نمی‌شوند. - stop یا rm؟
- دستور
sbx stopوضعیت را نگه می‌دارد.sbx rmساندباکس، وضعیت آن و رازهای محلی را پاک می‌کند. - آیا allow کردن هاست مانع آپلود gist می‌شود؟
- خیر. هاستِ مجاز هر متد، مسیر و بدنه‌ای را عبور می‌دهد.
- آیا ایجنت کلید من را می‌بیند؟
- خیر. مقدار
proxy-managedرا می‌بیند. پروکسی کلید را بعد از خروج از VM اضافه می‌کند.
نکات کاربردی
نکته‌ها- حافظه، پورت‌ها، مهارت‌ها و سرورهای MCP استاتیک را هنگام ساخت تعیین کنید؛ اتصال مجدد آن‌ها را نادیده می‌گیرد.
- قبل از prune، دستور
sbx prune --dry-runرا اجرا کنید. - قوانین محدود را با
--sandboxاضافه کنید. قوانین global را فقط برای هاست‌های مشترک همه ایجنت‌ها نگه دارید. - کلیدها را با
sbx secret setذخیره کنید، هرگز از-e KEYاستفاده نکنید. - رازهای سفارشی را دقیقاً به هاست‌های مقصد پیوند دهید. پروکسی مقدار نگهدارنده را در هر کجای درخواست جایگزین می‌کند.