SSD Nodes Learn Hosting plans →
الأدلة Matt Connorبقلم Matt Connor · آخر تحديث في 2026-10-13

كيفية استضافة SandBase Harness ذاتياً على VPS

شغّل SandBase Harness v0.3.8 على VPS تملكه: ثبّت الإصدار المحدد، اضبط YAML للوكيل وخوادم MCP، واختر نمط العزل ووجّه Anthropic SDK إلى خادمك.

ما تحصل عليه عند استضافة بيئة تشغيل وكيل SandBase ذاتياً

تعني استضافة بيئة تشغيل وكيل SandBase ذاتياً تشغيل SandBase Harness على خادم تملكه، بحيث تبقى الجلسات وبيانات الاعتماد والذاكرة ومسارات التدقيق على قرصك بدلاً من قرص جهة أخرى. هذه خدمة Node. تستمع على 127.0.0.1:3000، وتوفّر واجهة HTTP API وفق /v1 ووحدة تحكم ويب، وتحفظ حالتها في SQLite بجوار ملفات وكيلك.

صُممت واجهة /v1 API على غرار Claude Managed Agents (CMA)، وهي واجهة API للوكلاء المُدارين المستضافين. وهذا ما يجعل بيئة التشغيل هذه مفيدة في الاتجاهين: يمكنك كتابة التعليمات البرمجية باستخدام Anthropic SDK وتوجيه baseURL فيها إلى خادمك، ثم نقل التعليمات البرمجية نفسها إلى نشر مستضاف لاحقاً.

لا تتضمن SandBase Harness نموذجاً. بل تستدعي نموذجاً. اعتباراً من 12 October 2026، تدعم OpenAI وAnthropic وMiniMax ونقاط النهاية المتوافقة مع OpenAI، بما يشمل البوابات المستضافة ذاتياً وموفّرين مثل DeepSeek V4. أُضيف MiniMax كموفّر من الدرجة الأولى في v0.3.3، مع خيار استخدام نقطة نهاية عالمية أو نقطة نهاية في mainland China. ما زلت تحتاج إلى إحضار مفتاح API، أو خادم محلي يتحدث OpenAI API.

ما تحتاج إليه قبل البدء

  • VPS يعمل بنظام Ubuntu 24.04 ويحتوي على 2 GB من ذاكرة RAM على الأقل. يُعد بناء TypeScript أثقل خطوة في عملية التثبيت.
  • Node.js بإصدار 22 أو أحدث، وnpm بإصدار 10 أو أحدث. هذان الحدّان الأدنى إلزاميان وفقاً لما يحدده المشروع.
  • git، إضافةً إلى مفتاح API لمزوّد النماذج الذي تخطط لاستخدامه.
  • Docker، ولكن فقط إذا كنت تريد بيئات sandbox للحاويات لكل جلسة.

يأتي Ubuntu 24.04 مع Node 18.19 في مستودعه الخاص، وهذا أقل من الحد الأدنى المطلوب. لذلك ثبّت Node من NodeSource بدلاً من ذلك.

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs git
node -v
npm -v

يجب أن يعرض node -v القيمة v22 أو قيمة أعلى، ويجب أن يعرض npm -v القيمة 10 أو قيمة أعلى. إذا كان node -v لا يزال يعرض v18.19.1، فهذا يعني أن حزمة التوزيعة لا تزال مثبتة وتظهر أولاً في PATH. أزلها قبل المتابعة، لأن عملية البناء تستخدم إصدار node الذي يعثر عليه shell.

ثبّت SandBase من الوسم v0.3.8

ثبّت البرنامج من وسم محدد، وليس من فرع متغير. يمنحك الاستنساخ العاري لـ main كل ما أُضيف قبل ساعة، وقد لا تتوافق معه مفاتيح الإعدادات أدناه. نُشر v0.3.8 في 30 August 2026، وهو الوسم الحالي في 12 October 2026، كما أنه الوسم الذي تحدده وثائق التثبيت الخاصة بالمشروع.

sudo install -d -o "$USER" -g "$USER" /opt/sandbase
cd /opt/sandbase
git clone --branch v0.3.8 --depth 1 https://github.com/sandbaseai/sandbase-harness.git
cd sandbase-harness
npm ci
npm run build

استخدم npm ci، وليس npm install. يثبّت ci الإصدارات الدقيقة المسجلة في ملف القفل الملتزم به، لذلك تطابق شجرة ملفاتك الشجرة التي اختبرها المشرفون على المشروع. يُسمح لـ npm install بحل الإصدارات الأحدث، وهذا ما يجعل الوسم المثبت يتوقف بصمت عن كونه مثبتاً.

أنشئ الآن مساحة عمل. مساحة العمل دليل منفصل يحتوي على ملفات الوكيل وكل حالة التشغيل. ويتيح إبقاؤها خارج نسخة المصدر المسحوبة سحب وسم أحدث دون المساس ببياناتك.

mkdir -p /opt/sandbase/workspace
cd /opt/sandbase/workspace
node /opt/sandbase/sandbase-harness/dist/index.js init
node /opt/sandbase/sandbase-harness/dist/index.js start

يكتب init دليلاً باسم .managed-agents/ داخل مساحة العمل. يشغّل start وحدة التحكم على http://127.0.0.1:3000/dashboard وواجهة API على http://127.0.0.1:3000/v1. لا يمكن الوصول إلى أي منهما من حاسوبك المحمول بعد، وهذا صحيح، وسنشرح ذلك لاحقاً. اتصل بوحدة التحكم عبر SSH في الوقت الحالي:

ssh -N -L 3000:127.0.0.1:3000 you@your-server

سيصبح مسار node .../dist/index.js الطويل مرهقاً، لذا امنحه اسماً.

alias sandbase='node /opt/sandbase/sandbase-harness/dist/index.js'

كُتبت الأوامر أدناه بصيغة sandbase <command> وفقاً لذلك.

لا تثبّته من npm

تذكر وثائق تثبيت المشروع ذلك صراحة: حزمة managed-agents غير ذات النطاق الظاهرة على npm ليست حزمة هذا المشروع. لذلك يجلب الأمران npx managed-agents وnpm install -g managed-agents شيئاً غير مرتبط ببيئة التشغيل التي تريدها. ثبّت المشروع من المصدر المعلَّم على GitHub إلى أن يعلن المشرفون عن حزمة رسمية ذات نطاق. هذه ليست ملاحظة هامشية في سجل المشروع؛ إذ يوجد الإصدار v0.3.1 أساساً لاستبدال خطوات البدء السريع القديمة عبر npm بمسار المصدر المعلَّم والمثبت.

وجّه مساحة العمل إلى مزوّد نماذج

يكتب init ‏.managed-agents/config.yaml. يُضبط مزوّد واحد لمساحة العمل بأكملها، ثم تختار الوكلاء الفرديون معرّفات النماذج المحددة.

model:
  provider: openai
  api_key: ${OPENAI_API_KEY}
storage:
  metadata:
    provider: sqlite
    options: {}
  artifacts:
    provider: local
    options:
      base_path: files

يأخذ النموذج ${OPENAI_API_KEY} القيمة من بيئة العملية، لذلك يبقى المفتاح خارج ملف الإعدادات وخارج كل نسخة احتياطية تنشئها لهذا الملف. ضعه في ملف بيئة لا يستطيع قراءته إلا root، لأن systemd يقرأ EnvironmentFile= بصفته root قبل خفض الامتيازات.

sudo install -d -m 750 /etc/sandbase
sudo touch /etc/sandbase/runtime.env
sudo chmod 600 /etc/sandbase/runtime.env

افتح ذلك الملف في محرر وأضف سطراً واحداً، OPENAI_API_KEY=sk-.... توضع مفاتيح المزوّد هنا. أما الأسرار التي يستخدمها وكيل أثناء جلسة، فتوضع بدلاً من ذلك في مخازن بيانات الاعتماد الخاصة ببيئة التشغيل. هذه مشكلة مختلفة ولها نطاق تأثير مختلف. ويستحق إبقاء الأسرار خارج وكلاء الذكاء الاصطناعي القراءة قبل لصق رمز إنتاج في أي من الموضعين.

ملف YAML للوكيل: mcp_servers والأدوات وسياسات الصلاحيات

