SandBase agent runtime को self-host कैसे करें
SandBase Harness v0.3.8 को अपने VPS पर सेटअप करें। इस गाइड में tagged install, agent YAML कॉन्फ़िगरेशन, MCP servers और Anthropic SDK को अपने सर्वर से जोड़ने की विधि जानें।
SandBase agent runtime को self-host करने पर आपको क्या मिलता है
SandBase agent runtime को self-host करने का अर्थ है SandBase Harness को अपने स्वयं के सर्वर पर चलाना, ताकि sessions, credentials, memory और audit trails किसी और के सर्वर के बजाय आपकी डिस्क पर सुरक्षित रहें। यह एक Node service है। यह 127.0.0.1:3000 पर listen करती है, एक /v1 HTTP API और वेब कंसोल प्रदान करती है, और अपनी state को आपकी agent फाइलों के साथ SQLite में रखती है।
/v1 API को Claude Managed Agents (CMA) के आधार पर तैयार किया गया है, जो कि एक hosted managed-agent API है। यही कारण है कि यह runtime दोनों दिशाओं में उपयोगी है: आप Anthropic SDK का उपयोग करके कोड लिख सकते हैं और इसके baseURL को अपने सर्वर की ओर निर्देशित कर सकते हैं, और बाद में उसी कोड को किसी hosted deployment पर ले जा सकते हैं।
SandBase Harness के साथ कोई model नहीं आता है। यह एक model को call करता है। 12 October 2026 तक, यह OpenAI, Anthropic, MiniMax और OpenAI-compatible endpoints को support करता है, जिसमें self-hosted gateways और DeepSeek V4 जैसे providers शामिल हैं। MiniMax को v0.3.3 में एक first-class provider के रूप में जोड़ा गया था, जिसमें global या mainland China endpoint चुनने का विकल्प है। आपको अभी भी अपना API key प्रदान करना होगा, या एक ऐसा local सर्वर उपयोग करना होगा जो OpenAI API का समर्थन करता हो।
शुरू करने से पहले आपकी आवश्यकताएं
- कम से कम 2 GB RAM वाला Ubuntu 24.04 पर चलने वाला एक VPS। TypeScript build इंस्टॉलेशन का सबसे भारी चरण है।
- Node.js 22 या नया वर्ज़न, और npm 10 या नया वर्ज़न। ये दोनों प्रोजेक्ट द्वारा निर्धारित अनिवार्य न्यूनतम आवश्यकताएं हैं।
git, साथ ही जिस मॉडल प्रोवाइडर का आप उपयोग करने की योजना बना रहे हैं, उसकी एक API key।- Docker, लेकिन केवल तभी यदि आप प्रति-सत्र (per-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 -vnode -v को v22 या उससे अधिक प्रिंट करना चाहिए और npm -v को 10 या उससे अधिक प्रिंट करना चाहिए। यदि node -v अभी भी v18.19.1 प्रिंट करता है, तो डिस्ट्रीब्यूशन पैकेज अभी भी इंस्टॉल है और PATH पर प्राथमिकता ले रहा है। आगे बढ़ने से पहले इसे हटा दें, क्योंकि बिल्ड उस node के विरुद्ध चलता है जिसे शेल (shell) सबसे पहले ढूंढता है।
v0.3.8 tag से SandBase इंस्टॉल करें
हमेशा किसी tag से इंस्टॉल करें, कभी भी बदलते हुए branch से नहीं। main का bare clone करने पर आपको वह कोड मिलता है जो एक घंटे पहले ही push हुआ हो, और नीचे दिए गए config keys शायद उसके साथ मेल न खाएं। 30 August 2026 को प्रकाशित v0.3.8, 12 October 2026 तक का वर्तमान tag है, और प्रोजेक्ट के अपने इंस्टॉलेशन डॉक्यूमेंट में भी इसी tag को पिन किया गया है।
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 buildnpm install के बजाय npm ci का उपयोग करें। ci कमिट किए गए lockfile में दर्ज सटीक वर्ज़न को इंस्टॉल करता है, जिससे आपका ट्री वही रहता है जिसका मेंटेनर्स ने परीक्षण किया है। npm install को नए वर्ज़न रिज़ॉल्व करने की अनुमति होती है, और इसी तरह एक पिन किया गया tag चुपचाप पिन रहना बंद कर देता है।
अब एक workspace बनाएं। workspace एक अलग डायरेक्टरी है जो आपकी agent फाइलों और सभी runtime स्टेट को रखती है। इसे सोर्स चेकआउट के बाहर रखने का मतलब है कि आप अपने डेटा को छुए बिना एक नया 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 startinit, workspace में एक .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 से install न करें
Project के अपने installation documentation में यह स्पष्ट लिखा है: npm पर दिखने वाला unscoped managed-agents package इस project का नहीं है। इसलिए npx managed-agents और npm install -g managed-agents चलाने पर आपको वह runtime नहीं मिलेगा जिसकी आपको आवश्यकता है। जब तक maintainers किसी आधिकारिक scoped package की घोषणा नहीं करते, तब तक इसे tagged GitHub source से ही install करें। project के इतिहास में यह कोई छोटी-मोटी बात नहीं है: v0.3.1 का अस्तित्व मुख्य रूप से पुराने npm quick start को हटाकर उसे pinned tagged-source path से बदलने के लिए ही है।
Workspace को एक model provider पर point करें
init, .managed-agents/config.yaml लिखता है। पूरे workspace के लिए एक provider configure किया जाता है, और फिर व्यक्तिगत agents concrete 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 से value लेता है, इसलिए key config file से बाहर रहती है और उस file के आपके द्वारा लिए गए किसी भी backup में नहीं जाती। इसे एक ऐसी environment file में रखें जिसे केवल root ही पढ़ सके, क्योंकि systemd privileges drop करने से पहले EnvironmentFile= को root के रूप में पढ़ता है।
sudo install -d -m 750 /etc/sandbase
sudo touch /etc/sandbase/runtime.env
sudo chmod 600 /etc/sandbase/runtime.envउस file को एक editor में खोलें और एक line जोड़ें, OPENAI_API_KEY=sk-...। Provider keys यहीं होनी चाहिए। वे secrets जिनका उपयोग एक agent session के दौरान करता है, उन्हें runtime के credential vaults में होना चाहिए, जो एक अलग समस्या है और जिसका blast radius भी अलग है, और AI agents से secrets को दूर रखना को पढ़ना उचित है, इससे पहले कि आप किसी production token को कहीं भी paste करें।
Agent YAML: mcp_servers, tools और permission policies
Agents को workspace के agents/ directory में YAML files के रूप में define किया जाता है। runtime का यह वह हिस्सा है जहाँ आप वास्तव में समय बिताएंगे। जब आप एक बार हाथ से छोटा agent loop लिख लेंगे, तो ये keys अधिक स्पष्ट हो जाएंगी, क्योंकि प्रत्येक key उस चीज़ का एक नियंत्रण है जिसे आप अन्यथा खुद कोड कर रहे होते: system prompt, tool list, और tool चलने से पहले होने वाली जाँच।
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 के साथ agent को print करना चाहिए। यदि list इसे नहीं दिखाता है, तो file parse नहीं हुई है, और .managed-agents/logs/runtime.log वह स्थान है जहाँ इसका कारण लिखा होता है।
mcp_servers, MCP (model context protocol) endpoints को declare करता है। type: url का अर्थ है कि runtime किसी अन्य स्थान पर चल रहे server से HTTP के माध्यम से बात करता है, इसलिए आप जो कुछ भी पहले से operate करते हैं, वह यहाँ काम करता है, जिसमें runtime के साथ उसी VPS पर hosted MCP servers भी शामिल हैं। Web search आमतौर पर वह पहला tool है जिसे लोग इस्तेमाल करते हैं, और agent को अपना SearXNG instance देना शुरू करने से पहले इसे पढ़ना उचित है, क्योंकि जो tool अजनबियों द्वारा लिखे गए pages लौटाता है, वह untrusted text को सीधे model के context में डाल देता है। अधिक सुरक्षित शुरुआत इसके विपरीत है, यानी आपके अपने डेटा पर एक read-only endpoint, जो कि openGym द्वारा workout tracker के साथ expose किया जाता है, ताकि agent आपके training history के बारे में सवालों के जवाब दे सके, बिना उसे rewrite किए।
Server को declare करने से उसके tools agent को नहीं मिलते हैं। tools list ऐसा करती है, एक mcp_toolset entry के माध्यम से जिसका mcp_server_name ऊपर दिए गए name से मेल खाता है। यदि agent ऐसा व्यवहार करता है जैसे MCP tools मौजूद ही नहीं हैं, तो कहीं और देखने से पहले उन दोनों strings की अक्षर-दर-अक्षर तुलना करें।
agent_toolset_20260401, built-in tool set है। दिनांकित suffix एक schema version है, इसलिए इससे जुड़ा agent उन tool definitions को बनाए रखता है जिनके आधार पर इसे लिखा गया था। default_config, set के प्रत्येक tool के लिए policy set करता है, और configs के अंतर्गत प्रत्येक entry नाम के आधार पर एक tool को override करती है, जैसे उदाहरण में bash है।
permission_policy वह जगह है जहाँ एक runtime, bare model call की तुलना में अपनी उपयोगिता साबित करता है। always_ask session को pause करता है और call चलने से पहले human approval का इंतज़ार करता है। always_allow इसे अनुमति देता है। bash को always_ask पर set करने का मतलब है कि agent आपके द्वारा सटीक command देखे बिना shell command नहीं चला सकता, जो कि वही नियंत्रण है जिसे आप VPS पर सुरक्षित रूप से Claude Code चलाते समय अपनाएंगे। यदि आप DeepSeek Harness भी चलाते हैं, तो वही नियंत्रण वहाँ YAML keys के बजाय add-ons के रूप में आते हैं, और budgets को सीमित करने और tool calls को gate करने वाले plugins इस block के सबसे करीबी विकल्प हैं।
चार सैंडबॉक्स मोड, और प्रत्येक का उपयोग कब करें
कोड निष्पादित करने वाले टूल कॉल एक सैंडबॉक्स के भीतर चलते हैं। बैकएंड का चयन प्रति वातावरण किया जाता है, जो वातावरण के config ऑब्जेक्ट में sandbox_provider के माध्यम से होता है, या कंसोल में Settings के अंतर्गत, Sandbox एडिटर में Advanced के भीतर वर्कस्पेस डिफॉल्ट के रूप में सेट किया जाता है। वातावरण POST /v1/environments पर API के माध्यम से बनाए जाते हैं।
local कोड को रनटाइम की चाइल्ड प्रोसेस के रूप में, होस्ट पर, रनटाइम के स्वयं के उपयोगकर्ता के रूप में चलाता है। जब कोई वातावरण किसी बैकएंड का नाम नहीं देता है, तो यह डिफॉल्ट होता है, और यह तब उचित है जब आप एकमात्र उपयोगकर्ता हों और एजेंट केवल उन फाइलों को पढ़ता है जिनके आप स्वामी हैं। एक वातावरण जो ऐसे बैकएंड का नाम देता है जिसे रनटाइम लोड नहीं कर सकता, उसे चुपचाप यहाँ चलाने के बजाय अस्वीकार कर दिया जाता है। यह आइसोलेशन नहीं है। जो टूल कॉल फाइलों को हटाता है, वह आपकी फाइलों को हटा देता है, और जो टूल कॉल /etc/sandbase/runtime.env को पढ़ता है, वह आपकी प्रोवाइडर की (provider key) को पढ़ लेता है।
docker प्रति सत्र एक कंटेनर शुरू करता है।
{
"sandbox_provider": "docker",
"image": "node:22-slim",
"resources": { "memory": "1g", "cpu": 1 }
}सत्र को अपना स्वयं का फाइलसिस्टम मिलता है, और कंटेनर को सत्र के साथ हटा दिया जाता है। मेमोरी और CPU कैप इस मोड का हिस्सा नहीं हैं: रनटाइम कंटेनर में --memory और --cpus केवल तभी जोड़ता है जब वातावरण का resources ब्लॉक उन्हें सेट करता है, जैसा कि उदाहरण में है, इसलिए उस ब्लॉक के बिना वातावरण को बिना किसी सीमा वाला कंटेनर मिलता है। image को छोड़ दें और रनटाइम ghcr.io/sandbaseai/sandbase-harness-sandbox:latest का उपयोग करेगा। जब कोई एजेंट ऐसा कोड चलाता है जिसे आपने नहीं लिखा है, तो तुरंत इस पर स्विच करें। इसकी लागत यह है कि रनटाइम के उपयोगकर्ता को Docker सॉकेट तक पहुंच की आवश्यकता होती है, और docker समूह की सदस्यता होस्ट पर root के बराबर है। प्रति-सत्र कंटेनर एक कंटेनर प्रति रन वाले सेल्फ-होस्टेड एजेंट सैंडबॉक्स के समान ही होते हैं, इसलिए एक एस्केप्ड प्रोसेस क्या एक्सेस कर सकती है, इसके बारे में तर्क यहाँ अपरिवर्तित लागू होता है।
kubernetes सत्र वर्कलोड को पॉड (pod) के रूप में चलाता है और इसे kubectl exec और kubectl cp के साथ संचालित करता है। रनटाइम इमेज में kubectl का होना आवश्यक है, और इसके ServiceAccount को टारगेट नेमस्पेस में पॉड्स को बनाने, हटाने, प्राप्त करने, सूचीबद्ध करने और देखने के लिए RBAC (role-based access control) अनुमति की आवश्यकता होती है, साथ ही exec सब-रिसोर्स की भी। यह मोड सेटअप के लायक तभी है यदि आप पहले से ही एक क्लस्टर चला रहे हैं।
self-hosted worker को Settings में remote और वातावरण में self_hosted नाम दिया गया है, और यह इस बॉक्स पर टूल कोड बिल्कुल नहीं चलाता है। रनटाइम काम को एक कतार (queue) में डाल देता है, और एक बाहरी वर्कर, जिसे Settings से वर्कर API URL और की (key) दी जाती है, होस्ट के बाहर कतारबद्ध आइटम का दावा करता है और उन्हें पूरा करता है। यह तब उपयुक्त है जब कोड को ऐसी मशीन पर चलना चाहिए जिसमें आपकी प्रोवाइडर की (provider key) न हो। संसाधन सीमाएं केवल docker और kubernetes द्वारा सम्मानित की जाती हैं, इसलिए वर्कर को सीमित करना वर्कर होस्ट का काम है।
Runtime को 127.0.0.1 पर क्यों bind किया गया है?
ऐसा इसलिए है क्योंकि यह authentication बंद होने के साथ शुरू होता है। जब कम से कम एक API key मौजूद होती है, तब runtime bearer-token authentication को सक्षम करता है, और एक नया init कोई key नहीं बनाता है। उस डिफ़ॉल्ट स्थिति में 0.0.0.0 पर bind करने से एक unauthenticated agent runtime, जिसमें shell tools और आपका provider key मौजूद है, सार्वजनिक इंटरनेट पर आ जाएगा।
इसलिए जब आप चाहते हैं कि यह सुलभ हो, तो bind address को न बदलें और दो अन्य काम करें।
सबसे पहले, authentication को चालू करें। service environment file में MANAGED_AGENTS_API_KEY सेट करें, या POST /v1/api-keys के साथ एक key बनाएँ, जो एक बार secret_key फ़ील्ड लौटाता है और उसे फिर कभी नहीं दिखाता है। इसके बाद clients हर API request पर Authorization: Bearer <key> भेजते हैं, या x-api-key के रूप में वही key भेजते हैं, लेकिन कभी भी दोनों एक साथ नहीं। key API की सुरक्षा करती है, console की नहीं: dashboard के पेज और उनकी static assets बिना key के लोड हो जाते हैं, और ऐसा ही /v1/x/health और /v1/x/metrics के साथ भी होता है। एक key एक shared identity है, इसलिए यदि आप वास्तव में प्रत्येक टीम के सदस्य के लिए एक अलग sandboxed agent चाहते हैं, जहाँ provider keys एक ही gateway में हों, तो OneCLI इस संरचना के लिए बनाया गया है।
दूसरा, सामने एक 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;
}
}उनमें से दो लाइनें केवल सजावट नहीं हैं। proxy_buffering off महत्वपूर्ण है क्योंकि sessions server-sent events (SSE) के माध्यम से stream होते हैं, और buffering चालू होने पर, nginx response को तब तक रोक कर रखता है जब तक उसका buffer भर न जाए। इस कारण जब agent काम कर रहा होता है तो console पर कुछ नहीं दिखता और अंत में सब कुछ एक साथ दिखाई देता है। proxy_read_timeout 3600s महत्वपूर्ण है क्योंकि डिफ़ॉल्ट समय 60 सेकंड है, इसलिए यदि कोई stream एक मिनट से अधिक समय तक शांत रहती है, तो proxy उसे बीच में ही बंद कर देता है, और यह विफलता runtime के क्रैश होने जैसी दिखती है।
Firewall पर 22 और 443 पोर्ट खोलें। 3000 को बंद रखें, क्योंकि proxy loopback के माध्यम से उस तक पहुँचता है और बॉक्स के बाहर किसी भी चीज़ को उस तक नहीं पहुँचना चाहिए। चूँकि /v1/x/metrics बिना key के जवाब देता है, यदि आप runtime metrics को प्रकाशित नहीं करना चाहते हैं, तो server block में location = /v1/x/metrics { return 404; } जोड़ें।
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'
});यह उन beta headers को भी स्वीकार करता है जिन्हें Claude Managed Agents clients भेजते हैं, जैसे anthropic-beta: managed-agents-2026-04-01 और anthropic-beta: agent-memory-2026-07-22। बिना compatibility header वाली एक सामान्य request को local caller के रूप में स्वीकार किया जाता है। जो request x-api-key, anthropic-version या anthropic-beta के साथ आती है, उसे hosted नियमों के अधीन रखा जाता है: version 2023-06-01 और managed-agents beta आवश्यक हैं, सिवाय इसके कि /v1/memory_stores routes को agent-memory beta की आवश्यकता होती है और वे दोनों के संयोजन को अस्वीकार कर देते हैं। ये headers इसलिए मौजूद हैं ताकि hosted deployment के लिए लिखा गया code यहाँ बिना किसी बदलाव के चल सके।
Compatibility काफी हद तक समान है, लेकिन पूर्ण नहीं है। किसी surface के अस्तित्व को मानने से पहले checkout में docs/api-matrix.md को पढ़ें, क्योंकि project वहाँ अपनी कमियों का दस्तावेजीकरण करता है, जिसमें 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 सर्वर पर सुरक्षित रहते हैं, इसलिए client केवल एक log को replay कर रहा होता है, न कि एकमात्र copy को अपने पास रख रहा होता है।
जहाँ क्रेडेंशियल्स, मेमोरी और ऑडिट ट्रेल्स डिस्क पर रहते हैं
रनटाइम के स्वामित्व वाली हर चीज़ वर्कस्पेस में .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} फॉर्म का उपयोग किया है तो आपका प्रोवाइडर की (provider key) आर्काइव में नहीं होगा, इसलिए उसे कहीं ऐसी जगह रखें जहाँ वह आपके पास सुरक्षित रहे।
इसे systemd के अंतर्गत चलाएं
Runtime को अपना स्वयं का user दें ताकि local sandbox mode में कोई tool call आपके रूप में कार्य न कर सके।
sudo adduser --system --group --no-create-home --home /opt/sandbase sandbase
sudo chown -R sandbase:sandbase /opt/sandbaseइसे /etc/systemd/system/sandbase.service के रूप में save करें।
[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.targetProject का अपना deployment उदाहरण PATH पर एक managed-agents binary को call करता है। Tagged-source install इसे create नहीं करता है, इसलिए 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 वह हिस्सा है जो मायने रखता है, क्योंकि हाथ से start की गई 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" से करें, जो उस प्रक्रिया का नाम दिखाता है जिसे killed node किया गया है। Swap जोड़ें, या किसी बड़े instance पर build करें और dist/ को copy करें।
Error: listen EADDRINUSE: address already in use 127.0.0.1:3000। कोई अन्य प्रक्रिया पहले से ही उस port का उपयोग कर रही है। sudo ss -lntp | grep 3000 उसका नाम बताता है। या तो उस प्रक्रिया को रोकें या 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 के साथ विफल हो जाते हैं। sandbase user, docker group में नहीं है। इसे sudo usermod -aG docker sandbase के साथ ठीक करें और service को restart करें। यह समझें कि आपने क्या अनुमति दी है: वह group host पर root के समान है, इसलिए यह उस कारण को निष्प्रभावी कर देता है जिसके लिए आपने runtime को उसका अपना user दिया था।
Kubernetes sandboxes Error from server (Forbidden) के साथ विफल हो जाते हैं। ServiceAccount में pod permissions या exec subresource की कमी है। इसकी जाँच सीधे kubectl auth can-i create pods/exec -n <namespace> से करें, जो yes या no का उत्तर देता है।
API key जोड़ने के बाद API requests 401 error देती हैं। पहली key बनते ही authentication चालू हो जाता है। यह API को cover करता है लेकिन console को नहीं: dashboard pages और उनकी static assets public रहती हैं, इसलिए console load तो होता रहता है लेकिन अपने API calls के लिए key की मांग करता है। Authorization: Bearer <key> या x-api-key: <key> में से केवल एक भेजें, दोनों नहीं, क्योंकि दोनों headers वाली request को authentication बंद होने पर भी 401 error के साथ reject कर दिया जाता है। यदि आप key खो चुके हैं, तो दूसरी बनाएँ, क्योंकि secret_key केवल एक बार दिखाई जाती है और केवल hash के रूप में store की जाती है।
MCP server के tools session में दिखाई नहीं देते। tools block में मौजूद mcp_server_name की तुलना mcp_servers में मौजूद name से करें, फिर जाँचें कि क्या runtime सर्वर से ही उस URL तक curl -i <url> के माध्यम से पहुँच सकता है। URL-प्रकार का MCP server एक network dependency है, और एक VPS आपके laptop की तुलना में नामों को अलग तरह से resolve करता है और traffic को अलग तरह से route करता है।
FAQ
क्या मैं OpenAI या Anthropic key के बिना SandBase Harness चला सकता हूँ?
हाँ, MiniMax key या OpenAI-compatible endpoint के साथ। Runtime OpenAI, Anthropic, MiniMax और OpenAI-compatible providers को support करता है, इसलिए OpenAI API का उपयोग करने वाला कोई भी local server काम करेगा। .managed-agents/config.yaml में workspace provider सेट करें और api_key तथा endpoint को उस पर point करें। Runtime में अपना कोई model शामिल नहीं है, इसलिए calls का उत्तर देने के लिए किसी न किसी स्रोत की आवश्यकता होती है।
क्या runtime को public port पर expose करना सुरक्षित है?
डिफ़ॉल्ट इंस्टॉलेशन के साथ ऐसा नहीं है। यह 127.0.0.1:3000 पर bind होता है और बिना authentication के शुरू होता है, और इसका समाधान केवल bind address बदलना नहीं है। एक API key बनाएँ, या MANAGED_AGENTS_API_KEY सेट करें, ताकि API के लिए bearer-token authentication चालू हो जाए। इसके बाद TLS के लिए nginx या Caddy को सामने रखें, और firewall पर port 3000 को बंद रखें ताकि अंदर आने का एकमात्र रास्ता proxy के माध्यम से ही हो।
Local, Docker और Kubernetes sandboxes में क्या अंतर है?
local टूल कोड को host पर runtime के child process के रूप में चलाता है, जिसमें runtime user की अनुमतियाँ होती हैं और कोई isolation नहीं होती। docker प्रत्येक session को अपना container और filesystem देता है और session समाप्त होने पर उसे हटा देता है। यह memory और CPU को केवल तभी सीमित करता है यदि environment का resources ब्लॉक उन्हें सेट करता है। kubernetes session को pod के रूप में चलाता है और इसे kubectl exec के साथ संचालित करता है, जिसके लिए runtime image के अंदर kubectl और pods पर RBAC के साथ-साथ target namespace में exec subresource की आवश्यकता होती है। एक चौथा backend, self-hosted worker, काम को एक external worker के लिए queue में डाल देता है ताकि कोड host से बाहर चल सके।
मुझे वास्तव में किसका बैकअप लेने की आवश्यकता है?
Workspace में स्थित .managed-agents/ directory का। इसमें config.yaml, agents, sessions, credential vault entries और memory entries के साथ data.db SQLite database, तथा upload की गई फाइलें, skill packages और session snapshots होते हैं। इसे copy करने से पहले service को रोक दें ताकि archive बनते समय SQLite में कोई डेटा न लिखा जाए। ${OPENAI_API_KEY} के रूप में संदर्भित Provider API keys बैकअप के अंदर नहीं होती हैं, इसलिए उन्हें अलग से सुरक्षित रखें।
Main के बजाय v0.3.8 tag को clone क्यों करें?
Tag एक निश्चित tree है, इसलिए जिन config keys और CLI commands के बारे में आप पढ़ते हैं, वे वही होते हैं जो आपको वास्तव में मिलते हैं। main में बदलाव होते रहते हैं, और गाइड लिखे जाने तथा आपके द्वारा उसे चलाने के बीच config key का नाम बदला जा सकता है। प्रोजेक्ट यह भी चेतावनी देता है कि npm पर unscoped managed-agents पैकेज यह प्रोजेक्ट नहीं है, इसलिए npx managed-agents कुछ असंबंधित इंस्टॉल कर देगा। Release v0.3.1 मुख्य रूप से उस npm quick start को pinned tagged-source path से बदलने के लिए मौजूद है।