SSD Nodes Learn Hosting plans →
راهنماها Matt Connorتوسط Matt Connor · به‌روزرسانی شده 2026-10-15

آموزش میزبانی شخصی SandBase Harness روی سرور اختصاصی

راهنمای کامل اجرای SandBase Harness v0.3.8 روی VPS شخصی. شامل نصب تگ‌دار، تنظیم agent YAML، پیکربندی سرورهای MCP، حالت‌های sandbox و اتصال Anthropic SDK به سرور شما.

مزایای میزبانی شخصی (self-host) محیط اجرای SandBase agent

میزبانی شخصی محیط اجرای SandBase agent به معنای اجرای SandBase Harness روی سروری است که مالکیت آن با شماست؛ بنابراین نشست‌ها (sessions)، اعتبارنامه‌ها، حافظه و گزارش‌های حسابرسی (audit trails) به‌جای ذخیره در سرورهای دیگر، روی دیسک شما باقی می‌مانند. این یک سرویس Node است. این سرویس روی 127.0.0.1:3000 گوش می‌دهد، یک /v1 HTTP API و کنسول وب ارائه می‌دهد و وضعیت خود را در یک فایل SQLite در کنار فایل‌های agent شما ذخیره می‌کند.

رابط /v1 API بر اساس Claude Managed Agents (CMA) طراحی شده است که همان API مدیریت‌شدهٔ میزبانی‌شده است. همین موضوع باعث می‌شود این محیط اجرا در هر دو جهت جذاب باشد: شما می‌توانید کد خود را با استفاده از Anthropic SDK بنویسید و baseURL آن را به سمت سرور شخصی خود هدایت کنید، و سپس بعداً همان کد را به یک محیط میزبانی‌شده منتقل کنید.

SandBase Harness همراه با هیچ مدلی عرضه نمی‌شود. این برنامه مدل‌ها را فراخوانی می‌کند. تا تاریخ 12 اکتبر 2026، این برنامه از OpenAI، Anthropic، MiniMax و endpointهای سازگار با OpenAI پشتیبانی می‌کند که شامل gatewayهای میزبانی‌شده توسط کاربر و ارائه‌دهندگانی مانند DeepSeek V4 می‌شود. MiniMax در نسخه v0.3.3 به‌عنوان یک ارائه‌دهنده سطح اول با قابلیت انتخاب بین endpoint جهانی یا endpoint سرزمین اصلی چین اضافه شد. شما همچنان باید API key خود را ارائه دهید یا از یک سرور محلی که از پروتکل OpenAI API پشتیبانی می‌کند، استفاده کنید.

پیش‌نیازهای شروع کار

  • یک سرور مجازی (VPS) با سیستم‌عامل Ubuntu 24.04 و حداقل 2 GB رم. مرحله build پروژه TypeScript سنگین‌ترین بخش نصب است.
  • نسخه Node.js 22 یا جدیدتر و npm 10 یا جدیدتر. این‌ها حداقل‌های الزامی اعلام‌شده توسط پروژه هستند.
  • git، به همراه یک API key برای مدل ارائه‌دهنده‌ای که قصد استفاده از آن را دارید.
  • Docker، تنها در صورتی که به sandboxهای کانتینری برای هر نشست (session) نیاز دارید.

سیستم‌عامل 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 اولویت دارد. پیش از ادامه، آن را حذف کنید، زیرا فرآیند build با هر نسخه‌ای از node که shell پیدا کند، اجرا می‌شود.

نصب SandBase از تگ v0.3.8

نصب را از طریق یک تگ انجام دهید، نه از یک شاخه (branch) در حال تغییر. یک clone ساده از 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 دقیقاً همان نسخه‌های ثبت‌شده در فایل lockfile را نصب می‌کند، بنابراین درخت فایل‌های شما با درختی که توسعه‌دهندگان تست کرده‌اند مطابقت خواهد داشت. دستور npm install اجازه دارد نسخه‌های جدیدتر را جایگزین کند، که این دقیقاً همان روشی است که باعث می‌شود یک تگ ثابت، به‌طور ناخواسته تغییر کند.

