
بيئة اختبار محلية لوكلاء الذكاء الاصطناعي لديك.
يساعدك CodeRunner على عزل وكلاء الذكاء الاصطناعي وإجراءاتهم داخل بيئة معزولة (sandbox).
حالة الاستخدام الرئيسية: تشغيل كود وكيل الذكاء الاصطناعي داخل بيئة معزولة مع نقاط تركيب (mounts) على المضيف ومنافذ شبكة محددة صراحةً. يقلل العزل من المخاطر؛ لكنه لا يمنع كل فقدان للبيانات أو تسريبها.
للحصول على أجهزة افتراضية سحابية مُدارة للوكلاء، أطلقنا - InstaVM - حواسيب فورية لوكلاء الذكاء الاصطناعي
المتطلبات المسبقة: جهاز Mac يعمل بنظام macOS مع معالج Apple Silicon (M1/M2/M3/M4)، وPython 3.10+
يُنشئ المثبّت رمز البيئة المعزولة (sandbox token) في ~/.coderunner/api-token (أو يحفظ
CODERUNNER_API_TOKEN الذي قمت بتصديره). يرسله العملاء عبر
Authorization: Bearer <token>؛ ويطبعه الأمر cat ~/.coderunner/api-token. فقط
GET /health عام، وأي رمز مفقود أو ضعيف يؤدي إلى الفشل الآمن (fail closed). يقرأ وكيل Claude
Desktop والأمثلة الرمز من ذلك الملف عندما لا يكون المتغير
مضبوطًا. راجع المصادقة وحدود الشبكة.
git clone https://github.com/instavm/coderunner.git
cd coderunner
chmod +x install.sh
./install.sh
أوقف الـ sandbox عند الانتهاء:
container stop coderunner
استأنف نفس الصندوق الرملي لاحقًا، مع الحفاظ على نظام ملفاته. حالة نواة Python متطايرة ولا تصمد أمام إعادة تشغيل الجهاز الافتراضي أو الخادم:
container start coderunner
لبدء من جديد باستخدام بيئة اختبار نظيفة، احذف الحاوية ثم شغّل برنامج التثبيت مرة أخرى:
container delete coderunner && ./install.sh
يمكن ضبط حدود وحدة المعالجة المركزية والذاكرة عبر خيارات المثبّت أو متغيرات البيئة CODERUNNER_CPUS وCODERUNNER_MEMORY:
./install.sh --cpus 4 --memory 8g
يجب تركيب أدلة المضيف الإضافية تحت /workspace. وهي للقراءة فقط افتراضيًا؛ أضف :rw فقط عندما تحتاج البيئة المعزولة (sandbox) إلى الكتابة إلى المضيف:
./install.sh \
--mount "$HOME/projects/api:/workspace/api" \
--mount "$HOME/projects/output:/workspace/output:rw"
التركيبات الإضافية (extra mounts) افتراضيًا لا شيء. تُثبَّت إعدادات الموارد والتركيب عند إنشاء الحاوية؛ احذف الحاوية قبل تغييرها.
افتراضيًا، يمتلك الكود الذي يعمل في وضع الحماية (sandbox) وصولًا غير مقيّد إلى الشبكة. لتشغيله على شبكة مضيف فقط (host-only) دون الوصول إلى الإنترنت:
CODERUNNER_NETWORK=none ./install.sh
في هذا الوضع، يكون خادم MCP متاحًا على http://127.0.0.1:8222/mcp. يُثبَّت هذا الإعداد عند إنشاء الحاوية؛ ويرفض المثبِّت استئناف حاوية ذات وضع شبكة مختلف.
يشغّل Claude Code الأوامر على جهازك، بصلاحياتك أنت، مع كون مطالبات الأذونات هي الحد الوحيد. أما توجيهه إلى أدوات CodeRunner فيشغّل الكود الذي يكتبه داخل الآلة الافتراضية: فلا يمكنه لمس سوى المجلدات التي وصّلتها تحت /workspace، والشبكة التي سمحت بها، ونظام ملفات البيئة المعزولة نفسه، أيًّا كان ما أُمر بفعله. استخدم البيئة المعزولة للكود الذي يتعامل مع مدخلات غير موثوقة أو الذي لن تشغّله يدويًا، ولعدة وكلاء يجب ألا يتشاركوا الحالة (الجلسات المسماة). وهي لا تحمي أي شيء توصّله بصلاحية قراءة وكتابة.
./install.sh (إن لم يكن قد نُفِّذ بالفعل)
container exec -it coderunner /bin/bash
root@coderunner:/app# npm install -g @anthropic-ai/claude-code
سيكون خادم MCP متاحًا على: http://coderunner.local:8222/mcp
ينشئ المثبِّت ~/.coderunner/venv لوكيل Claude Desktop. أما أمثلة Python الأخرى، فثبِّت تبعياتها في بيئتك الافتراضية الخاصة:
pip install -r examples/requirements.txt



انسخ ملف التكوين النموذجي:
cd examples
cp claude_desktop/claude_desktop_config.example.json claude_desktop/claude_desktop_config.json
حرّر ملف الإعدادات واستبدل المسارات النائبة:
/path/to/your/python بـ $HOME/.coderunner/venv/bin/python باستخدام المسار الكامل إلى دليل المنزل الخاص بك/path/to/coderunner بالمسار الفعلي إلى المستودع الذي استنسختهمثال بعد التحرير:
{
"mcpServers": {
"coderunner": {
"command": "/Users/yourname/.coderunner/venv/bin/python",
"args": ["/Users/yourname/coderunner/examples/claude_desktop/mcpproxy.py"]
}
}
}
تحديث إعدادات Claude Desktop:
ابدأ باستخدام CodeRunner في Claude: الكود الذي يكتبه Claude الآن يُنفَّذ داخل البيئة المعزولة.
إذا ظهرت الأداة بحالة "Disabled" في قائمة أدوات المحادثة رغم أن الخادم مُدرج كقيد التشغيل: أغلق Claude
Desktop بالكامل (Cmd-Q) وافتحه مجددًا، وتأكد من أن command هو python الخاص بالبيئة الافتراضية الذي طبعه المُثبِّت (فهو
يحتوي على fastmcp)، واقرأ ~/Library/Logs/Claude/mcp-server-coderunner.log للاطلاع على خطأ الوسيط. يحتاج الوسيط
إلى البيئة المعزولة قيد التشغيل (container list) وملف الرمز المميز ~/.coderunner/api-token.
البدء السريع:
# 1. Install and start CodeRunner (one-time setup; run as yourself, it asks for sudo when it needs it)
git clone https://github.com/instavm/coderunner.git
cd coderunner
./install.sh
# 2. Add the sandbox with its token (the installer prints this command)
claude mcp add --transport http coderunner http://coderunner.local:8222/mcp \
--header "Authorization: Bearer $(cat ~/.coderunner/api-token)"
# 3. Reconnect to MCP servers
/mcp
إضافة Claude Code (claude plugin marketplace add https://github.com/instavm/coderunner-plugin) أقدم من
الرمز وتُعيد 401 حتى ترسل الترويسة نفسها؛ استخدم الأمر أعلاه حتى يتم تحديث الإضافة.
خطوات التثبيت:
انتقل إلى سوق الإضافات:

أضف مستودع InstaVM:

نفّذ كود Python باستخدام Claude Code:
