SSD Nodes Learn 🎉 VPS $5.50/महिन्यापासून
मार्गदर्शक Matt Connorद्वारे Matt Connor

SandBase एजंट रनटाइम स्वतःच्या सर्व्हरवर कसा होस्ट करावा

SandBase Harness v0.3.2 स्वतःच्या VPS वर इंस्टॉल करण्याची संपूर्ण प्रक्रिया. यात टॅग केलेले इंस्टॉलेशन, YAML कॉन्फिगरेशन, MCP सर्व्हर्स आणि Anthropic SDK सेटिंग्जची माहिती आहे.

SandBase एजंट रनटाइम स्वतः होस्ट केल्यावर तुम्हाला काय मिळते

SandBase एजंट रनटाइम स्वतः होस्ट करणे म्हणजे SandBase Harness तुमच्या मालकीच्या सर्व्हरवर चालवणे. यामुळे सेशन्स, क्रेडेन्शियल्स, मेमरी आणि ऑडिट ट्रेल्स दुसऱ्या कोणाच्या सर्व्हरवर न राहता तुमच्या डिस्कवर राहतात. ही एक Node सेवा आहे. ती 127.0.0.1:3000 वर लिसन करते, /v1 HTTP API आणि वेब कन्सोल सर्व्ह करते, आणि तिची स्थिती तुमच्या एजंट फाइल्सच्या शेजारी SQLite मध्ये साठवते.

/v1 API ची रचना Claude Managed Agents (CMA) वर आधारित आहे, जे एक होस्ट केलेले मॅनेज्ड-एजंट API आहे. यामुळेच हा रनटाइम दोन्ही बाजूंनी महत्त्वाचा ठरतो: तुम्ही Anthropic SDK वापरून कोड लिहू शकता आणि त्याचे baseURL तुमच्या स्वतःच्या सर्व्हरकडे वळवू शकता, आणि नंतर तोच कोड होस्ट केलेल्या डिप्लॉयमेंटवर हलवू शकता.

SandBase Harness स्वतः कोणतेही मॉडेल पुरवत नाही. ते मॉडेलला कॉल करते. ऑगस्ट 2026 पर्यंत, ते OpenAI, Anthropic आणि OpenAI-सुसंगत एंडपॉइंट्सना सपोर्ट करते, ज्यामध्ये सेल्फ-होस्टेड गेटवेज आणि DeepSeek V4 सारखे प्रोव्हायडर्स समाविष्ट आहेत. तुम्हाला यासाठी स्वतःची API की किंवा OpenAI API ला सपोर्ट करणारा स्थानिक सर्व्हर वापरावा लागेल.

सुरुवात करण्यापूर्वी आवश्यक गोष्टी

  • किमान 2 GB RAM असलेला Ubuntu 24.04 वर चालणारा VPS. TypeScript बिल्ड ही इन्स्टॉलेशनमधील सर्वात जड प्रक्रिया आहे.
  • Node.js 22 किंवा त्यापेक्षा नवीन आवृत्ती आणि npm 10 किंवा त्यापेक्षा नवीन आवृत्ती. या दोन्ही प्रकल्पाच्या अटींनुसार अनिवार्य किमान आवश्यकता आहेत.
  • git, आणि त्यासोबत तुम्ही वापरणार असलेल्या मॉडेल प्रोव्हायडरची API key.
  • Docker, परंतु केवळ तुम्हाला प्रति-सत्र (per-session) कंटेनर सँडबॉक्स हवे असतील तरच.

Ubuntu 24.04 च्या स्वतःच्या रिपॉझिटरीमध्ये Node 18.19 उपलब्ध आहे, जी किमान आवश्यकतेपेक्षा कमी आहे, म्हणून NodeSource कडून Node मिळवा.

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 सापडेल त्यावर चालते.

v0.3.2 टॅगवरून SandBase इन्स्टॉल करा

नेहमी टॅगवरून इन्स्टॉल करा, कधीही बदलणाऱ्या (moving) ब्रँचवरून करू नका. main चा bare clone केल्यास तुम्हाला तासाभरापूर्वी अपडेट झालेला कोड मिळेल आणि खाली दिलेले कॉन्फिगरेशन कीज कदाचित त्याच्याशी जुळणार नाहीत. 16 ऑगस्ट 2026 पर्यंत v0.3.2 हा सध्याचा टॅग आहे.

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 कमिट केलेल्या lockfile मध्ये नोंदवलेल्या अचूक आवृत्त्या इन्स्टॉल करते, त्यामुळे तुमची सिस्टिम मेंटेनर्सनी टेस्ट केलेल्या सिस्टिमशी तंतोतंत जुळते. 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 वर कन्सोल आणि http://127.0.0.1:3000/v1 वर API सुरू होते. यापैकी कशालाही तुमच्या लॅपटॉपवरून सध्या पोहोचता येणार नाही, जे योग्यच आहे आणि त्याबद्दल पुढे माहिती दिली आहे. सध्या 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 वरून इंस्टॉल करू नका

प्रकल्पाच्या स्वतःच्या इन्स्टॉलेशन डॉक्युमेंटमध्ये असे नमूद केले आहे की: npm वर दिसणारे unscoped managed-agents पॅकेज हे या प्रकल्पाचे नाही. त्यामुळे npx managed-agents आणि npm install -g managed-agents कमांड्स वापरल्यास तुम्हाला हव्या असलेल्या रनटाइमशी संबंधित नसलेली इतर काही फाईल्स मिळतील. जोपर्यंत मेंटेनर्स अधिकृत scoped पॅकेज जाहीर करत नाहीत, तोपर्यंत GitHub वरील tagged सोर्सवरूनच इंस्टॉल करा. प्रकल्पाच्या इतिहासामध्ये ही एक छोटी टीप नाही: v0.3.1 हे व्हर्जन प्रामुख्याने जुन्या npm क्विक स्टार्टला बदलून त्याऐवजी पिन केलेल्या tagged-source पाथचा वापर करण्यासाठी आणले गेले आहे.

वर्कस्पेसला मॉडेल प्रोव्हायडरशी जोडा

init हे .managed-agents/config.yaml मध्ये लिहिते. संपूर्ण वर्कस्पेससाठी एक प्रोव्हायडर कॉन्फिगर केला जातो आणि त्यानंतर वैयक्तिक एजंट्स विशिष्ट मॉडेल IDs निवडतात.

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

${OPENAI_API_KEY} फॉर्म प्रोसेस एन्व्हायरनमेंटमधून व्हॅल्यू घेतो, त्यामुळे की (key) कॉन्फिग फाईलमध्ये आणि त्या फाईलच्या कोणत्याही बॅकअपमध्ये राहत नाही. ती अशा एन्व्हायरनमेंट फाईलमध्ये ठेवा जी फक्त 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

ती फाईल एडिटरमध्ये उघडा आणि OPENAI_API_KEY=sk-... ही एक ओळ जोडा. प्रोव्हायडर कीज येथेच असाव्यात. सत्रादरम्यान एजंट वापरत असलेली गुपिते (secrets) रनटाइमच्या क्रेडेंशियल व्हॉल्टमध्ये असावीत, जी एक वेगळी समस्या आहे आणि तिचा प्रभाव क्षेत्र (blast radius) वेगळा असतो. तसेच, तुम्ही प्रोडक्शन टोकन कोठेही पेस्ट करण्यापूर्वी AI एजंट्सपासून गुपिते सुरक्षित ठेवणे हे वाचणे फायदेशीर ठरेल.

एजंट YAML: mcp_servers, टूल्स आणि परवानगी धोरणे

एजंट्स हे वर्कस्पेसच्या agents/ डिरेक्टरीमध्ये YAML फाइल्स म्हणून परिभाषित केलेले असतात. रनटाइमचा हा असा भाग आहे जिथे तुम्ही प्रत्यक्ष काम कराल.

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 मध्ये तो दिसत नसेल, तर फाइल पार्स झालेली नाही आणि .managed-agents/logs/runtime.log मध्ये त्याचे कारण लिहिलेले असते.

mcp_servers हे MCP (model context protocol) एंडपॉइंट्स घोषित करते. type: url चा अर्थ असा की रनटाइम इतरत्र चालणाऱ्या सर्व्हरशी HTTP द्वारे संवाद साधतो, त्यामुळे तुम्ही आधीच चालवत असलेली कोणतीही गोष्ट येथे काम करते, ज्यामध्ये त्याच VPS वर होस्ट केलेले MCP सर्व्हर देखील समाविष्ट आहेत.

सर्व्हर घोषित केल्याने त्याची टूल्स एजंटला मिळत नाहीत. tools यादी ते काम करते, एका mcp_toolset एंट्रीद्वारे ज्याचे mcp_server_name हे वरील name शी जुळते. जर एजंट असे वागत असेल की जणू काही MCP टूल्स अस्तित्वातच नाहीत, तर इतरत्र कुठेही पाहण्यापूर्वी त्या दोन स्ट्रिंग्सची अक्षरशः तुलना करा.

agent_toolset_20260401 हा इन-बिल्ट टूल सेट आहे. दिनांकित सफिक्स ही एक स्कीमा आवृत्ती आहे, त्यामुळे त्याला पिन केलेला एजंट ज्या आवृत्तीवर लिहिला गेला होता, त्याच टूल डेफिनिशन्स वापरतो. default_config हे सेटमधील प्रत्येक टूलसाठी धोरण ठरवते आणि configs अंतर्गत प्रत्येक एंट्री एका विशिष्ट टूलला नावानुसार ओव्हरराइड करते, उदाहरणातील bash प्रमाणे.

permission_policy हे असे ठिकाण आहे जिथे रनटाइम केवळ मॉडेल कॉलपेक्षा अधिक उपयुक्त ठरतो. always_ask हे सेशन थांबवते आणि कॉल रन होण्यापूर्वी मानवी मंजुरीची वाट पाहते. always_allow त्याला परवानगी देते. bash ला always_ask वर सेट करण्याचा अर्थ असा की, एजंट तुम्हाला आधी नेमकी कमांड दाखवल्याशिवाय कोणतीही शेल कमांड रन करू शकत नाही, जे Claude Code सुरक्षितपणे VPS वर चालवताना तुम्ही वापरता त्या नियंत्रणासारखेच आहे.

तीन सँडबॉक्स मोड आणि त्यांचा वापर कधी करावा

कोड एक्झिक्युट करणारे टूल कॉल्स सँडबॉक्समध्ये चालतात. बॅकएंडची निवड प्रत्येक एन्व्हायर्नमेंटनुसार केली जाते, जी एन्व्हायर्नमेंटच्या config ऑब्जेक्टमधील sandbox_provider द्वारे किंवा कन्सोलमधील Settings आणि त्यानंतर Sandbox पर्यायांतर्गत केली जाते. एन्व्हायर्नमेंट POST /v1/environments वरील API द्वारे तयार केले जातात.

local मोडमध्ये कोड रनटाइमच्या चाइल्ड प्रोसेस म्हणून, होस्टवर आणि रनटाइमच्या स्वतःच्या युजरच्या अधिकारांतर्गत चालतो. हा डीफॉल्ट मोड आहे. जेव्हा तुम्ही एकमेव युजर असता आणि एजंट फक्त तुमच्या मालकीच्या फाइल्स वाचतो, तेव्हा हा मोड वापरणे योग्य आहे. यात कोणतीही आयसोलेशन (विलगीकरण) नसते. फाइल्स डिलीट करणारा टूल कॉल तुमच्या फाइल्स डिलीट करू शकतो आणि /etc/sandbase/runtime.env वाचणारा टूल कॉल तुमची प्रोव्हायडर की वाचू शकतो.

docker मोड प्रत्येक सेशनसाठी एक कंटेनर सुरू करतो.

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

या सेशनला स्वतःची फाइलसिस्टम, मेमरीची मर्यादा आणि CPU शेअर मिळतो. सेशन संपल्यावर कंटेनर काढून टाकला जातो. जेव्हा एजंट असा कोड चालवतो जो तुम्ही लिहिलेला नाही, तेव्हा त्वरित या मोडवर स्विच करा. याचा तोटा असा की, रनटाइमच्या युजरला Docker सॉकेटचा ॲक्सेस असणे आवश्यक असते आणि docker ग्रुपचे सदस्यत्व असणे म्हणजे होस्टवर root असण्यासारखेच आहे. प्रति-सेशन कंटेनर हे प्रत्येक रनसाठी एक कंटेनर असलेल्या सेल्फ-होस्टेड एजंट सँडबॉक्स सारखेच असतात, त्यामुळे एस्केप झालेली प्रोसेस कशापर्यंत पोहोचू शकते, हे तर्क येथेही लागू होतात.

kubernetes मोडमध्ये सेशनचे वर्कलोड पॉड (pod) म्हणून चालवले जाते आणि ते kubectl exec व kubectl cp द्वारे नियंत्रित केले जाते. रनटाइम इमेजमध्ये kubectl असणे आवश्यक आहे. तसेच, त्याच्या ServiceAccount कडे टार्गेट नेमस्पेसमध्ये पॉड्स तयार करणे, डिलीट करणे, मिळवणे, लिस्ट करणे आणि मॉनिटर करण्यासाठी RBAC (role-based access control) परवानगी असणे आवश्यक आहे, सोबतच exec सब-रिसोर्सची परवानगीही हवी. जर तुम्ही आधीच क्लस्टर चालवत असाल, तरच हा मोड सेटअप करणे फायदेशीर ठरते.

रंटाईम 127.0.0.1 वर का बाइंड (bind) केलेला असतो?

कारण तो ऑथेंटिकेशन बंद असताना सुरू होतो. जेव्हा किमान एक API key अस्तित्वात असते, तेव्हा रंटाईम bearer-token ऑथेंटिकेशन सक्षम करतो, परंतु नवीन init मध्ये कोणतीही की तयार केली जात नाही. डीफॉल्टनुसार 0.0.0.0 वर बाइंड केल्यास, शेल टूल्स आणि तुमचा प्रोव्हायडर की असलेला एक अन-ऑथेंटिकेटेड एजंट रंटाईम थेट सार्वजनिक इंटरनेटवर उपलब्ध होईल.

त्यामुळे जेव्हा तुम्हाला तो पोहोचण्यायोग्य (reachable) हवा असेल, तेव्हा बाइंड ॲड्रेस बदलू नका आणि खालील दोन गोष्टी करा.

प्रथम, ऑथेंटिकेशन सुरू करा. सर्व्हिस एन्व्हायरनमेंट फाईलमध्ये MANAGED_AGENTS_API_KEY सेट करा किंवा POST /v1/api-keys वापरून एक की तयार करा, जी एकदाच secret_key फील्ड दर्शवते आणि त्यानंतर पुन्हा कधीही दाखवत नाही. त्यानंतर क्लायंट प्रत्येक विनंतीवर Authorization: Bearer <key> पाठवतात.

दुसरे, समोर एक रिव्हर्स प्रॉक्सी ठेवा आणि तिथे TLS (transport layer security) टर्मिनेट करा. रंटाईम डिझाइननुसार प्लेन 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;
    }
}

त्यातील दोन ओळी केवळ सजावट नाहीत. proxy_buffering off महत्त्वाचे आहे कारण सेशन्स server-sent events (SSE) द्वारे स्ट्रीम होतात. बफरिंग सुरू असल्यास, nginx बफर भरेपर्यंत रिस्पॉन्स रोखून धरते, त्यामुळे एजंट काम करत असताना कन्सोलवर काहीही दिसत नाही आणि शेवटी सर्व माहिती एकदम दिसते. proxy_read_timeout 3600s महत्त्वाचे आहे कारण डीफॉल्ट वेळ 60 सेकंद असते. त्यामुळे जर एखादे स्ट्रीम एका मिनिटापेक्षा जास्त काळ शांत राहिले, तर प्रॉक्सी ते बंद करते आणि ही त्रुटी रंटाईम क्रॅश झाल्यासारखी वाटते.

फायरवॉलवर 22 आणि 443 पोर्ट उघडा. 3000 पोर्ट बंद ठेवा, कारण प्रॉक्सी त्यापर्यंत लूपबॅकद्वारे पोहोचते आणि सर्व्हरच्या बाहेरील कोणत्याही गोष्टीला तिथे पोहोचण्याची गरज नसते.

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 देखील स्वीकारते. स्थानिक रनटाइमसाठी ते ऐच्छिक आहेत. हे हेडर्स अशा प्रकारे ठेवले आहेत जेणेकरून होस्ट केलेल्या डिप्लॉयमेंटसाठी लिहिलेला कोड येथे कोणताही बदल न करता चालू शकेल.

सुसंगतता बऱ्यापैकी आहे, पण पूर्ण नाही. एखादा इंटरफेस अस्तित्वात आहे असे गृहीत धरण्यापूर्वी चेकआउटमधील docs/api-matrix.md वाचा, कारण हा प्रकल्प तिथे स्वतःच्या त्रुटींची नोंद ठेवतो. यामध्ये क्लायंट-साइड कस्टम टूल्सचाही समावेश आहे, ज्यांना सध्याच्या इव्हेंट-रिझल्ट प्रोटोकॉलच्या वर नामनिर्देशित नोंदणीची (named registration) आवश्यकता असते.

साधे 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) प्रवाह असल्यामुळेच लॅपटॉप बंद झाला तरी सेशन टिकून राहते. इव्हेंट्स सर्व्हरवर जतन केलेले असतात, त्यामुळे क्लायंटकडे एकमेव प्रत असण्याऐवजी तो लॉग पुन्हा प्ले करत असतो.

क्रेडेंशियल्स, मेमरी आणि ऑडिट ट्रेल्स डिस्कवर कुठे असतात

रनटाइमच्या मालकीच्या सर्व गोष्टी वर्कस्पेसमध्ये .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 मध्ये राहतात, जे या रनटाइम आणि रॉ मॉडेल कॉल मधील मुख्य फरक आहे: रनटाइमला सेशन्सच्या पलीकडे माहिती लक्षात राहते आणि काय घडले याची नोंद तो ठेवतो.

ही एकच डिरेक्टरी असल्याने, तिचा बॅकअप एकसंधपणे घ्या.

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

प्रथम सर्व्हिस थांबवा. रनटाइम लिहित असताना SQLite डेटाबेस कॉपी केल्यास अशी फाइल तयार होऊ शकते जी रिस्टोर करताना उघडणार नाही, आणि ही गोष्ट तुम्हाला गरज पडेल तेव्हाच समजेल. जर तुम्हाला एजंट YAML गिट (git) मध्ये आणि स्टेट इतरत्र ठेवायची असेल, तर डिप्लॉयमेंट डॉक्युमेंटेशन start वर --data-dir वापरून स्टेट लोकेशन पिन करण्यास सपोर्ट करते.

रिस्टोर करणे ही उलट प्रक्रिया आहे: नवीन सर्व्हरवर तोच टॅग चेकआउट करा, आर्काइव्ह वर्कस्पेसमध्ये अनपॅक करा आणि सर्व्हिस सुरू करा. जर तुम्ही ${OPENAI_API_KEY} फॉर्म वापरला असेल, तर तुमची प्रोव्हायडर की आर्काइव्हमध्ये नसेल, त्यामुळे ती सुरक्षित ठिकाणी ठेवा जिथे ती तुम्हाला पुन्हा मिळेल.

systemd अंतर्गत चालवा

runtime साठी स्वतःचा स्वतंत्र वापरकर्ता (user) तयार करा, जेणेकरून local sandbox mode मधील टूल तुमच्या अधिकारांचा वापर करू शकणार नाही.

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 बायनरी कॉल केली जाते. tagged-source इन्स्टॉलेशनमध्ये अशी बायनरी तयार होत नाही, म्हणून 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

यशस्वी निकालामध्ये status कडून active (running) आणि curl कडून 200 मिळायला हवे. इतर कोणताही निकाल असल्यास, प्रथम journalctl -u sandbase -n 50 आणि त्यानंतर .managed-agents/logs/runtime.log वाचा. enable --now हा महत्त्वाचा भाग आहे, कारण मॅन्युअली सुरू केलेली प्रक्रिया रीबूटनंतर बंद होते.

काय बिघडते आणि तुम्हाला कोणता संदेश दिसेल

npm run build हे npm कडून कोणतीही त्रुटी न येता बंद होते. 1 GB च्या VPS वर TypeScript compile प्रक्रिया kernel च्या out-of-memory killer द्वारे थांबवली जाते, जी npm ऐवजी kernel log मध्ये नोंदवली जाते. journalctl -k | grep -i "out of memory" वापरून याची खात्री करा, जे बंद झालेल्या node प्रक्रियेचे नाव दर्शवणारी ओळ प्रिंट करते. Swap जोडा किंवा मोठ्या instance वर build करून dist/ कॉपी करा.

Error: listen EADDRINUSE: address already in use 127.0.0.1:3000. दुसरी प्रक्रिया आधीच तो पोर्ट वापरत आहे. sudo ss -lntp | grep 3000 त्या प्रक्रियेचे नाव सांगते. एकतर ती प्रक्रिया थांबवा किंवा --port 3001 वापरून runtime सुरू करा आणि proxy अपडेट करा.

डॅशबोर्ड तुमच्या लॅपटॉपवरून लोड होत नाही. हे अपेक्षितच आहे, कारण 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 मुळे अयशस्वी होतात. sandbase वापरकर्ता docker ग्रुपमध्ये नाही. sudo usermod -aG docker sandbase वापरून हे दुरुस्त करा आणि service रीस्टार्ट करा. तुम्ही काय अधिकार दिले आहेत हे समजून घ्या: तो ग्रुप host वर root असतो, त्यामुळे runtime ला स्वतंत्र वापरकर्ता देण्याचा मूळ उद्देश अंशतः निष्फळ ठरतो.

Kubernetes sandboxes Error from server (Forbidden) मुळे अयशस्वी होतात. ServiceAccount कडे pod permissions किंवा exec subresource ची कमतरता आहे. kubectl auth can-i create pods/exec -n <namespace> वापरून थेट तपासा, जे yes किंवा no असे उत्तर देते.

API key जोडल्यानंतर प्रत्येक विनंती 401 त्रुटी देते. पहिली key तयार झाल्यावर authentication सुरू होते आणि ते API सोबतच console ला देखील लागू होते. Authorization: Bearer <key> पाठवा, आणि जर तुमची key हरवली असेल, तर दुसरी तयार करा, कारण secret_key एकदाच दिसते आणि ती वाचनीय स्वरूपात साठवली जात नाही.

MCP सर्व्हरची साधने (tools) सत्रात दिसत नाहीत. mcp_servers मधील name च्या तुलनेत tools ब्लॉक मधील mcp_server_name तपासा, त्यानंतर curl -i <url> वापरून सर्व्हरवरून runtime त्या URL पर्यंत पोहोचू शकतो का ते तपासा. URL-प्रकारचा MCP सर्व्हर ही एक network dependency आहे आणि VPS तुमच्या लॅपटॉपपेक्षा वेगळ्या पद्धतीने नावे resolve करतो आणि traffic route करतो.

FAQ

मी OpenAI किंवा Anthropic की (key) शिवाय SandBase Harness चालवू शकतो का?

हो, जर तुमच्याकडे OpenAI-सुसंगत (compatible) एंडपॉईंट असेल तर तुम्ही हे करू शकता. रनटाइम OpenAI, Anthropic आणि OpenAI-सुसंगत प्रोव्हाइडर्सना सपोर्ट करतो, त्यामुळे OpenAI API वर चालणारा कोणताही स्थानिक सर्व्हर काम करेल. .managed-agents/config.yaml मध्ये वर्कस्पेस प्रोव्हाइडर सेट करा आणि api_key व एंडपॉईंटला त्याकडे निर्देशित करा. रनटाइममध्ये स्वतःचे कोणतेही मॉडेल समाविष्ट नसते, त्यामुळे कॉलला उत्तर देण्यासाठी काहीतरी असणे आवश्यक आहे.

रनटाइमला पब्लिक पोर्टवर उघडणे सुरक्षित आहे का?

ज्या स्थितीत ते इन्स्टॉल होते, तसे ते सुरक्षित नाही. हे 127.0.0.1:3000 वर बाइंड होते आणि ऑथेंटिकेशन बंद असताना सुरू होते. यावर उपाय म्हणजे केवळ बाइंड ॲड्रेस बदलणे नव्हे. एक API की तयार करा किंवा MANAGED_AGENTS_API_KEY सेट करा, जेणेकरून बेअरर-टोकन ऑथेंटिकेशन सुरू होईल. त्यानंतर TLS साठी समोर nginx किंवा Caddy ठेवा आणि फायरवॉलवर पोर्ट 3000 बंद ठेवा, जेणेकरून प्रवेश फक्त प्रॉक्सीद्वारेच मिळेल.

लोकल, Docker आणि Kubernetes सँडबॉक्समध्ये काय फरक आहे?

local टूल कोडला होस्टवर रनटाइमच्या चाइल्ड प्रोसेस म्हणून चालवते, ज्याला रनटाइम वापरकर्त्याचे अधिकार असतात आणि कोणतेही आयसोलेशन नसते. docker प्रत्येक सत्राला स्वतःचे कंटेनर, स्वतःची फाइलसिस्टम, मेमरी लिमिट आणि CPU शेअर देते आणि सत्र संपल्यावर ते काढून टाकते. kubernetes सत्राला पॉड (pod) म्हणून चालवते आणि ते kubectl exec द्वारे नियंत्रित करते. यासाठी रनटाइम इमेजमध्ये kubectl आणि पॉड्सवर RBAC तसेच टार्गेट नेमस्पेसमध्ये exec सब-रिसोर्सची आवश्यकता असते.

मला नेमके कशाचा बॅकअप घेणे आवश्यक आहे?

वर्कस्पेस मधील .managed-agents/ डिरेक्टरीचा बॅकअप घ्या. यामध्ये config.yaml, एजंट्स, सत्रे, क्रेडेंशियल व्हॉल्ट एन्ट्रीज आणि मेमरी एन्ट्रीज असलेला data.db SQLite डेटाबेस, तसेच अपलोड केलेल्या फाइल्स, स्किल पॅकेजेस आणि सत्राचे स्नॅपशॉट्स असतात. कॉपी करण्यापूर्वी सर्व्हिस थांबवा, जेणेकरून आर्काइव्ह तयार होत असताना SQLite मध्ये डेटा लिहिला जाणार नाही. ${OPENAI_API_KEY} म्हणून संदर्भित केलेले प्रोव्हाइडर API की बॅकअपमध्ये नसतात, त्यामुळे ते स्वतंत्रपणे जतन करा.

main ऐवजी v0.3.2 टॅग क्लोन का करावा?

टॅग म्हणजे एक निश्चित ट्री (tree) असते, त्यामुळे तुम्ही ज्या कॉन्फिग की आणि CLI कमांड्सबद्दल वाचता, त्या तुम्हाला प्रत्यक्षात मिळतात. main मध्ये बदल होत असतात आणि मार्गदर्शिका लिहिल्याच्या वेळेपासून ते तुम्ही ती अंमलात आणण्याच्या वेळेपर्यंत एखादी कॉन्फिग की रिनेम होऊ शकते. प्रकल्प असाही इशारा देतो की npm वरील अनस्कोप केलेले managed-agents पॅकेज हा हा प्रकल्प नाही, त्यामुळे npx managed-agents काहीतरी असंबद्ध इन्स्टॉल करेल. रिलीज v0.3.1 प्रामुख्याने त्या npm क्विक स्टार्टला पिन केलेल्या टॅग्ड-सोर्स पाथने बदलण्यासाठी अस्तित्वात आहे.

#ai-agents#mcp#self-hosting#sandboxing#anthropic-sdk