اکنون یک workspace ایجاد کنید. این workspace یک دایرکتوری مجزا است که فایل‌های agent و تمام وضعیت‌های runtime شما را نگه می‌دارد؛ نگهداری آن خارج از دایرکتوری source باعث می‌شود بتوانید بدون دست زدن به داده‌های خود، تگ جدیدتری را pull کنید.

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/ در داخل workspace می‌سازد. دستور 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 چیزی غیرمرتبط با runtime مورد نظر شما را دریافت می‌کنند. تا زمانی که نگهدارندگان پروژه یک پکیج رسمی و اسکوپ‌دار معرفی نکرده‌اند، نصب را از طریق سورس تگ‌شده در GitHub انجام دهید. این موضوع یک یادداشت کوچک در تاریخچه پروژه نیست: نسخه v0.3.1 عمدتاً با این هدف منتشر شد که راهنمای قدیمی quick start در 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= را پیش از کاهش سطح دسترسی (drop privileges) با کاربر 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-... به آن اضافه کنید. کلیدهای ارائه‌دهنده متعلق به این بخش هستند. اسراری که یک ایجنت در طول یک نشست استفاده می‌کند، باید در vaultهای اعتبارسنجی runtime قرار بگیرند که مسئله‌ای متفاوت با شعاع انفجار (blast radius) متفاوت است؛ مطالعه مطلب دور نگه داشتن اسرار از ایجنت‌های هوش مصنوعی پیش از آنکه یک توکن عملیاتی (production) را در هر یک از این دو مکان قرار دهید، توصیه می‌شود.

فایل YAML عامل: mcp_servers، ابزارها و سیاست‌های دسترسی

عامل‌ها به عنوان فایل‌های YAML در دایرکتوری agents/ فضای کاری تعریف می‌شوند. این بخشی از runtime است که در عمل زمان زیادی را صرف آن خواهید کرد. کلیدها پس از آنکه یک حلقه عامل کوچک را با دست نوشتید، خواناتر می‌شوند؛ زیرا هر کلید در واقع دستگیره‌ای برای چیزی است که در غیر این صورت باید خودتان کدنویسی می‌کردید: پرامپت سیستم، لیست ابزارها و بررسی‌هایی که پیش از اجرای یک ابزار انجام می‌شود.

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 اکنون باید عامل را همراه با یک ID نمایش دهد. اگر list آن را نشان نمی‌دهد، فایل تجزیه (parse) نشده است و .managed-agents/logs/runtime.log جایی است که دلیل آن نوشته شده است.

mcp_servers نقاط پایانی MCP (model context protocol) را تعریف می‌کند. type: url یعنی runtime از طریق HTTP با سروری ارتباط دارد که در مکان دیگری اجرا می‌شود؛ بنابراین هر چیزی را که از قبل اجرا می‌کنید می‌توان در اینجا نیز استفاده کرد، از جمله سرورهای MCP میزبانی‌شده روی همان VPS که runtime روی آن اجرا می‌شود. جست‌وجوی وب معمولاً نخستین ابزاری است که افراد به سراغ آن می‌روند، اما پیش از راه‌اندازی چنین ابزاری، مطالعهٔ اختصاص دادن نمونهٔ SearXNG خودتان به یک agent ارزش دارد؛ زیرا ابزاری که صفحاتی نوشته‌شده توسط افراد ناشناس را برمی‌گرداند، متن غیرقابل‌اعتماد را مستقیماً وارد context مدل می‌کند. گزینهٔ ساده‌تر برای شروع، ساختاری معکوس دارد: یک endpoint فقط‌خواندنی روی داده‌هایی که مالک آن‌ها هستید. همین کاری است که openGym در کنار خود workout tracker ارائه می‌کند؛ بنابراین agent می‌تواند دربارهٔ سابقهٔ تمرین شما پاسخ دهد، بدون آن‌که بتواند هیچ بخشی از آن را بازنویسی کند.

اعلام یک سرور، ابزارهای آن را به عامل نمی‌دهد. لیست tools این کار را از طریق ورودی mcp_toolset انجام می‌دهد که mcp_server_name آن با name در بالا مطابقت دارد. اگر عامل طوری رفتار می‌کند که انگار ابزارهای MCP وجود ندارند، پیش از جستجو در هر جای دیگر، آن دو رشته را کاراکتر به کاراکتر با هم مقایسه کنید.

