اپنے VPS پر SandBase Harness کیسے چلائیں

اپنے زیر انتظام SandBase agent runtime چلانے پر آپ کو کیا ملتا ہے

اپنے زیر انتظام SandBase agent runtime چلانے کا مطلب ہے کہ SandBase Harness کو اپنے سرور پر چلایا جائے، تاکہ sessions، credentials، memory اور audit trails کسی دوسرے فریق کے بجائے آپ کی اپنی disk پر محفوظ رہیں۔ یہ ایک Node service ہے۔ یہ 127.0.0.1:3000 پر listening کرتی ہے، /v1 HTTP API اور web console فراہم کرتی ہے، اور اپنی state کو آپ کی agent files کے ساتھ موجود SQLite میں محفوظ رکھتی ہے۔

/v1 API کی ساخت Claude Managed Agents (CMA) کے مطابق ہے، جو hosted managed-agent API ہے۔ یہی خصوصیت اس runtime کو دونوں صورتوں میں مفید بناتی ہے: آپ Anthropic SDK کے خلاف code لکھ کر اس کے baseURL کو اپنے server کی طرف point کر سکتے ہیں، پھر بعد میں اسی code کو hosted deployment پر منتقل کر سکتے ہیں۔

SandBase Harness خود کوئی model فراہم نہیں کرتا۔ یہ کسی model کو call کرتا ہے۔ August 2026 تک یہ OpenAI، Anthropic اور OpenAI-compatible endpoints کو support کرتا ہے۔ اس میں self-hosted gateways اور DeepSeek V4 جیسے providers بھی شامل ہیں۔ آپ کو پھر بھی API key یا ایسا local server فراہم کرنا ہوگا جو OpenAI API استعمال کرتا ہو۔

شروع کرنے سے پہلے ضروری چیزیں

• Ubuntu 24.04 چلانے والا ایک VPS، جس میں کم از کم 2 GB RAM ہو۔ انسٹالیشن کے دوران TypeScript build سب سے زیادہ وسائل استعمال کرتا ہے۔
• Node.js 22 یا اس کے بعد کا ورژن، اور npm 10 یا اس کے بعد کا ورژن۔ پروجیکٹ نے دونوں کے لیے یہی کم از کم ورژن مقرر کیے ہیں۔
• git، اور اس model provider کی API key جسے آپ استعمال کرنا چاہتے ہیں۔
• Docker، لیکن صرف اس صورت میں جب آپ ہر session کے لیے container sandboxes چاہتے ہوں۔

Ubuntu 24.04 اپنی repository میں 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 دکھائے تو distribution package ابھی انسٹال ہے اور PATH میں ترجیح حاصل کر رہا ہے۔ آگے بڑھنے سے پہلے اسے ہٹا دیں، کیونکہ build اسی node کے خلاف چلتا ہے جسے shell تلاش کرتا ہے۔

v0.3.2 tag سے SandBase انسٹال کریں

ہمیشہ tag سے انسٹال کریں، کسی ایسی branch سے نہیں جو مسلسل تبدیل ہوتی رہے۔ main کا bare clone آپ کو وہ تبدیلیاں بھی دے دیتا ہے جو ایک گھنٹہ پہلے شامل کی گئی ہوں، جبکہ ذیل میں دی گئی config keys اس کے مطابق نہیں بھی ہو سکتیں۔ 16 August 2026 تک v0.3.2 موجودہ tag ہے۔

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

npm install کے بجائے npm ci استعمال کریں۔ ci committed lockfile میں درج عین versions انسٹال کرتا ہے، اس لیے آپ کا tree اسی tree سے مطابقت رکھتا ہے جسے maintainers نے test کیا تھا۔ npm install کو نئے versions resolve کرنے کی اجازت ہے۔ اسی طرح pinned tag خاموشی سے pinned نہیں رہتا۔

