Agentbox - بيئة معزولة لوكلاء البرمجة

لا توجد طريقة مثالية لعزل الوكلاء (حتى الآن)، لكن الحاويات تُعدّ بداية عملية.

Agentbox هي بيئة معزولة لوكلاء البرمجة مبنية على Docker، مستوحاة في الأصل من Batrachian Toad، وأصبحت الآن معمّمة لأدوات أكثر. توفّر بيئة معزولة تعمل بشكل جيد مع webterm لتشغيل جلسات وكلاء متعددة.

الميزات

توفّر الحاوية الافتراضية ما يلي:

• بيئة تطوير: Debian Stable مع أدوات التطوير الشائعة
• وكلاء برمجة مثبّتون مسبقًا: Copilot CLI، Codex، Pi
• أدوات CLI مثبّتة مسبقًا: gh، Nushell، lazygit، killall
• مديرو الحزم: Homebrew وAPT، بالإضافة إلى uv وBun؛ تقوم عمليات بناء الحاوية بتثبيت أحدث الحزم المتاحة دون تثبيت إصدارات محددة
• أدوات الوكلاء الاختيارية: ثبّت toad وopencode وgemini وvibe عبر make -C ~ ...
• التحكم بالخدمات: فعّل/عطّل Docker/SSH/RDP باستخدام ENABLE_DOCKER وENABLE_SSH وENABLE_RDP
• Docker داخل Docker: متاح عندما تعمل الحاويات في الوضع المميّز (privileged)
• الوصول عن بُعد: دعم SSH (ENABLE_SSH=true) وmosh
• تهيئة مساحة العمل: هيكل مساحة عمل مدمج ومهارات الوكلاء ضمن /home/agent/workspace-skel

خارطة الطريق

• حدود المعالج والذاكرة (قيود موارد Docker الأساسية)
• خيارات عزل الشبكة
• تقنيات عزل أخرى (gVisor، Kata Containers، إلخ)

إعدادات الخدمات

يستخدم Agentbox متغيرات البيئة للتحكم في الخدمات التي تبدأ عند تشغيل الحاوية:

• ENABLE_DOCKER=true - تشغيل خدمة Docker (لدعم Docker داخل Docker)
• ENABLE_SSH=true - تشغيل خادم SSH (المنفذ 22)
• ENABLE_RDP=true - تشغيل خادم RDP (المنفذ 3389)
• AGENTBOX_ENVIRONMENT=cli|gui - علامة البيئة التي توفّرها الصورة (cli للبيئة بلا واجهة/CLI، وgui لصور سطح المكتب)

السلوك الافتراضي: جميع الخدمات معطّلة ما لم يتم تفعيلها صراحةً.

أمثلة:

# Default - all services disabled
docker run -d agentbox

# Enable only Docker daemon
docker run -d -e ENABLE_DOCKER=true agentbox

# Enable Docker and SSH for development
docker run -d -e ENABLE_DOCKER=true -e ENABLE_SSH=true -p 22:22 agentbox

# Full desktop experience with all services (GUI image)
docker run -d -e ENABLE_DOCKER=true -e ENABLE_SSH=true -e ENABLE_RDP=true -p 22:22 -p 3389:3389 agentbox:gui

البدء السريع

تثبيت الأدوات الاختيارية

داخل الحاوية، يأتي المستخدم agent مع ملف ~/Makefile يمكنه تثبيت أدوات إضافية.

وكلاء البرمجة/أدوات CLI التي يمكنك تثبيتها عبر make -C ~ …:

• toad — يثبّت Batrachian Toad (عبر uv tool)
• opencode — يثبّت OpenCode (عبر Bun)
• gemini — يثبّت Gemini CLI (عبر Homebrew)
• vibe — يثبّت mistral-vibe (عبر uv tool)

أهداف تسهيلية:

• tools — يثبّت node وgo وgemini وvibe
• node وgo — يثبّتان سلاسل أدوات اللغات (متطلبات مسبقة لبعض الوكلاء)

هيكل مساحة العمل

يوفّر Agentbox هيكل مشروع مدمجًا في /home/agent/workspace-skel.

لنسخه إلى /workspace الحالي دون الكتابة فوق الملفات الموجودة:

make init-workspace

راجع docs/workspace-skeleton.md للتفاصيل.

صورة GUI

يُنشر بناء GUI بوسم :gui (وأيضًا <release>-gui) ويتضمّن XFCE وXRDP وVS Code.

Docker Compose

سير العمل الموصى به:

make up
make enter-toad   # or: make enter-copilot
make down

إذا كنت بحاجة إلى تجاوزات للخدمات، أنشئ docker-compose.override.yml:

services:
  toad:
    environment:
      ENABLE_DOCKER: "true"
      ENABLE_SSH: "true"
  copilot:
    environment:
      ENABLE_DOCKER: "true"
      ENABLE_SSH: "true"

ثم شغّل:

docker compose up -d

استخدام Docker مباشرةً

# Build the headless image
docker build -t agentbox .

# Build the GUI image
docker build -t agentbox:gui --target gui .

# Run the container with selected services (GUI image)
docker run -d \
  --name agentbox \
  --privileged \
  -e ENABLE_DOCKER=true \
  -e ENABLE_SSH=true \
  -e ENABLE_RDP=true \
  -p 22:22 \
  -p 3389:3389 \
  -v $(pwd):/workspace \
  agentbox:gui

استخدام Batrachian Toad

بعد الاتصال بالحاوية:

1. ثبّت Toad (إذا لزم الأمر):

make -C ~ toad

2. شغّل Toad:

toad

3. أو ابدأ مع دليل مشروع محدد:

toad /workspace

4. أو شغّله مباشرةً مع وكيل:

toad -a open-hands

ملاحظات أمنية

• التحكم بالخدمات: افتراضيًا، جميع الخدمات (Docker وSSH وRDP) معطّلة. فعّل فقط ما تحتاجه صراحةً باستخدام متغيرات البيئة.
• كلمات المرور الافتراضية ضعيفة - غيّرها للاستخدام في بيئة الإنتاج
• تحتاج الحاوية إلى العمل في الوضع المميّز (privileged) ليكون Docker داخل Docker متاحًا لوكلائك (وهذا أفضل من لا شيء)
• فكّر في استخدام مفاتيح SSH بدلًا من المصادقة بكلمة المرور
• للاستخدام في بيئة الإنتاج، فكّر في تعطيل الخدمات غير الضرورية وتغيير بيانات الاعتماد الافتراضية

شكر وتقدير

يستند هذا المشروع بشكل غير مباشر إلى مشروعي القديم rcarmo/docker-templates/desktop-chrome مع بيئة مستخدم محدّثة.

الترخيص

MIT