agent_toolset_20260401 مجموعه ابزارهای داخلی است. پسوند تاریخ‌دار، نسخه طرح‌واره (schema) است، بنابراین عاملی که به آن متصل شده، تعاریف ابزاری را که برای آن نوشته شده است حفظ می‌کند. default_config سیاست را برای تمام ابزارهای موجود در مجموعه تعیین می‌کند و هر ورودی در زیر configs، یک ابزار را بر اساس نام بازنویسی می‌کند، مانند bash در مثال.

permission_policy جایی است که یک runtime برتری خود را نسبت به فراخوانی مستقیم مدل ثابت می‌کند. always_ask نشست را متوقف کرده و منتظر می‌ماند تا یک انسان پیش از اجرا، فراخوانی را تأیید کند. always_allow اجازه عبور به آن می‌دهد. تنظیم bash روی always_ask به این معنی است که عامل نمی‌تواند یک دستور shell را بدون اینکه ابتدا دستور دقیق را ببینید اجرا کند؛ این همان کنترلی است که هنگام اجرای ایمن Claude Code روی یک VPS به دنبال آن خواهید بود. اگر از DeepSeek Harness نیز استفاده می‌کنید، همان کنترل‌ها به جای کلیدهای YAML به عنوان افزونه (add-on) ارائه می‌شوند و پلاگین‌هایی که بودجه را محدود کرده و فراخوانی ابزارها را کنترل می‌کنند، نزدیک‌ترین معادل برای این بلوک هستند.

چهار حالت sandbox و موارد استفاده از هر کدام

فراخوانی‌های ابزاری که کد اجرا می‌کنند، درون یک sandbox انجام می‌شوند. backend برای هر محیط از طریق sandbox_provider در شیء config محیط انتخاب می‌شود، یا به‌عنوان پیش‌فرض workspace در کنسول، بخش Settings، زیربخش Sandbox editor و قسمت Advanced تنظیم می‌گردد. محیط‌ها از طریق API در POST /v1/environments ایجاد می‌شوند.

حالت local کد را به‌عنوان یک child process از runtime، روی میزبان و با کاربر خودِ runtime اجرا می‌کند. این حالت پیش‌فرض در زمانی است که محیط هیچ backendای را مشخص نکند، و زمانی که شما تنها کاربر هستید و agent فقط فایل‌های متعلق به شما را می‌خواند، منطقی است. محیطی که backendای را نام ببرد که runtime قادر به بارگذاری آن نیست، به‌جای اجرای بی‌سروصدا در اینجا، رد می‌شود. این حالت ایزولاسیون نیست. فراخوانی ابزاری که فایل‌ها را حذف می‌کند، فایل‌های شما را حذف خواهد کرد و فراخوانی ابزاری که /etc/sandbase/runtime.env را می‌خواند، کلید provider شما را می‌خواند.

حالت docker به ازای هر session یک container را شروع می‌کند.

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

این session فایل‌سیستم اختصاصی خود را دارد و container همراه با session حذف می‌شود. محدودیت‌های حافظه و CPU بخشی از این حالت نیستند: runtime تنها زمانی --memory و --cpus را به container اضافه می‌کند که بلوک resources محیط آن‌ها را تنظیم کرده باشد (مانند مثال)، بنابراین محیطی بدون آن بلوک، containerای بدون سقف اختصاصی دریافت می‌کند. اگر image را حذف کنید، runtime از ghcr.io/sandbaseai/sandbase-harness-sandbox:latest استفاده می‌کند. لحظه‌ای که agent کدی را اجرا می‌کند که شما ننوشته‌اید، به این حالت سوییچ کنید. هزینه این کار این است که کاربرِ runtime به Docker socket نیاز دارد و عضویت در گروه docker معادل دسترسی root روی میزبان است. containerهای هر session مشابه sandboxهای agent خودمیزبان با یک container در هر اجرا هستند، بنابراین استدلال درباره آنچه یک پردازش فرار کرده می‌تواند به آن دسترسی داشته باشد، در اینجا نیز بدون تغییر صدق می‌کند.

حالت kubernetes بار کاری session را به‌عنوان یک pod اجرا کرده و آن را با kubectl exec و kubectl cp هدایت می‌کند. image مربوط به runtime باید kubectl را داشته باشد و ServiceAccount آن باید مجوز RBAC (کنترل دسترسی مبتنی بر نقش) برای ایجاد، حذف، دریافت، لیست کردن و نظارت بر podها در namespace هدف، به‌علاوه زیرمنبع exec را داشته باشد. این حالت تنها در صورتی ارزش راه‌اندازی دارد که از قبل یک cluster داشته باشید.