اب workspace بنائیں۔ workspace ایک الگ directory ہے جس میں agent files اور تمام runtime state محفوظ ہوتی ہے۔ اسے source checkout سے باہر رکھنے سے آپ اپنے data کو متاثر کیے بغیر نیا tag 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 workspace میں .managed-agents/ directory بناتا ہے۔ start console کو http://127.0.0.1:3000/dashboard پر اور API کو http://127.0.0.1:3000/v1 پر شروع کرتا ہے۔ ابھی دونوں آپ کے laptop سے قابل رسائی نہیں ہیں، اور یہ درست ہے۔ اس کی مزید وضاحت آگے دی گئی ہے۔ فی الحال SSH کے ذریعے console تک رسائی حاصل کریں:

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

طویل node .../dist/index.js path بار بار لکھنا مشکل ہوتا ہے، اس لیے اسے ایک نام دیں۔

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

ذیل کے commands اسی بنیاد پر sandbase <command> کے طور پر لکھے گئے ہیں۔

اسے npm سے انسٹال نہ کریں

پروجیکٹ کی اپنی installation documentation میں یہ بات واضح کی گئی ہے: npm پر موجود بے دائرہ managed-agents package اس پروجیکٹ کا package نہیں ہے۔ اس لیے npx managed-agents اور npm install -g managed-agents اس runtime سے متعلق کوئی اور چیز حاصل کرتے ہیں جسے آپ استعمال کرنا چاہتے ہیں۔ جب تک maintainers official scoped package کا اعلان نہ کریں، tagged GitHub source سے انسٹال کریں۔ یہ پروجیکٹ کی تاریخ میں معمولی حاشیہ نہیں ہے: v0.3.1 بنیادی طور پر پرانے npm quick start کو pinned tagged-source path سے بدلنے کے لیے جاری کیا گیا ہے۔

ورک اسپیس کو model provider سے منسلک کریں

init، .managed-agents/config.yaml میں لکھتا ہے۔ پورے ورک اسپیس کے لیے ایک provider configure کیا جاتا ہے، اور پھر ہر agent مخصوص model IDs منتخب کرتا ہے۔

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

${OPENAI_API_KEY} form کی قدر process environment سے لیتا ہے، اس لیے key config file اور اس file کے ہر backup سے باہر رہتی ہے۔ اسے ایسی environment file میں رکھیں جسے صرف root پڑھ سکے، کیونکہ systemd privileges کم کرنے سے پہلے EnvironmentFile= کو root کے طور پر پڑھتا ہے۔

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

اس file کو editor میں کھولیں اور ایک سطر شامل کریں، OPENAI_API_KEY=sk-...۔ Provider keys اسی جگہ رکھی جاتی ہیں۔ کسی agent کے session کے دوران استعمال ہونے والے secrets اس کے بجائے runtime کے credential vaults میں رکھے جاتے ہیں۔ یہ ایک الگ مسئلہ ہے جس کا blast radius بھی مختلف ہوتا ہے، اور AI agents سے secrets باہر رکھنا پڑھ لینا مفید ہے، اس سے پہلے کہ آپ production token ان دونوں میں سے کسی جگہ paste کریں۔

ایجنٹ YAML: mcp_servers، tools اور اجازت کی پالیسیاں

ایجنٹس workspace کی agents/ directory میں YAML files کے طور پر define ہوتے ہیں۔ 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

اسے load کریں اور تصدیق کریں کہ یہ درست طور پر شامل ہو گئی ہے:

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

reload seed YAML کو SQLite میں import کرتا ہے۔ list کو اب ID کے ساتھ ایجنٹ دکھانا چاہیے۔ اگر list اسے نہیں دکھاتا تو file parse نہیں ہوئی، اور وجہ .managed-agents/logs/runtime.log میں لکھی جاتی ہے۔

mcp_servers MCP (model context protocol) endpoints declare کرتا ہے۔ type: url کا مطلب ہے کہ runtime کسی دوسرے مقام پر چلنے والے server سے HTTP کے ذریعے رابطہ کرتا ہے۔ اس لیے یہاں آپ کی پہلے سے چل رہی کوئی بھی سروس استعمال ہو سکتی ہے، بشمول اسی VPS پر hosted MCP servers جو runtime چلا رہا ہے۔

کسی server کو declare کرنے سے اس کے tools ایجنٹ کو دستیاب نہیں ہوتے۔ tools list یہ کام کرتی ہے۔ اس میں موجود mcp_toolset entry کا mcp_server_name اوپر دیے گئے name سے match ہونا چاہیے۔ اگر ایجنٹ اس طرح کام کرے جیسے MCP tools موجود ہی نہیں ہیں تو کسی اور جگہ دیکھنے سے پہلے ان دونوں strings کا حرف بہ حرف موازنہ کریں۔

agent_toolset_20260401 built-in tool set ہے۔ تاریخ والا suffix schema version ہے، اس لیے اس سے pinned ایجنٹ وہی tool definitions استعمال کرتا ہے جن کے مطابق اسے لکھا گیا تھا۔ default_config اس set کے ہر tool کے لیے policy مقرر کرتا ہے، جبکہ configs کے تحت موجود ہر entry نام کے ذریعے ایک tool کی policy override کرتی ہے، جیسا کہ مثال میں bash کے ساتھ دکھایا گیا ہے۔

permission_policy وہ جگہ ہے جہاں runtime محض model call کے مقابلے میں اپنی افادیت ثابت کرتا ہے۔ always_ask session کو روک کر call چلنے سے پہلے کسی انسان کی منظوری کا انتظار کرتا ہے۔ always_allow call کو گزرنے دیتا ہے۔ bash کو always_ask پر set کرنے کا مطلب ہے کہ ایجنٹ آپ کے سامنے exact command دکھائے بغیر shell command نہیں چلا سکتا۔ یہ وہی control ہے جو آپ VPS پر Claude Code محفوظ طریقے سے چلاتے وقت استعمال کریں گے۔

تین sandbox modes اور ہر mode کے مناسب استعمال کا وقت

وہ tool calls جو code execute کرتی ہیں، sandbox کے اندر چلتی ہیں۔ Backend کا انتخاب ہر environment کے لیے sandbox_provider کے ذریعے، environment کے config object میں، یا console میں Settings پھر Sandbox کے تحت کیا جاتا ہے۔ Environments API کے ذریعے POST /v1/environments پر create کیے جاتے ہیں۔

local code کو host پر runtime کے child process کے طور پر، runtime کے اپنے user سے چلاتا ہے۔ یہ default ہے، اور اس وقت مناسب ہے جب آپ واحد user ہوں اور agent صرف وہ files پڑھے جن کی ملکیت آپ کے پاس ہو۔ یہ isolation فراہم نہیں کرتا۔ جو tool call files delete کرے گی، وہ آپ کی files delete کرے گی، اور جو tool call /etc/sandbase/runtime.env پڑھے گی، وہ آپ کی provider key پڑھ لے گی۔

docker ہر session کے لیے ایک container شروع کرتا ہے۔

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

Session کو اپنا filesystem، اپنی memory ceiling اور اپنا CPU share ملتا ہے، اور session ختم ہونے پر container بھی remove ہو جاتا ہے۔ Agent کے ایسے code چلانے کے فوراً بعد اس mode پر منتقل ہو جائیں جو آپ نے خود نہیں لکھا۔ اس کی قیمت یہ ہے کہ runtime کے user کو Docker socket تک access درکار ہوتا ہے، اور docker group کی membership host پر root کے مساوی ہوتی ہے۔ Per-session containers، ہر run کے لیے ایک container والے self-hosted agent sandboxes کے جیسی ساخت رکھتے ہیں، اس لیے escaped process کی ممکنہ رسائی سے متعلق reasoning یہاں بھی بغیر تبدیلی کے لاگو ہوتی ہے۔

kubernetes session workload کو pod کے طور پر چلاتا ہے اور اسے kubectl exec اور kubectl cp کے ذریعے چلاتا ہے۔ Runtime image میں kubectl موجود ہونا چاہیے، اور اس کے ServiceAccount کو target namespace میں pods کو create، delete، get، list اور watch کرنے کے لیے RBAC (role-based access control) permission درکار ہوتی ہے، نیز exec subresource کے لیے بھی۔ یہ mode صرف اسی وقت setup کے قابل ہے جب آپ پہلے سے cluster چلا رہے ہوں۔

runtime کو 127.0.0.1 سے bind کیوں کیا گیا ہے؟

کیونکہ یہ authentication بند حالت میں شروع ہوتا ہے۔ جب کم از کم ایک API key موجود ہو تو runtime bearer-token authentication فعال کرتا ہے، جبکہ نیا init کوئی key نہیں بناتا۔ اس default حالت میں `0.0.0.0` سے bind کرنے کا مطلب یہ ہوگا کہ shell tools اور آپ کی provider key رکھنے والا غیر مصدقہ agent runtime public internet پر دستیاب ہو جائے۔

اس لیے جب آپ اسے قابل رسائی بنانا چاہیں تو bind address تبدیل نہ کریں، بلکہ دو دوسرے کام کریں۔

پہلا، authentication فعال کریں۔ service environment file میں MANAGED_AGENTS_API_KEY سیٹ کریں، یا POST /v1/api-keys سے key بنائیں۔ یہ کمانڈ secret_key field صرف ایک بار واپس کرتی ہے اور اسے دوبارہ نہیں دکھاتی۔ اس کے بعد clients ہر request کے ساتھ Authorization: Bearer <key> بھیجتے ہیں۔

دوسرا، اس کے سامنے reverse proxy رکھیں اور وہیں TLS (transport layer security) terminate کریں۔ runtime جان بوجھ کر plain HTTP فراہم کرتا ہے اور توقع کرتا ہے کہ certificates کوئی دوسری سروس سنبھالے گی۔

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;
    }
}

ان میں سے دو lines محض ظاہری سجاوٹ نہیں ہیں۔ proxy_buffering off اہم ہے کیونکہ sessions server-sent events (SSE) کے ذریعے stream ہوتے ہیں۔ buffering فعال ہونے پر nginx response کو اس وقت تک روک کر رکھتا ہے جب تک اس کا buffer بھر نہ جائے۔ نتیجتاً agent کے کام کرنے کے دوران console میں کچھ نظر نہیں آتا، اور آخر میں تمام output ایک ساتھ دکھائی دیتا ہے۔ proxy_read_timeout 3600s بھی اہم ہے کیونکہ اس کی default قدر 60 seconds ہے۔ اس لیے اگر stream ایک minute سے زیادہ خاموش رہے تو proxy turn کے دوران connection بند کر دیتی ہے، اور failure runtime کے crash ہونے جیسی دکھائی دیتی ہے۔

Firewall پر 22 اور 443 کھولیں۔ 3000 بند رکھیں، کیونکہ proxy loopback کے ذریعے اس تک پہنچتا ہے اور host کے باہر سے کسی چیز کو وہاں تک رسائی نہیں ہونی چاہیے۔

اپنے box کی طرف Anthropic SDK کی سمت مقرر کریں

Runtime، CMA جیسا /v1 surface فراہم کرتا ہے، اس لیے Anthropic SDK client سے بات کرنے کے لیے صرف ایک field تبدیل کرنا پڑتا ہے۔

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 clients کی جانب سے بھیجے گئے beta headers، anthropic-beta: managed-agents-2026-04-01 اور anthropic-beta: agent-memory-2026-07-22، بھی قبول کرتا ہے۔ Local runtime کے لیے یہ اختیاری ہیں۔ ان کا مقصد یہ ہے کہ hosted deployment کے لیے لکھا گیا code یہاں بغیر تبدیلی کے چل سکے۔

Compatibility قریب ہے، لیکن مکمل نہیں۔ کسی surface کے موجود ہونے کا مفروضہ قائم کرنے سے پہلے checkout میں docs/api-matrix.md پڑھیں، کیونکہ project اپنی limitations وہاں درج کرتا ہے۔ ان میں client-side custom tools بھی شامل ہیں، جن کے لیے موجودہ event-result protocol سے اوپر named registration درکار ہے۔

Plain HTTP بھی اسی طرح کام کرتا ہے اور runtime کے فعال ہونے کی فوری تصدیق کا سب سے تیز طریقہ ہے:

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}'

صحت مند response مسلسل آنے والے events کا stream ہوتا ہے۔ اگر connection منقطع ہو جائے تو پورا turn دوبارہ چلانے کے بجائے اپنے دیکھے گئے آخری event سے resume کریں:

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

یہ resumable stream اس لیے ہے کہ بند laptop کے بعد بھی session برقرار رہتا ہے۔ Events server پر persist ہوتے ہیں، اس لیے client log کو دوبارہ چلاتا ہے، نہ کہ واحد copy اپنے پاس رکھتا ہے۔

ڈسک پر credentials، memory اور audit trails کہاں محفوظ ہوتے ہیں

runtime کی ملکیت میں موجود ہر چیز workspace میں .managed-agents/ کے تحت محفوظ ہوتی ہے۔

.managed-agents/
├── config.yaml
├── data.db
├── logs/runtime.log
├── files/
├── skills/
├── snapshots/
└── sandbox/

• data.db SQLite metadata محفوظ کرتا ہے: agents، sessions، credential vault entries، memory store entries اور API keys۔
• files/ اپ لوڈ کی گئی files کے bytes محفوظ کرتا ہے، جبکہ skills/ اپ لوڈ کیے گئے skill packages محفوظ کرتا ہے۔
• snapshots/ session workspace snapshots محفوظ کرتا ہے، جبکہ sandbox/ local-mode sessions کی working directories محفوظ کرتا ہے۔
• logs/runtime.log وہ پہلی جگہ ہے جہاں کسی چیز کے خاموشی سے کچھ نہ کرنے کی صورت میں دیکھنا چاہیے۔

Credential vaults secrets کے گروپس ہوتے ہیں۔ ہر گروپ auth_type کے ذریعے شامل کیا جاتا ہے، جیسے environment_variable، اور session بناتے وقت vault_ids کے ذریعے session کے ساتھ منسلک کیا جاتا ہے۔ Memory stores نامزد entries محفوظ کرتے ہیں۔ آپ انہیں memory_store کے طور پر session میں mount کرتے ہیں، جس کی اپنی access setting اور instructions ہوتی ہیں۔ دونوں data.db میں محفوظ ہوتے ہیں۔ یہی اس runtime اور raw model call کے درمیان بنیادی فرق ہے: runtime sessions کے درمیان معلومات یاد رکھتا ہے اور پیش آنے والے واقعات کا ریکارڈ لکھتا ہے۔

چونکہ یہ سب ایک ہی directory میں ہے، اس کا backup بھی ایک ہی unit کے طور پر لیں۔

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

پہلے service روکیں۔ runtime کے SQLite database میں لکھتے وقت اس کی copy بنانے سے ایسی file حاصل ہو سکتی ہے جو restore کے بعد کھلے ہی نہ۔ اس کا علم عموماً اسی وقت ہوتا ہے جب backup درکار ہو۔ اگر آپ agent YAML کو git میں اور state کو کسی الگ location میں رکھنا چاہتے ہیں تو deployment documentation، start پر --data-dir کے ذریعے state location مقرر کرنے کی سہولت فراہم کرتی ہے۔

Restore کا طریقہ اس کے برعکس ہے: نئی machine پر وہی tag check out کریں، archive کو workspace میں unpack کریں، اور service شروع کریں۔ اگر آپ نے ${OPENAI_API_KEY} form استعمال کیا تھا تو provider key archive میں شامل نہیں ہوگی، اس لیے اسے ایسی جگہ محفوظ رکھیں جہاں ضرورت کے وقت آپ کو دوبارہ دستیاب ہو۔

اسے systemd کے تحت چلائیں

Runtime کے لیے الگ user بنائیں، تاکہ local sandbox mode میں tool call آپ کے user کے طور پر کارروائی نہ کر سکے۔

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 مثال PATH پر managed-agents binary کو call کرتی ہے۔ Tagged-source install یہ binary نہیں بناتا، اس لیے ExecStart اس کے بجائے built entry point کے خلاف 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

درست نتیجہ status سے active (running) اور curl سے 200 ہوتا ہے۔ کسی اور نتیجے کی صورت میں پہلے journalctl -u sandbase -n 50 اور پھر .managed-agents/logs/runtime.log پڑھیں۔ enable --now وہ حصہ ہے جو اہمیت رکھتا ہے، کیونکہ ہاتھ سے شروع کیا گیا process اگلے reboot کے بعد ختم ہو جاتا ہے۔

کیا خراب ہوتا ہے اور آپ کو کون سا پیغام نظر آئے گا

npm run build npm کی طرف سے کسی error کے بغیر بند ہو جاتا ہے۔ 1 GB VPS پر TypeScript compile کو kernel کا out-of-memory killer روک دیتا ہے۔ یہ واقعہ npm کے بجائے kernel log میں درج ہوتا ہے۔ journalctl -k | grep -i "out of memory" سے تصدیق کریں۔ یہ ایسی سطر دکھاتا ہے جس میں ختم کیے گئے node process کا نام ہوتا ہے۔ swap شامل کریں، یا بڑے instance پر build کر کے dist/ کو وہاں copy کریں۔

Error: listen EADDRINUSE: address already in use 127.0.0.1:3000۔ کوئی دوسرا process پہلے ہی اس port کو استعمال کر رہا ہے۔ sudo ss -lntp | grep 3000 اس process کا نام دکھاتا ہے۔ اس process کو روکیں، یا runtime کو --port 3001 کے ساتھ start کریں اور proxy update کریں۔

Dashboard آپ کے laptop سے load نہیں ہوگا۔ یہ متوقع رویہ ہے، کیونکہ runtime loopback پر bind ہوتا ہے۔ اوپر دیا گیا SSH tunnel استعمال کریں، یا reverse proxy مکمل کریں۔ اسے --host 0.0.0.0 سے درست نہ کریں، کیونکہ key موجود ہونے تک authentication بند رہتی ہے۔

Docker sandboxes permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock کے ساتھ fail ہوتے ہیں۔ sandbase user، docker group میں شامل نہیں ہے۔ اسے sudo usermod -aG docker sandbase سے درست کریں اور service restart کریں۔ یہ بھی سمجھیں کہ آپ نے کیا اجازت دی ہے: host پر یہ group root کے برابر ہے، اس لیے runtime کو الگ user دینے کی وجہ جزوی طور پر ختم ہو جاتی ہے۔

Kubernetes sandboxes Error from server (Forbidden) کے ساتھ fail ہوتے ہیں۔ ServiceAccount کے پاس pod permissions یا exec subresource موجود نہیں ہے۔ kubectl auth can-i create pods/exec -n <namespace> سے براہ راست جانچ کریں۔ یہ yes یا no میں جواب دیتا ہے۔

API key شامل کرنے کے بعد ہر request 401 واپس کرتی ہے۔ پہلی key موجود ہوتے ہی authentication فعال ہو جاتی ہے، اور یہ console کے ساتھ ساتھ API پر بھی لاگو ہوتی ہے۔ Authorization: Bearer <key> بھیجیں۔ اگر key گم ہو گئی ہے تو نئی key بنائیں، کیونکہ secret_key صرف ایک بار واپس کیا جاتا ہے اور readable form میں محفوظ نہیں ہوتا۔

MCP server کے tools کسی session میں ظاہر نہیں ہوتے۔ tools block میں موجود mcp_server_name کو mcp_servers میں موجود name سے ملائیں۔ پھر curl -i <url> سے جانچیں کہ runtime خود server سے URL تک پہنچ سکتا ہے۔ URL-type MCP server ایک network dependency ہے، اور VPS names resolve کرتا ہے اور traffic کو آپ کے laptop سے مختلف طریقے سے route کرتا ہے۔

FAQ

کیا میں OpenAI یا Anthropic key کے بغیر SandBase Harness چلا سکتا ہوں؟

ہاں، اگر آپ کے پاس OpenAI-compatible endpoint موجود ہو۔ Runtime، OpenAI، Anthropic اور OpenAI-compatible providers کو support کرتا ہے، اس لیے OpenAI API پر کام کرنے والا local server بھی استعمال ہو سکتا ہے۔ .managed-agents/config.yaml میں workspace provider سیٹ کریں اور api_key اور endpoint کو اسی server کی طرف point کریں۔ Runtime میں اپنا کوئی model شامل نہیں، اس لیے calls کا جواب دینے کے لیے کسی model کی ضرورت ہوگی۔

کیا runtime کو public port پر expose کرنا محفوظ ہے؟

موجودہ installation کے ساتھ نہیں۔ یہ 127.0.0.1:3000 پر bind ہوتا ہے اور authentication بند حالت میں شروع ہوتا ہے۔ اس کا حل bind address تبدیل کرنا نہیں ہے۔ API key بنائیں یا MANAGED_AGENTS_API_KEY سیٹ کریں تاکہ bearer-token authentication فعال ہو جائے۔ اس کے بعد TLS کے لیے nginx یا Caddy کو سامنے رکھیں، اور firewall پر port 3000 بند رکھیں تاکہ رسائی کا واحد راستہ proxy کے ذریعے ہو۔

local، Docker اور Kubernetes sandboxes میں کیا فرق ہے؟

local tool code کو host پر runtime کے child process کے طور پر چلاتا ہے، runtime user کی permissions کے ساتھ، اور اس میں کوئی isolation نہیں ہوتی۔ docker ہر session کو اس کے اپنے filesystem، memory limit اور CPU share کے ساتھ الگ container دیتا ہے، اور session ختم ہونے پر اسے حذف کر دیتا ہے۔ kubernetes session کو pod کے طور پر چلاتا ہے اور kubectl exec کے ذریعے اسے control کرتا ہے۔ اس کے لیے runtime image کے اندر kubectl، نیز target namespace میں pods اور exec subresource پر RBAC درکار ہوتا ہے۔

مجھے بالکل کس چیز کا backup لینا چاہیے؟

Workspace میں موجود .managed-agents/ directory کا۔ اس میں config.yaml، data.db SQLite database، agents، sessions، credential vault entries اور memory entries شامل ہوتے ہیں۔ اس کے علاوہ uploaded files، skill packages اور session snapshots بھی اسی میں ہوتے ہیں۔ اسے copy کرنے سے پہلے service روک دیں تاکہ archive بناتے وقت SQLite میں لکھائی نہ ہو رہی ہو۔ ${OPENAI_API_KEY} کے طور پر referenced provider API keys backup میں شامل نہیں ہوتیں، اس لیے انہیں الگ محفوظ کریں۔

main کے بجائے v0.3.2 tag clone کیوں کریں؟

Tag ایک fixed tree ہوتا ہے، اس لیے جن config keys اور CLI commands کے بارے میں آپ پڑھتے ہیں، عملی طور پر وہی حاصل ہوتے ہیں۔ main تبدیل ہوتا رہتا ہے، اور guide لکھے جانے اور اسے چلانے کے درمیان config key کا نام تبدیل ہو سکتا ہے۔ Project یہ بھی خبردار کرتا ہے کہ npm پر موجود unscoped managed-agents package اس project کا حصہ نہیں ہے، اس لیے npx managed-agents کوئی غیر متعلقہ چیز install کرتا ہے۔ Release v0.3.1 کا بنیادی مقصد npm quick start کو pinned tagged-source path سے تبدیل کرنا ہے۔