sandbox-agent

شغّل عوامل الترميز في الصناديق الرملية. تحكم بها عبر HTTP.

خادم يعمل داخل الصندوق الرملي الخاص بك. يتصل تطبيقك عن بُعد للتحكم في Claude Code، Codex، OpenCode، Cursor، Amp، أو Pi — بث الأحداث، معالجة الأذونات، إدارة الجلسات.

الوثائق — مرجع API — Discord

تجريبي: Gigacode — استخدم واجهة OpenCode النصية مع أي عامل ترميز.

لماذا Sandbox Agent؟

تشغيل عوامل الترميز عن بُعد صعب. تفترض حزم SDK الحالية التنفيذ المحلي، و SSH يعطل معالجة TTY والبث، وكل عامل له API مختلف. البناء من الصفر يعني إعادة تنفيذ كل شيء لكل عامل ترميز.

يحل Sandbox Agent ثلاث مشاكل:

1. عوامل الترميز تحتاج إلى صناديق رملية — لا يمكنك ترك الذكاء الاصطناعي ينفذ أكوادًا عشوائية على خوادم الإنتاج الخاصة بك. عوامل الترميز تحتاج إلى بيئات معزولة، لكن حزم SDK الحالية تفترض التنفيذ المحلي. Sandbox Agent هو خادم يعمل داخل الصندوق الرملي ويعرض HTTP/SSE.

2. كل عامل ترميز مختلف — Claude Code، Codex، OpenCode، Cursor، Amp، و Pi لكل منها APIs، تنسيقات أحداث، وسلوكيات خاصة. تغيير العامل يعني إعادة كتابة التكامل الخاص بك. يوفر Sandbox Agent واجهة HTTP واحدة — اكتب كودك مرة واحدة، وبدّل العوامل بتغيير الإعدادات.

3. الجلسات مؤقتة — نصوص العامل تعيش في الصندوق الرملي. عند انتهاء العملية، تفقد كل شيء. يقوم Sandbox Agent ببث الأحداث في مخطط عالمي إلى مساحة التخزين الخاصة بك. احفظها في Postgres أو ClickHouse أو Rivet. أعد تشغيلها لاحقًا، ودقّق كل شيء.

الميزات

• واجهة API عالمية للعوامل: واجهة واحدة للتحكم في Claude Code و Codex و OpenCode و Cursor و Amp و Pi مع تغطية كاملة للميزات
• مخطط جلسة عالمي: مخطط موحّد يطبّع جميع تنسيقات أحداث العامل للتخزين وإعادة التشغيل
• يعمل داخل أي صندوق رملي: ملف Rust ثابت خفيف الوزن. أمر curl واحد للتثبيت داخل E2B أو Daytona أو Modal أو Cloudflare Containers أو Agent Computer أو Docker
• وضع الخادم أو حزمة SDK: يعمل كخادم HTTP أو يُضمّن مع حزمة TypeScript SDK
• مواصفات OpenAPI: موثّقة جيدًا وسهلة التكامل من أي لغة
• دعم حزمة OpenCode SDK وواجهة المستخدم (تجريبي): قم بتوصيل OpenCode CLI أو SDK أو واجهة الويب للتحكم في العوامل من خلال أدوات OpenCode المألوفة

البنية المعمارية

يعمل Sandbox Agent كمحول عالمي بين تطبيق العميل الخاص بك وعوامل الترميز المختلفة. كل عامل له محوله الخاص الذي يتولى الترجمة بين API العالمي والواجهة الخاصة بالعامل.

• الوضع المضمّن: يشغّل العوامل محليًا كعمليات فرعية
• وضع الخادم: يعمل كخادم HTTP من أي مزود صناديق رملية

وثائق البنية المعمارية

المكونات

ابدأ

اختر طريقة التثبيت التي تناسب حالتك الاستخدامية.

Skill

قم بتثبيت skill باستخدام:

npx skills add rivet-dev/skills -s sandbox-agent

bunx skills add rivet-dev/skills -s sandbox-agent

حزمة TypeScript SDK

قم باستيراد حزمة SDK مباشرة إلى تطبيق Node.js أو المتصفح الخاص بك. أمان كامل للنوع ودعم للبث.

التثبيت

npm install [email protected]

bun add [email protected]
# اختياري: السماح لـ Bun بتشغيل نصوص ما بعد التثبيت للملفات الثنائية الأصلية (مطلوب لـ SandboxAgent.start()).
bun pm trust @sandbox-agent/cli-linux-x64 @sandbox-agent/cli-linux-arm64 @sandbox-agent/cli-darwin-arm64 @sandbox-agent/cli-darwin-x64 @sandbox-agent/cli-win32-x64

الإعداد

محليًا (الوضع المضمّن):

import { SandboxAgent } from "sandbox-agent";

const client = await SandboxAgent.start();

عن بُعد (وضع الخادم):

import { SandboxAgent } from "sandbox-agent";

const client = await SandboxAgent.connect({
  baseUrl: "http://127.0.0.1:2468",
  token: process.env.SANDBOX_TOKEN,
});

نظرة عامة على API

const agents = await client.listAgents();

await client.createSession("demo", {
  agent: "codex",
  agentMode: "default",
});

await client.postMessage("demo", { message: "Hello from the SDK." });

for await (const event of client.streamEvents("demo", { offset: 0 })) {
  console.log(event.type, event.data);
}

وثائق حزمة SDK — إدارة الجلسات

خادم HTTP

شغّل كخادم HTTP واتصل من أي لغة. انشره على E2B أو Daytona أو Vercel أو البنية التحتية الخاصة بك.

# قم بتثبيته
curl -fsSL https://releases.rivet.dev/sandbox-agent/0.4.x/install.sh | sh
# شغّله
sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468

اختياري: قم بتثبيت ملفات العوامل الثنائية مسبقًا (لا حاجة للخادم؛ سيتم تثبيتها بشكل كسول عند أول استخدام إذا تخطيت هذه الخطوة):

sandbox-agent install-agent --all

لتعطيل المصادقة محليًا:

sandbox-agent server --no-token --host 127.0.0.1 --port 2468

دليل البدء السريع — أدلة النشر

واجهة CLI

قم بتثبيت غلاف CLI (اختياري لكنه ملائم):

npm install -g @sandbox-agent/[email protected]

# اسمح لـ Bun بتشغيل نصوص ما بعد التثبيت للملفات الثنائية الأصلية.
bun add -g @sandbox-agent/[email protected]
bun pm -g trust @sandbox-agent/cli-linux-x64 @sandbox-agent/cli-linux-arm64 @sandbox-agent/cli-darwin-arm64 @sandbox-agent/cli-darwin-x64 @sandbox-agent/cli-win32-x64

أنشئ جلسة وأرسل رسالة:

sandbox-agent api sessions create my-session --agent codex --endpoint http://127.0.0.1:2468 --token "$SANDBOX_TOKEN"
sandbox-agent api sessions send-message my-session --message "Hello" --endpoint http://127.0.0.1:2468 --token "$SANDBOX_TOKEN"
sandbox-agent api sessions send-message-stream my-session --message "Hello" --endpoint http://127.0.0.1:2468 --token "$SANDBOX_TOKEN"

يمكنك أيضًا استخدام npx مثل:

npx @sandbox-agent/[email protected] --help

bunx @sandbox-agent/[email protected] --help

وثائق CLI

المفتش

قم بتصحيح الجلسات والأحداث باستخدام واجهة المفتش المدمجة (على سبيل المثال، http://localhost:2468/ui/).

وثائق المفتش

مواصفات OpenAPI

استكشف API — عرض المواصفات

نصيحة: استخراج بيانات الاعتماد

غالبًا ما تحتاج إلى استخدام رموز API الشخصية الخاصة بك لاختبار العوامل على الصناديق الرملية:

sandbox-agent credentials extract-env --export

يطبع هذا متغيرات البيئة لمفاتيح API الخاصة بـ OpenAI/Anthropic/etc لاختبارها مع حزمة Sandbox Agent SDK.

الأسئلة الشائعة

خارج النطاق

• تخزين الجلسات على القرص: الجلسات مُخزَّنة بالفعل بواسطة عوامل الترميز المعنية على القرص. من المفترض أن المستهلك يقوم ببث البيانات من هذا الجهاز إلى تخزين خارجي، مثل Postgres أو ClickHouse أو Rivet.
• أغلفة LLM مباشرة: استخدم Vercel AI SDK إذا كنت تريد تنفيذ العامل الخاص بك من الصفر.
• إدارة مستودعات Git: فقط استخدم أوامر git أو الميزات التي يوفرها مزود الصندوق الرملي الذي تختاره.
• API مزود الصندوق الرملي: لدى مزودي الصناديق الرملية العديد من الاختلافات الدقيقة في API الخاصة بهم، ولا يعقل أن نحاول توفير طبقة مخصصة. بدلاً من ذلك، نختار تقديم أدلة تسمح لك بدمج هذا المستودع مع مزودي الصناديق الرملية.

خريطة الطريق

• حزمة Python SDK
• التكوين التلقائي لـ MCP والمهارات والخطافات
• قوائم المهام