حالت self-hosted worker در Settings با نام remote و در Environment با نام self_hosted شناخته می‌شود و کد ابزار را اصلاً روی این دستگاه اجرا نمی‌کند. runtime کار را در یک صف قرار می‌دهد و یک worker خارجی، با دریافت URL و کلید API مربوط به worker از Settings، موارد صف‌بندی‌شده را خارج از میزبان دریافت و تکمیل می‌کند. این حالت زمانی مناسب است که کد باید روی ماشینی اجرا شود که کلید provider شما را ندارد. محدودیت‌های منابع تنها توسط docker و kubernetes رعایت می‌شوند، بنابراین محدود کردن worker وظیفه میزبانِ worker است.

چرا runtime به 127.0.0.1 متصل (bind) شده است؟

زیرا این سرویس در ابتدا بدون احراز هویت شروع به کار می‌کند. runtime زمانی احراز هویت با bearer-token را فعال می‌کند که حداقل یک API key وجود داشته باشد، اما یک init تازه، هیچ کلیدی ایجاد نمی‌کند. اتصال به 0.0.0.0 با تنظیمات پیش‌فرض، باعث می‌شود یک agent runtime بدون احراز هویت که به ابزارهای shell و کلید provider شما دسترسی دارد، در معرض اینترنت عمومی قرار بگیرد.

بنابراین، زمانی که می‌خواهید این سرویس در دسترس باشد، آدرس bind را تغییر ندهید و دو کار دیگر انجام دهید.

نخست، احراز هویت را فعال کنید. مقدار MANAGED_AGENTS_API_KEY را در فایل environment سرویس تنظیم کنید یا با استفاده از POST /v1/api-keys یک کلید بسازید؛ این دستور یک بار فیلد secret_key را نمایش می‌دهد و دیگر هرگز آن را نشان نخواهد داد. کلاینت‌ها سپس باید در هر درخواست API، مقدار Authorization: Bearer <key> را ارسال کنند یا همان کلید را به عنوان x-api-key بفرستند، اما هرگز نباید هر دو را هم‌زمان ارسال کنند. این کلید از API محافظت می‌کند، نه از کنسول: صفحات داشبورد و فایل‌های استاتیک آن بدون کلید بارگذاری می‌شوند، همان‌طور که /v1/x/health و /v1/x/metrics نیز بدون کلید کار می‌کنند. هر کلید یک هویت مشترک است، بنابراین اگر به دنبال یک agent ایزوله (sandboxed) برای هر یک از اعضای تیم هستید که کلیدهای provider در یک gateway واحد نگهداری شوند، OneCLI برای این ساختار طراحی شده است.

دوم، یک reverse proxy در مقابل آن قرار دهید و TLS (امنیت لایه انتقال) را در آنجا خاتمه دهید (terminate کنید). 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) جریان می‌یابند و با فعال بودن buffering، nginx پاسخ را تا پر شدن بافر نگه می‌دارد؛ در نتیجه کنسول در حین کار agent چیزی نشان نمی‌دهد و در پایان همه خروجی‌ها را یک‌جا تخلیه می‌کند. proxy_read_timeout 3600s اهمیت دارد زیرا مقدار پیش‌فرض 60 ثانیه است؛ بنابراین اگر جریانی بیش از یک دقیقه ساکت بماند، توسط proxy در میانه کار بسته می‌شود و این خطا به شکل crash کردن runtime دیده می‌شود.

در فایروال، پورت‌های 22 و 443 را باز کنید. پورت 3000 را بسته نگه دارید، زیرا proxy از طریق loopback به آن دسترسی دارد و هیچ منبعی خارج از سرور نباید به آن متصل شود. از آنجا که /v1/x/metrics بدون کلید پاسخ می‌دهد، اگر نمی‌خواهید متریک‌های runtime منتشر شوند، location = /v1/x/metrics { return 404; } را به بلوک server اضافه کنید.

اشاره کردن Anthropic SDK به سرور شخصی خود

محیط اجرا یک سطح به شکل CMA در /v1 پیاده‌سازی می‌کند، بنابراین کلاینت 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'
});

این محیط همچنین هدرهای بتا که کلاینت‌های Claude Managed Agents ارسال می‌کنند، یعنی anthropic-beta: managed-agents-2026-04-01 و anthropic-beta: agent-memory-2026-07-22 را می‌پذیرد. یک درخواست ساده بدون هدر سازگاری، به‌عنوان یک فراخوان محلی (local caller) پذیرفته می‌شود. درخواستی که دارای x-api-key، anthropic-version یا anthropic-beta باشد، تابع قوانین نسخه میزبانی‌شده (hosted) است: نسخه 2023-06-01 و بتای managed-agents الزامی هستند، با این استثنا که مسیرهای /v1/memory_stores به بتای agent-memory نیاز دارند و ترکیب این دو را رد می‌کنند. این هدرها وجود دارند تا کدی که برای یک استقرار میزبانی‌شده نوشته شده است، در اینجا بدون تغییر اجرا شود.

سازگاری نزدیک است، اما کامل نیست. پیش از آنکه فرض کنید سطحی وجود دارد، docs/api-matrix.md را در checkout مطالعه کنید، زیرا پروژه شکاف‌های خود را در آنجا مستند کرده است؛ از جمله ابزارهای سفارشی سمت کلاینت که همچنان به ثبت نامی (named registration) فراتر از پروتکل فعلی 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"

دلیل اینکه یک نشست پس از بستن لپ‌تاپ زنده می‌ماند، همین جریان قابل‌ادامه (resumable stream) است. رویدادها روی سرور ذخیره می‌شوند، بنابراین کلاینت به‌جای نگهداری تنها نسخه موجود، در حال بازخوانی یک لاگ است.

محل ذخیره‌سازی اعتبارنامه‌ها، حافظه و لاگ‌های حسابرسی روی دیسک

هر آنچه که runtime مالکیت آن را بر عهده دارد، در مسیر .managed-agents/ در فضای کاری قرار گرفته است.

.managed-agents/
├── config.yaml
├── data.db
├── logs/runtime.log
├── files/
├── skills/
├── snapshots/
└── sandbox/
  • data.db شامل متادیتای SQLite است: ایجنت‌ها، نشست‌ها، ورودی‌های vault اعتبارنامه‌ها، ورودی‌های حافظه و کلیدهای API.
  • files/ فایل‌های آپلود شده را نگه می‌دارد و skills/ بسته‌های skill آپلود شده را در خود جای می‌دهد.
  • snapshots/ اسنپ‌شات‌های فضای کاری نشست‌ها را نگه می‌دارد و sandbox/ دایرکتوری‌های کاری نشست‌های local-mode را در خود دارد.
  • logs/runtime.log اولین جایی است که باید هنگام بروز رفتاری که در آن چیزی بدون هیچ خروجی یا خطایی کار نمی‌کند، بررسی کنید.

Credential vaultها گروه‌هایی از اسرار هستند که هر کدام با یک auth_type مانند environment_variable اضافه شده و هنگام ایجاد نشست، از طریق vault_ids به آن نشست متصل می‌شوند. Memory storeها ورودی‌های نام‌گذاری‌شده‌ای را نگه می‌دارند که شما آن‌ها را به عنوان یک memory_store با تنظیمات دسترسی و دستورالعمل‌های خاص خود، در یک نشست mount می‌کنید. هر دوی این‌ها در data.db قرار دارند، که دقیقاً تفاوت اصلی این سیستم با یک فراخوانی خام مدل است: 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 و وضعیت (state) را در جای دیگری نگه دارید، مستندات deployment از تعیین محل ذخیره وضعیت با استفاده از --data-dir در start پشتیبانی می‌کند.

بازیابی برعکس این فرآیند است: همان تگ را روی یک سیستم تازه checkout کنید، آرشیو را در فضای کاری باز کنید و سرویس را استارت بزنید. اگر از فرم ${OPENAI_API_KEY} استفاده کرده باشید، کلید provider شما در آرشیو نیست، بنابراین آن را در جایی نگه دارید که همیشه به آن دسترسی داشته باشید.

اجرای آن تحت systemd

برای محیط runtime یک کاربر اختصاصی ایجاد کنید تا فراخوانی ابزار در حالت sandbox محلی، نتواند با دسترسی‌های شما عمل کند.

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

نمونه deployment خود پروژه، یک باینری managed-agents را در مسیر PATH فراخوانی می‌کند. نصب از طریق tagged-source چنین فایلی ایجاد نمی‌کند، بنابراین ExecStart دستور node را روی نقطه ورود (entry point) ساخته‌شده اجرا می‌کند.

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 بخشی است که اهمیت دارد، زیرا فرآیندی که به‌صورت دستی اجرا شده باشد، پس از reboot بعدی از بین می‌رود.

چه چیزی از کار می‌افتد و پیامی که مشاهده خواهید کرد

npm run build بدون هیچ خطایی از سمت npm متوقف می‌شود. در یک VPS با 1 گیگابایت رم، فرآیند کامپایل TypeScript توسط قابلیت out-of-memory killer در هسته متوقف می‌شود؛ این قابلیت گزارش را به لاگ هسته می‌فرستد، نه به npm. این موضوع را با journalctl -k | grep -i "out of memory" تأیید کنید که خطی را چاپ می‌کند که نام فرآیند node کشته‌شده را نشان می‌دهد. فضای swap اضافه کنید یا build را روی یک نمونه بزرگ‌تر انجام داده و dist/ را منتقل کنید.

Error: listen EADDRINUSE: address already in use 127.0.0.1:3000. فرآیند دیگری در حال حاضر از پورت استفاده می‌کند. sudo ss -lntp | grep 3000 نام آن را مشخص می‌کند. یا آن فرآیند را متوقف کنید یا runtime را با --port 3001 اجرا کرده و پروکسی را به‌روزرسانی کنید.

داشبورد از روی لپ‌تاپ شما بارگذاری نمی‌شود. این رفتار مورد انتظار است، زیرا runtime به loopback متصل می‌شود. از تونل SSH که در بالا ذکر شد استفاده کنید یا reverse proxy را تکمیل کنید. آن را با --host 0.0.0.0 تعمیر نکنید، زیرا تا زمانی که کلیدی وجود نداشته باشد، احراز هویت غیرفعال است.

سندباکس‌های 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 برطرف کرده و سرویس را ری‌استارت کنید. توجه داشته باشید که چه دسترسی‌ای داده‌اید: این گروه در میزبان (host) دسترسی root دارد، بنابراین بخشی از دلیلی که باعث شد برای runtime یک کاربر مجزا تعریف کنید، خنثی می‌شود.

سندباکس‌های Kubernetes با Error from server (Forbidden) شکست می‌خورند. حساب کاربری ServiceAccount فاقد مجوزهای pod یا زیرمنبع exec است. آن را مستقیماً با kubectl auth can-i create pods/exec -n <namespace> بررسی کنید که پاسخ yes یا no را می‌دهد.

درخواست‌های API پس از افزودن کلید API، خطای 401 برمی‌گردانند. احراز هویت با ایجاد اولین کلید فعال می‌شود و API را پوشش می‌دهد، اما کنسول را نه: صفحات داشبورد و دارایی‌های استاتیک آن‌ها عمومی باقی می‌مانند، بنابراین کنسول بارگذاری می‌شود اما برای فراخوانی‌های API خود به کلید نیاز دارد. یا Authorization: Bearer <key> یا x-api-key: <key> را ارسال کنید، نه هر دو را؛ زیرا درخواستی که هر دو هدر را داشته باشد، حتی در صورت غیرفعال بودن احراز هویت، با خطای 401 رد می‌شود. اگر کلید را گم کرده‌اید، کلید دیگری بسازید، زیرا secret_key فقط یک بار نمایش داده می‌شود و تنها به صورت هش ذخیره می‌گردد.

ابزارهای یک سرور MCP هرگز در نشست (session) ظاهر نمی‌شوند. مقدار mcp_server_name در بلوک tools را با name در mcp_servers مقایسه کنید، سپس بررسی کنید که آیا runtime می‌تواند از خودِ سرور با استفاده از curl -i <url> به آن URL دسترسی داشته باشد یا خیر. یک سرور MCP از نوع URL یک وابستگی شبکه است و یک VPS نام‌ها را متفاوت از لپ‌تاپ شما تحلیل (resolve) کرده و ترافیک را متفاوت مسیریابی می‌کند.

FAQ

آیا می‌توانم SandBase Harness را بدون کلید OpenAI یا Anthropic اجرا کنم؟