تُعرَّف الوكلاء كملفات YAML في دليل مساحة العمل agents/. هذا هو الجزء من بيئة التشغيل الذي ستقضي فيه معظم وقتك فعلياً. تصبح المفاتيح أوضح بعد أن تكون قد كتبت حلقة وكيل صغيرة يدوياً، لأن كل مفتاح منها يضبط شيئاً كنت ستبرمجه بنفسك لولا ذلك: مطالبة النظام، وقائمة الأدوات، والفحص الذي يُجرى قبل تشغيل الأداة.

name: Incident commander
description: Triages alerts and coordinates response.
model: gpt-4o
system: |-
  You are an on-call incident commander.
mcp_servers:
  - name: sentry
    type: url
    url: https://mcp.sentry.dev/mcp
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy: { type: always_ask }
    configs:
      - name: bash
        permission_policy: { type: always_ask }
  - type: mcp_toolset
    mcp_server_name: sentry
metadata:
  template: incident-commander

حمّله وتحقق من استيراده:

sandbase reload
sandbase list
sandbase chat agent_assistant --message "hello"

يستورد reload ملف YAML الأساسي إلى SQLite. يجب أن يطبع list الوكيل مع معرّف الآن. إذا لم يعرضه list، فهذا يعني أن الملف لم يُحلَّل، وستجد سبب ذلك في .managed-agents/logs/runtime.log.

mcp_servers يعرّف نقاط نهاية MCP (بروتوكول سياق النموذج). يعني type: url أن بيئة التشغيل تتصل عبر HTTP بخادم يعمل في مكان آخر، ولذلك يمكنك استخدام أي خدمة تديرها مسبقاً، بما في ذلك خوادم MCP المستضافة على VPS نفسه الذي تعمل عليه بيئة التشغيل. عادةً ما يكون البحث على الويب أول أداة يلجأ إليها المستخدمون، ومن المفيد قراءة تمرير نسخة SearXNG الخاصة بك إلى وكيل قبل ربطها، لأن الأداة التي تعيد صفحات كتبها أشخاص مجهولون تضع نصاً غير موثوق به مباشرةً في سياق النموذج. أما الربط الأول الأبسط، فهو نقطة نهاية للقراءة فقط فوق بيانات تملكها مسبقاً. وهذا ما يتيحُه openGym بجوار متتبّع التمارين نفسه، بحيث يستطيع الوكيل الإجابة عن أسئلة تتعلق بسجل تدريبك دون أن يتمكن من إعادة كتابة أي جزء منه.

لا يؤدي تعريف الخادم إلى إتاحة أدواته للوكيل. تتولى قائمة tools ذلك من خلال إدخال mcp_toolset يطابق فيه mcp_server_name القيمة المذكورة أعلاه في name. إذا تصرف الوكيل كما لو أن أدوات MCP غير موجودة، فقارن السلسلتين حرفاً بحرف قبل أن تبحث عن السبب في أي مكان آخر.

تحتوي agent_toolset_20260401 على مجموعة الأدوات المضمّنة. اللاحقة التي تتضمن التاريخ هي إصدار للمخطط، ولذلك يحتفظ الوكيل المثبّت عليه بتعريفات الأدوات التي كُتب ليتعامل معها. تحدد default_config السياسة المطبقة على كل أداة في المجموعة، ويتجاوز كل إدخال ضمن configs هذه السياسة لأداة واحدة حسب اسمها، وهي bash في المثال.

تُظهر permission_policy القيمة التي تضيفها بيئة التشغيل مقارنةً باستدعاء نموذج مجرد. توقف always_ask الجلسة وتنتظر موافقة بشرية على الاستدعاء قبل تشغيله. وتسمح always_allow بمروره. يعني ضبط bash على always_ask أن الوكيل لا يستطيع تشغيل أمر shell من دون أن ترى الأمر الدقيق أولاً. وهذا هو الإجراء نفسه الذي ستستخدمه عند تشغيل Claude Code بأمان على VPS. إذا كنت تشغّل DeepSeek Harness أيضاً، فستتوفر عناصر التحكم نفسها هناك كإضافات بدلاً من مفاتيح YAML، وتُعد الإضافات التي تحد الميزانيات وتقيّد استدعاءات الأدوات أقرب نظير لهذه الكتلة.

أنماط العزل الأربعة ومتى يناسب كل منها

تُنفَّذ استدعاءات الأدوات التي تشغّل التعليمات البرمجية داخل بيئة عزل. يُحدَّد النظام الخلفي لكل بيئة عبر sandbox_provider في الكائن config الخاص بالبيئة، أو يُضبط كإعداد افتراضي لمساحة العمل من وحدة التحكم، ضمن Settings، في محرر Sandbox تحت Advanced. تُنشأ البيئات عبر API على العنوان POST /v1/environments.

local يشغّل التعليمات البرمجية كعملية فرعية لبيئة التشغيل على المضيف، وباسم مستخدم بيئة التشغيل نفسها. وهو الوضع الافتراضي عندما لا تحدد البيئة نظاماً خلفياً، ويكون مناسباً ما دمت المستخدم الوحيد وكان الوكيل يقرأ فقط الملفات التي تملكها. تُرفض البيئة التي تحدد نظاماً خلفياً لا يستطيع runtime تحميله، بدلاً من تشغيلها هنا بصمت. هذا الوضع لا يوفر عزلاً. فإذا حذف استدعاء أداة ملفات، فسيحذف ملفاتك، وإذا قرأ استدعاء أداة /etc/sandbase/runtime.env، فسيقرأ مفتاح المزود الخاص بك.

docker يبدأ حاوية واحدة لكل جلسة.

{
  "sandbox_provider": "docker",
  "image": "node:22-slim",
  "resources": { "memory": "1g", "cpu": 1 }
}

تحصل الجلسة على نظام ملفات خاص بها، وتُزال الحاوية عند انتهاء الجلسة. لا تُعد حدود الذاكرة ووحدة المعالجة المركزية جزءاً من هذا الوضع؛ إذ يضيف runtime --memory و--cpus إلى الحاوية فقط عندما تحدد كتلة resources الخاصة بالبيئة هذه الحدود، كما في المثال. لذلك تحصل البيئة التي لا تتضمن هذه الكتلة على حاوية بلا حد أقصى خاص بها. اترك image من دون تحديد، وسيستخدم runtime القيمة ghcr.io/sandbaseai/sandbase-harness-sandbox:latest. انتقل إلى هذا الوضع فوراً عندما يشغّل الوكيل تعليمات برمجية لم تكتبها. وتتمثل الكلفة في أن مستخدم runtime يحتاج إلى الوصول إلى Docker socket، وأن العضوية في مجموعة docker تعادل امتلاك صلاحيات root على المضيف. تشبه الحاويات الخاصة بكل جلسة بيئات العزل لوكيل مستضاف ذاتياً مع حاوية واحدة لكل تشغيل، لذلك ينطبق هنا أيضاً، من دون تغيير، تحليل الموارد التي يمكن لعملية خرجت من العزل الوصول إليها.

kubernetes يشغّل حمل الجلسة في pod ويديره باستخدام kubectl exec وkubectl cp. يجب أن تتضمن صورة runtime المكوّن kubectl، كما يجب أن يملك ServiceAccount الخاص بها صلاحيات RBAC (التحكم في الوصول المستند إلى الأدوار) لإنشاء pods وحذفها والحصول عليها وسردها ومراقبتها في namespace المستهدف، إضافة إلى المورد الفرعي exec. لا يستحق هذا الوضع عناء الإعداد إلا إذا كنت تشغّل cluster مسبقاً.

self-hosted worker يُسمّى remote في Settings وself_hosted في Environment، ولا يشغّل تعليمات الأدوات البرمجية على هذا الجهاز إطلاقاً. يضع runtime العمل في قائمة انتظار، ثم يتولى worker خارجي، بعد تزويده بعنوان URL ومفتاح API الخاصين بالـworker من Settings، العناصر الموضوعة في القائمة وينجزها خارج المضيف. يناسب هذا الوضع الحالات التي يجب أن تعمل فيها التعليمات البرمجية على جهاز لا يحتوي على مفتاح المزود الخاص بك. لا تُطبَّق حدود الموارد إلا بواسطة docker وkubernetes، لذلك تقع مسؤولية تقييد worker على مضيف worker.

لماذا يستمع runtime على 127.0.0.1؟

لأنّه يبدأ مع تعطيل المصادقة. يفعّل runtime المصادقة باستخدام bearer token عند وجود مفتاح API واحد على الأقل، لكن init الجديد لا ينشئ أي مفاتيح. إن ربطت runtime على 0.0.0.0 في هذه الحالة، فستعرّض runtime غير موثّق، ويحتوي على أدوات shell ومفتاح مزوّد الخدمة، للإنترنت العام.

لذلك، عندما تريد إتاحته، اترك عنوان الربط كما هو ونفّذ أمرين آخرين.

أولاً، فعّل المصادقة. عيّن MANAGED_AGENTS_API_KEY في ملف بيئة الخدمة، أو أنشئ مفتاحاً باستخدام POST /v1/api-keys، إذ يعرض ذلك الحقل secret_key مرة واحدة ولا يعرضه مجدداً. بعد ذلك يرسل العملاء Authorization: Bearer <key> مع كل طلب API، أو يرسلون المفتاح نفسه باعتباره x-api-key، لكن ليس كليهما في الوقت نفسه. يحمي المفتاح واجهة API، وليس وحدة التحكم: تُحمّل صفحات لوحة المعلومات وملفاتها الثابتة من دونه، وكذلك /v1/x/health و/v1/x/metrics. المفتاح الواحد يمثل هوية مشتركة واحدة. إذا كان ما تريده فعلياً هو بيئة agent معزولة ومستقلة لكل زميل، مع حفظ مفاتيح مزوّد الخدمة في بوابة واحدة، فإن OneCLI مصمم لهذا النمط.

ثانياً، ضع reverse proxy أمامه وأنهِ TLS (أمان طبقة النقل) فيه. يقدّم runtime بروتوكول HTTP عاديًا عن قصد، ويتوقع من مكوّن آخر معالجة الشهادات.

server {
    listen 443 ssl;
    server_name agents.example.com;

    ssl_certificate     /etc/letsencrypt/live/agents.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/agents.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

السطران المذكوران ليسا للزينة. يهم proxy_buffering off لأن الجلسات تُبث عبر server-sent events (SSE)، وعند تفعيل التخزين المؤقت يحتفظ nginx بالاستجابة إلى أن تمتلئ ذاكرته المؤقتة. لذلك لا تعرض وحدة التحكم شيئاً أثناء عمل agent، ثم تعرض كل المحتوى دفعة واحدة في النهاية. يهم proxy_read_timeout 3600s لأن القيمة الافتراضية هي 60 ثانية. لذلك يغلق proxy البث إذا ظل صامتاً لأكثر من دقيقة، في منتصف الدورة، ويبدو الفشل كأن runtime قد تعطل.

في جدار الحماية، افتح المنفذين 22 و443. اترك المنفذ 3000 مغلقاً، لأن proxy يصل إليه عبر loopback ولا ينبغي لأي جهة خارج الخادم الوصول إليه. وبما أن /v1/x/metrics يستجيب من دون مفتاح، أضف location = /v1/x/metrics { return 404; } إلى server block إذا كنت تفضّل عدم نشر مقاييس runtime.

وجّه Anthropic SDK إلى خادمك

توفّر بيئة التشغيل واجهة /v1 متوافقة مع CMA، لذلك يتصل بها عميل Anthropic SDK بعد تغيير حقل واحد.

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.MANAGED_AGENTS_API_KEY ?? 'local-dev-key',
  baseURL: 'http://127.0.0.1:3000'
});

كما تقبل رؤوس beta التي ترسلها عملاء Claude Managed Agents، وهما anthropic-beta: managed-agents-2026-04-01 وanthropic-beta: agent-memory-2026-07-22. يُقبل الطلب العادي الذي لا يحتوي على رأس توافق باعتباره طلباً محلياً. أما الطلب الذي يحتوي على x-api-key أو anthropic-version أو anthropic-beta، فيخضع لقواعد الخدمة المستضافة: يلزم استخدام الإصدار 2023-06-01 وميزة beta الخاصة بـ managed-agents، باستثناء أن مسارات /v1/memory_stores تحتاج إلى ميزة beta الخاصة بذاكرة الوكيل، وترفض الميزتين معاً. وُجدت هذه الرؤوس لكي تعمل الشفرة المكتوبة لنشر مستضاف هنا من دون تعديل.

التوافق قريب، لكنه غير كامل. اقرأ docs/api-matrix.md في نسخة checkout قبل افتراض وجود واجهة معينة، لأن المشروع يوثّق الفجوات الخاصة به هناك، ومنها الأدوات المخصصة من جهة العميل، التي ما زالت تحتاج إلى تسجيل مسمّى فوق بروتوكول event-result الحالي.

يعمل HTTP العادي بالقدر نفسه، وهو أسرع طريقة للتأكد من أن بيئة التشغيل تعمل:

curl -N -X POST http://127.0.0.1:3000/v1/sessions/SESSION_ID/messages \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello", "stream": true}'

الاستجابة السليمة هي تدفق من الأحداث يستمر في الوصول. إذا انقطع الاتصال، فاستأنف من آخر حدث رأيته بدلاً من إعادة تنفيذ الدورة كاملة:

curl -N http://127.0.0.1:3000/v1/sessions/SESSION_ID/events/stream \
  -H "Last-Event-ID: EVENT_ID"

هذا التدفق القابل للاستئناف هو سبب استمرار الجلسة بعد إغلاق الحاسوب المحمول. تُحفَظ الأحداث على الخادم، لذلك يعيد العميل تشغيل سجل بدلاً من الاحتفاظ بالنسخة الوحيدة منه.

مكان حفظ بيانات الاعتماد والذاكرة ومسارات التدقيق على القرص

كل ما يملكه runtime موجود ضمن .managed-agents/ في مساحة العمل.

.managed-agents/
├── config.yaml
├── data.db
├── logs/runtime.log
├── files/
├── skills/
├── snapshots/
└── sandbox/
  • يحتوي data.db على بيانات SQLite الوصفية: الوكلاء والجلسات وإدخالات مخزن بيانات الاعتماد وإدخالات مخزن الذاكرة ومفاتيح API.
  • يحتوي files/ على وحدات بايت الملفات المحمّلة، بينما يحتوي skills/ على حزم المهارات المحمّلة.
  • يحتوي snapshots/ على لقطات مساحة عمل الجلسات، بينما يحتوي sandbox/ على أدلة العمل الخاصة بالجلسات التي تعمل في الوضع المحلي.
  • يمثّل logs/runtime.log أول مكان ينبغي التحقق منه عندما لا يحدث شيء بصمت.

مخازن بيانات الاعتماد هي مجموعات من الأسرار. تضيف كل مجموعة باستخدام auth_type مثل environment_variable، ثم تربطها بجلسة عبر vault_ids عند إنشاء الجلسة. تحتوي مخازن الذاكرة على إدخالات مسماة تثبّتها في جلسة بصفتها memory_store، مع إعداد وصول وتعليمات خاصين بها. يوجد كلا النوعين ضمن data.db. وهذا هو الفرق تحديداً بين runtime واستدعاء نموذج خام: إذ يتذكر runtime المعلومات بين الجلسات، ويسجل ما حدث.

بما أنها موجودة في دليل واحد، انسخها احتياطياً كوحدة واحدة.

sudo systemctl stop sandbase
sudo tar czf /root/sandbase-$(date +%F).tgz -C /opt/sandbase/workspace .managed-agents
sudo systemctl start sandbase

أوقف الخدمة أولاً. قد يؤدي نسخ قاعدة بيانات SQLite أثناء كتابة runtime إليها إلى التقاط ملف لا يمكن فتحه عند الاستعادة، وقد تكتشف ذلك في اليوم الذي تحتاج فيه إلى النسخة الاحتياطية. إذا كنت تفضّل إبقاء YAML الخاص بالوكلاء في git وحالة runtime في موقع آخر، فإن وثيقة النشر تدعم تثبيت موقع الحالة باستخدام --data-dir على start.

الاستعادة هي العملية العكسية: افحص نفس الوسم على خادم جديد، وفك الأرشيف داخل مساحة العمل، ثم ابدأ الخدمة. لن يكون مفتاح المزوّد موجوداً في الأرشيف إذا استخدمت صيغة ${OPENAI_API_KEY}، لذلك احتفظ به في مكان يمكنك الوصول إليه لاحقاً.

شغّله عبر systemd

امنح بيئة التشغيل مستخدماً خاصاً بها، حتى لا يتمكن استدعاء أداة في وضع الحماية المحلي من التصرف بصلاحياتك.

sudo adduser --system --group --no-create-home --home /opt/sandbase sandbase
sudo chown -R sandbase:sandbase /opt/sandbase

احفظ هذا في /etc/systemd/system/sandbase.service.

[Unit]
Description=SandBase Harness runtime
After=network-online.target

[Service]
User=sandbase
Group=sandbase
WorkingDirectory=/opt/sandbase/workspace
EnvironmentFile=/etc/sandbase/runtime.env
ExecStart=/usr/bin/node /opt/sandbase/sandbase-harness/dist/index.js start --host 127.0.0.1 --port 3000
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

يستدعي مثال النشر الخاص بالمشروع ملفاً تنفيذياً باسم managed-agents على PATH. لا ينشئ التثبيت من مصدر موسوم هذا الملف، لذلك يشغّل ExecStart الأمر node على نقطة الدخول المبنية بدلاً من ذلك.

sudo systemctl daemon-reload
sudo systemctl enable --now sandbase
sudo systemctl status sandbase
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/dashboard

النتيجة السليمة هي active (running) من status و200 من curl. في أي حالة أخرى، اقرأ journalctl -u sandbase -n 50 أولاً ثم .managed-agents/logs/runtime.log. يمثّل enable --now الجزء المهم، لأن العملية التي شغّلتها يدوياً تختفي بعد إعادة التشغيل التالية.

ما الذي قد يتعطل، والرسالة التي ستظهر لك

npm run build يتوقف دون ظهور خطأ من npm. في VPS بسعة 1 GB، يوقف kernel عملية ترجمة TypeScript بسبب نفاد الذاكرة. ويسجل kernel ذلك في سجل kernel بدلاً من إرساله إلى npm. تحقق من ذلك باستخدام journalctl -k | grep -i "out of memory"، الذي يطبع سطراً يتضمن اسم عملية node التي أوقفها kernel. أضف swap، أو نفّذ عملية البناء على instance أكبر ثم انسخ dist/ إليه.

Error: listen EADDRINUSE: address already in use 127.0.0.1:3000. توجد عملية أخرى تستخدم المنفذ. يحدد sudo ss -lntp | grep 3000 هذه العملية. أوقفها، أو شغّل runtime باستخدام --port 3001 وحدّث proxy.

لا تُحمّل لوحة المعلومات من حاسوبك المحمول. هذا السلوك مقصود، لأن runtime يستمع على loopback. استخدم نفق SSH المذكور أعلاه، أو أكمل إعداد reverse proxy. لا تصلح ذلك باستخدام --host 0.0.0.0، لأن المصادقة تظل معطّلة إلى أن يوجد مفتاح.

تفشل sandboxes الخاصة بـDocker مع permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock. المستخدم sandbase ليس عضواً في المجموعة docker. أصلح ذلك باستخدام sudo usermod -aG docker sandbase ثم أعد تشغيل الخدمة. افهم ما منحته من صلاحيات: هذه المجموعة تملك صلاحيات root على المضيف، ولذلك تلغي جزءاً من سبب منح runtime مستخدماً مستقلاً.

تفشل sandboxes الخاصة بـKubernetes مع Error from server (Forbidden). يفتقد ServiceAccount صلاحيات pod أو المورد الفرعي exec. تحقق من ذلك مباشرة باستخدام kubectl auth can-i create pods/exec -n <namespace>، الذي يعرض yes أو no.

تعيد طلبات API الحالة 401 بعد إضافة API key. تُفعّل المصادقة عند وجود أول مفتاح، وهي تغطي API وليس console: تظل صفحات لوحة المعلومات وملفاتها الثابتة متاحة للعامة، لذلك تواصل console التحميل ثم تحتاج إلى المفتاح في طلبات API الخاصة بها. أرسل Authorization: Bearer <key> أو x-api-key: <key>، وليس كليهما، لأن الطلب الذي يحتوي على كلا الرأسين يُرفض بالحالة 401 حتى عند تعطيل المصادقة. إذا فقدت المفتاح، فأنشئ مفتاحاً آخر، لأن secret_key يُعرض مرة واحدة ويُخزّن كقيمة hash فقط.

لا تظهر أدوات خادم MCP في الجلسة مطلقاً. قارن mcp_server_name في كتلة tools مع name في mcp_servers، ثم تحقق من قدرة runtime على الوصول إلى URL من الخادم نفسه باستخدام curl -i <url>. خادم MCP من نوع URL هو تبعية شبكية، كما أن VPS يحل أسماء النطاقات ويوجّه حركة الشبكة بطريقة تختلف عن حاسوبك المحمول.

FAQ

هل يمكنني تشغيل SandBase Harness من دون مفتاح OpenAI أو Anthropic؟

نعم، باستخدام مفتاح MiniMax أو نقطة نهاية متوافقة مع OpenAI. يدعم وقت التشغيل موفّري OpenAI وAnthropic وMiniMax والموفّرين المتوافقين مع OpenAI، لذلك يعمل خادم محلي يتحدث باستخدام OpenAI API. اضبط موفّر مساحة العمل في .managed-agents/config.yaml، ووجّه api_key ونقطة النهاية إليه. لا يتضمن وقت التشغيل نموذجاً خاصاً به، لذلك يجب أن يستجيب شيء ما للطلبات.

هل من الآمن كشف وقت التشغيل على منفذ عام؟

ليس بالإعداد المثبّت. فهو يرتبط بـ127.0.0.1:3000 ويبدأ مع تعطيل المصادقة، والحل ليس استخدام عنوان ارتباط مختلف. أنشئ مفتاح API أو اضبط MANAGED_AGENTS_API_KEY لتفعيل مصادقة bearer token لواجهة API. ثم ضع nginx أو Caddy أمامه لتوفير TLS، وأبقِ المنفذ 3000 مغلقاً في جدار الحماية بحيث يكون المسار الوحيد للدخول عبر الـproxy.

ما الفرق بين sandbox المحلي وDocker وKubernetes؟

يشغّل local كود الأدوات كعملية فرعية لوقت التشغيل على المضيف، باستخدام أذونات مستخدم وقت التشغيل ومن دون عزل. ينشئ docker حاوية ونظام ملفات خاصين بكل جلسة ويحذفهما عند انتهاء الجلسة، ولا يفرض حدوداً على الذاكرة ووحدة المعالجة المركزية إلا إذا حدّد قسم resources في البيئة هذه الحدود. يشغّل kubernetes الجلسة على هيئة pod ويديرها باستخدام kubectl exec، الذي يتطلب kubectl داخل صورة وقت التشغيل، وRBAC على pods، إضافة إلى المورد الفرعي exec في مساحة الأسماء المستهدفة. يوجد backend رابع، وهو العامل المستضاف ذاتياً، يضع العمل في قائمة انتظار لعامل خارجي، بحيث يُشغَّل الكود خارج المضيف.

ما الذي أحتاج إلى نسخه احتياطياً تحديداً؟

دليل .managed-agents/ الموجود في مساحة العمل. يحتوي هذا الدليل على config.yaml، وهي قاعدة بيانات SQLite في data.db التي تضم الوكلاء والجلسات وإدخالات مخزن بيانات الاعتماد وإدخالات الذاكرة، إضافة إلى الملفات المرفوعة وحزم المهارات ولقطات الجلسات. أوقف الخدمة قبل نسخ الدليل حتى لا تُكتب قاعدة بيانات SQLite أثناء إنشاء الأرشيف. مفاتيح API الخاصة بالموفّرين المشار إليها باسم ${OPENAI_API_KEY} ليست ضمن النسخة الاحتياطية، لذلك خزّنها بشكل منفصل.

لماذا أستنسخ الوسم v0.3.8 بدلاً من main؟

الوسم يمثل شجرة ثابتة، لذلك تكون مفاتيح الإعداد وأوامر CLI التي تقرأ عنها هي نفسها التي تحصل عليها فعلياً. يتحرك main، وقد يُعاد تسمية مفتاح إعداد بين وقت كتابة الدليل ووقت تشغيلك له. ويحذّر المشروع أيضاً من أن الحزمة غير المقيّدة managed-agents على npm ليست هذا المشروع، لذلك يثبّت npx managed-agents شيئاً غير ذي صلة. يوجد الإصدار v0.3.1 أساساً لاستبدال البدء السريع عبر npm بمسار المصدر المعلَّم والمثبّت.

هل كان هذا المقال مفيدًا؟