بله، با استفاده از کلید MiniMax یا یک endpoint سازگار با OpenAI. این runtime از ارائه‌دهندگان OpenAI، Anthropic، MiniMax و هر ارائه‌دهنده‌ای که با API استاندارد OpenAI سازگار باشد پشتیبانی می‌کند؛ بنابراین یک سرور محلی که از API OpenAI پیروی کند، کارساز خواهد بود. ارائه‌دهنده فضای کاری (workspace provider) را در .managed-agents/config.yaml تنظیم کنید و api_key و endpoint مربوطه را به سمت آن هدایت نمایید. این runtime به خودی خود هیچ مدلی ندارد، بنابراین برای پاسخ‌دهی به فراخوانی‌ها، باید یک سرویس‌دهنده در دسترس باشد.

آیا قرار دادن runtime روی یک پورت عمومی امن است؟

به شکلی که نصب می‌شود، خیر. این سرویس روی 127.0.0.1:3000 گوش می‌دهد و بدون احراز هویت شروع به کار می‌کند؛ راه‌حل این مسئله صرفاً تغییر آدرس bind نیست. یک کلید API ایجاد کنید یا MANAGED_AGENTS_API_KEY را تنظیم نمایید تا احراز هویت با bearer-token برای API فعال شود. سپس از nginx یا Caddy برای TLS در مقابل آن استفاده کنید و پورت 3000 را در فایروال ببندید تا تنها مسیر دسترسی، از طریق proxy باشد.

تفاوت بین sandboxهای محلی، Docker و Kubernetes چیست؟

local کد ابزارها را به عنوان یک child process از runtime روی میزبان اجرا می‌کند، با دسترسی‌های کاربرِ runtime و بدون هیچ‌گونه ایزولاسیون. docker برای هر نشست (session) یک container و فایل‌سیستم مجزا ایجاد کرده و پس از پایان نشست آن را حذف می‌کند؛ این حالت تنها در صورتی محدودیت حافظه و CPU اعمال می‌کند که بلوک resources در محیط تنظیم شده باشد. kubernetes نشست را به صورت یک pod اجرا کرده و آن را با kubectl exec مدیریت می‌کند که نیازمند kubectl در داخل image مربوط به runtime و تنظیمات RBAC روی podها به همراه زیرمنبع exec در namespace هدف است. یک backend چهارم نیز وجود دارد که worker خود-میزبانی‌شده (self-hosted) نام دارد و کارها را برای یک worker خارجی صف‌بندی می‌کند تا کد خارج از میزبان اجرا شود.

دقیقاً از چه چیزی باید نسخه پشتیبان تهیه کنم؟

دایرکتوری .managed-agents/ در فضای کاری. این دایرکتوری شامل config.yaml، پایگاه داده SQLite به نام data.db (حاوی agentها، نشست‌ها، ورودی‌های vault اعتبارنامه‌ها و حافظه)، به همراه فایل‌های آپلود شده، بسته‌های مهارت و snapshotهای نشست است. پیش از کپی کردن، سرویس را متوقف کنید تا SQLite در حین آرشیو کردن در حال نوشتن نباشد. کلیدهای API ارائه‌دهندگان که به صورت ${OPENAI_API_KEY} ارجاع داده می‌شوند، داخل این نسخه پشتیبان نیستند؛ بنابراین آن‌ها را جداگانه ذخیره کنید.

چرا باید به جای شاخه main، تگ v0.3.8 را clone کنم؟

یک تگ، یک درخت ثابت از کد است؛ بنابراین کلیدهای پیکربندی و دستورات CLI که درباره آن‌ها مطالعه می‌کنید، دقیقاً همان‌هایی هستند که دریافت خواهید کرد. main تغییر می‌کند و ممکن است یک کلید پیکربندی در فاصله زمانی بین نگارش راهنما و اجرای آن توسط شما، تغییر نام یابد. این پروژه همچنین هشدار می‌دهد که بسته بدون دامنه (unscoped) managed-agents در npm مربوط به این پروژه نیست، بنابراین npx managed-agents چیز نامرتبطی را نصب می‌کند. نسخه v0.3.1 عمدتاً برای جایگزینی آن روش شروع سریع npm با مسیرِ ثابتِ تگ‌شده ارائه شده است.

آیا این مقاله مفید بود؟