OneCLI को self-host कैसे करें: सेटअप और सर्वर गाइड
OneCLI को अपने VPS पर self-host करने का पूरा तरीका जानें। Docker Compose और PostgreSQL का उपयोग करें। प्रति agent 2 GiB RAM की आवश्यकता को देखते हुए सर्वर का सही चुनाव करें।
OneCLI को self-host करने पर आपको क्या मिलता है
OneCLI को self-host करें और आपकी टीम के प्रत्येक व्यक्ति को अपना स्वयं का agent मिलता है। हर एक agent अपने स्वयं के sandbox में चलता है और API keys एक gateway में सुरक्षित रहती हैं जिसे agents कभी नहीं पढ़ पाते। इसका इंस्टॉलेशन एक Docker Compose stack है जिसके पीछे PostgreSQL चलता है, जो http://localhost:10254 पर उपलब्ध है। एक वास्तविक सर्वर (real box) की योजना बनाएँ। प्रलेखित डिफ़ॉल्ट के अनुसार प्रति agent sandbox 2 GiB मेमोरी की सीमा है, इसलिए base stack और agents की वास्तविक working memory के लिए अलग-अलग बजट रखें।
उस stack में आठ घटक (pieces) शामिल हैं, और यह जानना कि कौन सा क्या है, इस गाइड के बाकी हिस्सों को पढ़ना आसान बनाता है।
- Web dashboard (Next.js), port
10254। Agent निर्माण, चैट, मेमोरी और स्किल्स एडिटिंग, कनेक्शन और सीक्रेट्स। - API server, port
10256। कंट्रोल प्लेन: डेटाबेस, बातचीत का प्रबंधन, वर्क क्यू। - Rust gateway, port
10255। Agents से बाहर जाने वाले अनुरोधों को इंटरसेप्ट करता है और क्रेडेंशियल्स इंजेक्ट करता है। - Runner। README इसे उस घटक के रूप में वर्णित करता है जो "agent sandboxes को शुरू करता है, रोकता है और समाप्त करता है। यह केवल आउटबाउंड है और डेटाबेस को कभी नहीं छूता है।"
- Sandbox Supervisor। README इसे "प्रत्येक sandbox के अंदर चलने वाले" घटक के रूप में वर्णित करता है, जो एक वेंडर-न्यूट्रल हार्नेस इंटरफ़ेस का उपयोग करता है ताकि agent runtime को बदला जा सके।"
- SSH terminator, port
10257। README इसे "SSH फ्रंट डोर" कहता है: यह API द्वारा जारी किए गए अल्पकालिक प्रमाणपत्रों (short-lived certificates) के साथ SSH को समाप्त करता है और प्रत्येक सत्र को agent के sandbox से जोड़ता है। यह उसीrunnerप्रोफ़ाइल के तहत चलता है जैसे runner। - Channel adapter। एक daemon जो Slack app को कनेक्ट करता है, ताकि एक agent अपने नाम से चैनल्स और DM में उत्तर दे सके।
- PostgreSQL। प्रदान की गई compose फ़ाइल
postgres:18-alpineकोpgdataवॉल्यूम के साथ चलाती है।
नाम CLI है, लेकिन यह एक सर्वर प्रोडक्ट है
OneCLI एक सर्वर प्लेटफॉर्म है। इसका नाम एक ऐसे कमांड लाइन टूल की ओर इशारा करता है जिसे आप लैपटॉप पर इंस्टॉल करते हैं, लेकिन इस गाइड में जिस चीज़ की बात हो रही है, उसके लिए यह धारणा गलत है। एक अलग कमांड लाइन क्लाइंट onecli/onecli-cli रिपॉजिटरी में मौजूद है, और यह एक लोकल कोडिंग एजेंट के ट्रैफिक को गेटवे के माध्यम से रूट करता है। आप यहाँ जो डिप्लॉय कर रहे हैं, वह एक मल्टी-यूज़र वेब एप्लिकेशन है: इसमें संगठनों और आमंत्रणों वाली एक अकाउंट सिस्टम, बातचीत और सीक्रेट्स का डेटाबेस, और कंटेनर स्टार्ट करने वाला एक रनर शामिल है।
पूरा डिज़ाइन प्रति-व्यक्ति (per-person) मॉडल पर आधारित है। README के अनुसार: "आप प्रत्येक व्यक्ति के लिए एक एजेंट बनाते हैं, प्रत्येक एजेंट को उसकी ज़रूरत के अनुसार एक्सेस देते हैं, और यह एक सैंडबॉक्स में काम करता है, जिसे एक ऐसे गेटवे के माध्यम से रूट किया जाता है जो क्रेडेंशियल्स को इंजेक्ट करता है और आपकी पॉलिसी को लागू करता है।" प्रत्येक एजेंट का अपना फाइलसिस्टम और शेल, अपना बातचीत का पेज, प्लेटफॉर्म द्वारा सुरक्षित रखी गई मेमोरी, और आपके द्वारा एक बार लिखे गए स्किल्स होते हैं। क्रेडेंशियल्स सामान्य सेटअप से विपरीत तरीके से काम करते हैं। प्रत्येक व्यक्ति के एनवायरनमेंट में API key कॉपी करने के बजाय, आप की (key) को एक बार स्टोर करते हैं और इसे उन एजेंटों को प्रदान करते हैं जिन्हें इसका उपयोग करने की अनुमति है।
शुरू करने से पहले सिस्टम की आवश्यकताएं
- Docker, Compose plugin के version 2.24.0 या उससे नए के साथ। प्रदान की गई compose file में
env_filemappings के साथrequired: falseका उपयोग किया गया है, जिसे Docker 2.24.0 से सपोर्ट करता है। इसके migration comments में 2.19 की न्यूनतम सीमा का उल्लेखup --waitके तहत one-shot dependencies के लिए किया गया है, लेकिन यह इस फाइल की optional environment files को कवर नहीं करता है। - Memory, जो कि मुख्य बाधा है। कोई भी प्लान चुनने से पहले नीचे दिए गए sizing सेक्शन को पढ़ें।
- खाली loopback ports
10254,10255,10256,10257और5432। Port10257SSH का मुख्य द्वार है, जो इस गाइड द्वारा सक्षम किए गएrunnerप्रोफाइल के साथ शुरू होता है।
आपको स्वयं PostgreSQL इंस्टॉल करने की आवश्यकता नहीं है: compose file इसे एक सर्विस के रूप में चलाती है। नीचे दिए गए सेटअप विज़ार्ड के लिए होस्ट पर Node.js और pnpm की आवश्यकता है। कोड पर काम करने के लिए भी mise का उपयोग किया जाता है ताकि toolchain को पिन किया जा सके, जिसमें gateway के लिए Rust भी शामिल है।
आपके VPS पर कितने agent sandboxes आ सकते हैं?
Runner का अपना documentation अनुमान के बजाय वास्तविक संख्याएँ देता है। प्रत्येक sandbox की सीमा 2048 MB मेमोरी (RUNNER_SANDBOX_MEMORY_MB), एक CPU (RUNNER_SANDBOX_CPUS) और 512 processes (RUNNER_SANDBOX_PIDS) है। Concurrency की सीमा 4 (RUNNER_MAX_SANDBOXES) है, और documentation इस सीमा को पूरा करने के लिए base stack के अलावा लगभग 10 GiB खाली मेमोरी की सिफारिश करता है।
इस चार्ट के पीछे का डेटा
[
{
"plan": "2 GB box",
"ram_gb": 2,
"sandbox_slots": 0
},
{
"plan": "4 GB box",
"ram_gb": 4,
"sandbox_slots": 1
},
{
"plan": "8 GB box",
"ram_gb": 8,
"sandbox_slots": 3
},
{
"plan": "16 GB box",
"ram_gb": 16,
"sandbox_slots": 7
},
{
"plan": "32 GB box",
"ram_gb": 32,
"sandbox_slots": 15
}
]ये slot counts अंकगणितीय हैं, न कि कोई benchmark: कुल मेमोरी में से PostgreSQL और अन्य long-running services के लिए लगभग 2 GB घटाकर, उसे 2 GiB sandbox cap से विभाजित किया जाता है। इस आधार पर 2 GB box में 0 sandboxes का बजट उनकी पूरी मेमोरी क्षमता के अनुसार तय होता है; शून्य का मतलब यह नहीं है कि Docker agent को start करने से मना कर देगा, बल्कि यह है कि इन मान्यताओं के तहत full-cap बजट उपलब्ध नहीं है। एक 16 GB box में 7 के लिए जगह बचती है, जो चार की default सीमा और runner documentation द्वारा मांगी गई लगभग 10 GiB खाली मेमोरी से काफी अधिक है। 32 GB box आपको 15 तक ले जाता है। एक साथ चार से अधिक चलाने के लिए RUNNER_MAX_SANDBOXES को बढ़ाना भी आवश्यक है।
दो चीजें इस गणित को बदल देती हैं। Background process चलाने वाला sandbox कभी भी park नहीं होता, इसलिए वह अपना slot स्थायी रूप से रखता है। इसका मतलब है कि आप RUNNER_MAX_SANDBOXES का आकार sustained load के लिए तय करते हैं, न कि सबसे व्यस्त मिनट के लिए। Platform इस पर एक सीमा लगाता है: default रूप से प्रत्येक runner अधिकतम RUNNER_MAX_SANDBOXES minus एक held-awake sandboxes रखता है (संख्या कभी भी एक से कम नहीं होती, जिसे API पर MAX_HELD_AWAKE_SANDBOXES के साथ override किया जा सकता है), और उससे अधिक होने पर यह सबसे लंबे समय से idle चल रहे sandbox को हटा देता है और उसकी watched process को lost रिपोर्ट करता है। मेमोरी और CPU का उपयोग काम पर निर्भर करता है। प्रत्येक sandbox एक CPU तक सीमित है, इसलिए चार व्यस्त agents चार cores का उपयोग कर सकते हैं, लेकिन 2 GiB मेमोरी सेटिंग एक अधिकतम सीमा है, न कि reservation: चार idle-but-awake agents अपने आप 8 GiB का उपभोग नहीं करते हैं।
Runner settings जिन्हें आप बदलना चाह सकते हैं
RUNNER_MAX_SANDBOXES(default4): एक साथ कितने sandboxes चलते हैं।RUNNER_SANDBOX_MEMORY_MB(default2048): प्रति sandbox मेमोरी की अधिकतम सीमा।RUNNER_SANDBOX_CPUS(default1): प्रति sandbox CPU की अधिकतम सीमा।RUNNER_SANDBOX_PIDS(default512): प्रति sandbox processes की अधिकतम सीमा।RUNNER_NETWORK_INTERNAL(defaulttrue): sandbox network को बाहर जाने वाले किसी भी route के बिना रखता है। इसे चालू रहने दें।RUNNER_SANDBOX_NETWORK(defaultonecli-sandboxes): वह network जिससे sandboxes जुड़ते हैं।RUNNER_RECONCILE_SECONDS(default60): runner कितनी बार state को reconcile करता है।RUNNER_ORPHAN_GRACE_SECONDS(default3600): वह आयु जिस पर orphaned containers और volumes को नष्ट कर दिया जाता है।RUNNER_AGENT_IMAGE: sandbox image को override करता है, जो अन्यथाONECLI_VERSIONका अनुसरण करती है।
Docker Compose के साथ OneCLI इंस्टॉल करें
अपस्ट्रीम self-hosting दस्तावेज़ का मूल अनुक्रम compose फ़ाइल के बगल में docker/.env में तीन secrets लिखता है। वह अनुक्रम runner token, Docker socket group और सेवाओं के लिए आवश्यक SSH क्रेडेंशियल्स को छोड़ देता है, इसलिए stack शुरू करने से पहले setup wizard चलाएँ।
git clone https://github.com/onecli/onecli.git && cd onecli/docker
cat > .env <<EOF
SECRET_ENCRYPTION_KEY=$(head -c 32 /dev/urandom | base64)
GATEWAY_INTERNAL_SECRET=$(head -c 32 /dev/urandom | base64)
BETTER_AUTH_SECRET=$(head -c 32 /dev/urandom | base64)
COMPOSE_PROFILES=runner
EOF
chmod 600 .env
cd ..
pnpm install
pnpm run setup
cd docker
docker compose up -d --waitइसे चलाने से पहले उस ब्लॉक को पढ़ें। Heredoc मार्कर unquoted है, इसलिए आपका shell प्रत्येक head -c 32 /dev/urandom | base64 को चलाता है और literal text के बजाय परिणाम लिखता है। SECRET_ENCRYPTION_KEY डेटाबेस में प्रत्येक secret के लिए AES-256-GCM key है। GATEWAY_INTERNAL_SECRET gateway को API के लिए प्रमाणित करता है। BETTER_AUTH_SECRET session cookies को sign करता है। COMPOSE_PROFILES=runner वह लाइन है जो सबसे अधिक मायने रखती है, क्योंकि runner service एक Compose profile के पीछे स्थित होती है: यदि आप इसे छोड़ देते हैं, तो stack healthy स्थिति में आ जाता है लेकिन कोई भी agent sandbox शुरू नहीं होता है।
--wait सेवाओं के चलने या healthy होने और migrations dependency के सफलतापूर्वक पूरा होने की प्रतीक्षा करता है, इसलिए non-zero exit इस बात का पहला संकेत है कि कुछ गलत है। फिर देखें कि वास्तव में क्या शुरू हुआ।
docker compose ps
docker compose logs migrationsversion को पिन करें। ONECLI_VERSION एक साथ सभी सेवाओं के लिए tag सेट करता है, और agent sandbox image इसका अनुसरण करती है जब तक कि RUNNER_AGENT_IMAGE कहीं और न इंगित करे। केवल version number का उपयोग करें: प्रकाशित image tags में कोई v prefix नहीं होता है। 1 November 2026 तक वर्तमान release v2.17.0 है, जिसे 31 October 2026 को प्रकाशित किया गया था। इसे उसी फ़ाइल में जोड़ें, फिर documented upgrade path का उपयोग करें ताकि चल रहे sandboxes भी उस image पर चले जाएँ।
echo 'ONECLI_VERSION=2.17.0' >> .env
cd ..
pnpm run setup --upgrade
cd dockerएक installer भी मौजूद है, curl -fsSL https://onecli.sh/install | sh, जो अपना configuration ~/.onecli/.env में लिखता है और वही काम करता है। यह अपने स्वयं के run के लिए ONECLI_VERSION=latest सेट करता है, जो उस .env फ़ाइल में रखे गए पिन को ओवरराइड करता है। Compose path वह है जहाँ आप कुछ भी चलने से पहले हर फ़ाइल को पढ़ सकते हैं, और यह उस सर्वर पर उपयोग करने के लिए है जिसमें पहले से ही अन्य Compose stacks मौजूद हैं। ऊपर दिया गया checkout setup pnpm run setup --upgrade के साथ अपग्रेड होता है। वह path host पर Node.js और pnpm की मांग करता है, और कोड पर काम करने के लिए gateway के लिए mise और Rust की आवश्यकता होती है, इसलिए यह उन लोगों के लिए उपयुक्त है जो OneCLI को बदलना चाहते हैं। Kubernetes के लिए, release v2.11.0 (8 October 2026) ने एक Helm chart जोड़ा है; वर्तमान chart agent sandboxes को persistent volumes के साथ Jobs के रूप में चलाता है, बिना Docker daemon के, और आवश्यक secrets, database और routing configuration का दस्तावेजीकरण करता है।
अपने लैपटॉप से डैशबोर्ड तक पहुँचना
शिप की गई compose file में प्रत्येक पब्लिश किया गया पोर्ट ${ONECLI_BIND_HOST:-127.0.0.1} पर बाइंड होता है। VPS पर इसका मतलब है कि डैशबोर्ड चल रहा है, लेकिन बॉक्स के बाहर से कोई भी उस तक नहीं पहुँच सकता। यह डिफ़ॉल्ट सेटिंग सही है। इसे ऐसे ही रहने दें और टनल का उपयोग करें:
ssh -N -L 10254:127.0.0.1:10254 you@your-serverअब अपने लैपटॉप पर http://localhost:10254 खोलें। ट्रैफ़िक SSH कनेक्शन के माध्यम से जाता है, इसलिए सार्वजनिक इंटरनेट पर कोई अनएन्क्रिप्टेड डैशबोर्ड नहीं होता और फ़ायरवॉल के लिए कोई अतिरिक्त पोर्ट खोलने की आवश्यकता नहीं पड़ती।
ONECLI_BIND_HOST=0.0.0.0 सेट करने से डैशबोर्ड सादे HTTP पर पब्लिश हो जाता है, और यह इसके साथ PostgreSQL को भी पब्लिश कर देता है, जिसमें compose file का डिफ़ॉल्ट पासवर्ड onecli होता है, जब तक कि आप POSTGRES_PASSWORD सेट न करें। यह पोर्ट 10257 पर SSH फ्रंट डोर को भी पब्लिश करता है, जो एक ऐसी सर्विस है जो Docker सॉकेट को माउंट करती है। यदि कई लोगों को डैशबोर्ड की आवश्यकता है, तो सामने TLS (transport layer security) के साथ एक रिवर्स प्रॉक्सी लगाएँ और बाइंड होस्ट को न बदलें। ONECLI_EXTERNAL_URL को इसके HTTPS URL पर सेट करें और अपस्ट्रीम के रिवर्स प्रॉक्सी कॉन्फ़िगरेशन का उपयोग करें, जो डैशबोर्ड, API और गेटवे पाथ को उनकी संबंधित सर्विस तक रूट करता है। केवल एक प्रॉक्सी बाहरी लोगों को नहीं रोकती। सेल्फ-होस्टिंग दस्तावेज़ बताता है कि रजिस्ट्रेशन डिज़ाइन के अनुसार खुला है और इसे बंद करने के लिए कोई स्विच नहीं है: डैशबोर्ड तक पहुँचने वाला कोई भी व्यक्ति अकाउंट बना सकता है, जिसे अपना स्वयं का संगठन मिल जाता है, और केवल आपके संगठन में शामिल होने के लिए आमंत्रण की आवश्यकता होती है। सलाह यह है कि डैशबोर्ड को अपनी नेटवर्क सीमा के पीछे रखें। यदि वह प्रॉक्सी पहले से ही आपके अन्य सेल्फ-होस्टेड ऐप्स के सामने है, तो एक सेल्फ-होस्टेड सिंगल साइन-ऑन लेयर के माध्यम से ऑथेंटिकेशन को फॉरवर्ड करने से डैशबोर्ड उस लॉगिन के पीछे आ जाता है जो आपकी टीम के पास पहले से है, इसलिए किसी को एक जगह से हटाने पर यह दरवाज़ा भी बंद हो जाता है।
पहला अकाउंट बनाएँ, फिर एक model key प्रदान करें
Dashboard खोलें और तुरंत अपना अकाउंट बनाएँ। प्रत्येक नए अकाउंट को अपनी एक organization मिलती है, और टीम के सदस्य निमंत्रण द्वारा आपकी organization में शामिल होते हैं। उसके बाद registration खुला रहता है, जो एक और कारण है कि dashboard को tunnel या authenticated proxy के पीछे होना चाहिए। यदि आप ऐसे release से upgrade कर रहे हैं जिसमें login की सुविधा नहीं थी, तो तुरंत register करें: self-hosting document के अनुसार मौजूदा डेटा उस पहले अकाउंट में चला जाता है जो register होता है, इसलिए एक reachable host पर आप चाहेंगे कि वह अकाउंट आपका हो।
फिर agent बनाने से पहले एक model key store करें। एक hosted agent को एक granted model key की आवश्यकता होती है, और क्रम महत्वपूर्ण है: key को dashboard में store करें, उसे agent को grant करें, और उसके बाद ही conversation शुरू करें। यदि आप grant करना छोड़ देते हैं तो sandbox कभी launch नहीं होगा; agent thread में उत्तर देकर बताएगा कि उसे एक model key की आवश्यकता है।
सीमित रूप से grant करें। प्रत्येक agent को केवल वही मिलता है जो आपने उसे grant किया है और gateway हर request पर इसे लागू करता है, इसलिए जो agent एक repository को पढ़ता है, उसके पास आपके payment provider की key तक पहुँचने का कोई रास्ता नहीं होता। यही grant list आपके खर्च को नियंत्रित करने का जरिया है। प्रति-व्यक्ति एक ऐसा agent जो आपके स्वामित्व वाले किसी भी model को call कर सकता है, वह प्रति-व्यक्ति invoice बन जाता है, इसलिए दस agent देने से पहले यह पढ़ना उचित है कि agent model calls पर कितना खर्च कर सकता है, इसकी सीमा कैसे तय करें।
गेटवे एजेंटों से कुंजियों (keys) को कैसे सुरक्षित रखता है
गेटवे Rust में लिखा गया एक HTTPS प्रॉक्सी है, जो port 10255 पर listen करता है। एजेंट का HTTP client इसकी ओर निर्देशित होता है और एजेंट वास्तविक credential के बजाय एक placeholder credential रखता है। गेटवे outbound request का मिलान उस एजेंट के grants से करता है, वास्तविक secret को decrypt करता है, उसे request में swap करता है और आगे भेज देता है। Secrets PostgreSQL में AES-256-GCM (advanced encryption standard, 256-bit, Galois/counter mode) के साथ encrypted रहते हैं और केवल request के समय ही decrypt किए जाते हैं। प्रत्येक कॉल को एजेंट की पहचान और उसके target के साथ log किया जाता है, जो एक ऐसा audit trail है जिसे आप तब प्राप्त नहीं कर सकते जब कुंजियाँ दस लोगों की shell profiles में मौजूद हों।
इसे deploy करने के तरीके दो तंत्रों द्वारा निर्धारित होते हैं।
- HTTPS interception एक man-in-the-middle है। गेटवे एक local certificate authority उत्पन्न करता है, एजेंट उस पर भरोसा करता है, और गेटवे एजेंट के TLS connection को terminate करके upstream service के लिए एक नया connection खोलता है। यही कारण है कि जिस एजेंट का HTTP client गेटवे certificate authority पर भरोसा नहीं करता, वह authentication error के बजाय certificate verification error के साथ विफल हो जाता है।
- एजेंट खुद को
Proxy-Authorizationheader के साथ पहचानता है। एक single box पर, जहाँ एजेंट और गेटवे एक internal Docker network साझा करते हैं, वह header कभी भी ऐसे नेटवर्क से नहीं गुजरता जिसे आप नियंत्रित नहीं करते। यदि आप box के बाहर के किसी एजेंट को गेटवे की ओर निर्देशित करते हैं, तो connection को VPN या TLS transport से सुरक्षित करें, क्योंकि वह header एक bearer token है; upstream raw CONNECT proxy port के लिए VPN का उपयोग करने की सलाह देता है।
ईमानदार समझौता: गेटवे आपके एजेंटों द्वारा की जाने वाली प्रत्येक request को, डिज़ाइन के अनुसार, plaintext में पढ़ता है। यह मशीन पर सबसे संवेदनशील प्रक्रिया है। इसके host के साथ उसी अनुसार व्यवहार करें, और उन लोगों की संख्या कम रखें जो least-privilege Linux users के साथ login कर सकते हैं।
Runner को inbound port की आवश्यकता क्यों नहीं है
Runner केवल outbound-only है। इसके documentation के अनुसार: "यह ऐसे किसी port को open नहीं रखता जिसे बाहरी दुनिया access कर सके, इसलिए laptop, homelab, या NAT के पीछे स्थित VPC बिना किसी ingress, tunnel, या TLS termination के काम करते हैं।" NAT का अर्थ network address translation है, जो एक home router द्वारा किया जाने वाला कार्य है। Runner control plane से जुड़ता है और उससे काम प्राप्त करता है, इसलिए न तो कुछ forward करने की आवश्यकता है और न ही कुछ open करने की।
यह design sandbox network में बहुत प्रभावी है। Compose file एक दूसरे network को परिभाषित करती है जिसे internal: true चिह्नित किया गया है, जिसका Docker में अर्थ है कि इसमें कोई बाहरी network connectivity नहीं है। Sandboxes इससे जुड़ते हैं। Gateway दोनों networks पर dual-homed है, इसलिए बाहर निकलने का यही एकमात्र रास्ता है। Runner का documentation इस बात को स्पष्ट रूप से कहता है: "एक internal network जिस पर gateway dual-homed हो, वही gateway-only egress को एक सुझाव के बजाय एक सीमा (boundary) बनाता है।" कोई agent किसी बाहरी address से सीधा connection खोलकर gateway को bypass नहीं कर सकता; gateway की policy ही यह तय करती है कि किन requests को अनुमति दी जाए।
ऊपर दिए गए पैराग्राफ पर भरोसा करने के बजाय इसे अपने box पर स्वयं confirm करें।
docker network ls
docker network inspect onecli-sandboxes | grep -i internalआपको "Internal": true दिखाई देना चाहिए। यदि यह false दिखाता है, तो egress control बंद है और gateway फिर से केवल एक सुझाव मात्र है। जिस sandbox network name को docker network ls print करता है, उसी का उपयोग करें, क्योंकि onecli-sandboxes केवल default है।
OneCLI sandbox कितना सुरक्षित है?
इस अनुभाग को ध्यान से पढ़ें, क्योंकि प्रोजेक्ट के विवरण में "sandboxed" शब्द का बहुत महत्व है, जबकि इसकी कार्यप्रणाली runner documentation और backend code में दर्ज है।
README के अनुसार प्रत्येक agent को "अपना अलग sandbox मिलता है, जिसमें एक filesystem और shell होता है", और Sandbox Supervisor को वह घटक बताया गया है जो "प्रत्येक sandbox के अंदर चलता है और एक vendor-neutral harness interface का उपयोग करता है ताकि agent runtime को बदला जा सके"। इनमें से कोई भी वाक्य यह नहीं बताता कि isolation किस चीज से बनी है। Runner की documentation यह बताती है: default backend Docker (RUNNER_BACKEND=docker) है, और sandbox एक Docker container है जिसमें memory cap, CPU cap और process cap लगे होते हैं, जो internal network से जुड़ा होता है। Code में अन्य backends के लिए भी प्रावधान है। वर्तमान runner code में एक Kubernetes backend भी है, जिसका उपयोग Helm chart द्वारा sandbox Jobs और persistent volumes के लिए किया जाता है। इस गाइड में Compose installation के तहत, sandbox एक Docker container है।
Runner documentation अब Docker boundary का वर्णन करती है: agent node के रूप में चलता है, जिसमें no-new-privileges होता है, सभी Linux capabilities हटा दी जाती हैं और Docker का default seccomp profile लागू होता है। Backend केवल agent के durable home को ही उसके sandbox में mount करता है। इसलिए इसे सीमित अर्थ में ही लें। ये caps केवल resource caps हैं। Internal network एक वास्तविक egress control है। Agent और आपके host के बीच isolation इन container controls का उपयोग करती है, और container host kernel को साझा करता है।
यहाँ एक दूसरा तथ्य भी है जिस पर विचार करना आवश्यक है। Runner service /var/run/docker.sock को mount करती है, क्योंकि इसी तरह यह sandboxes बनाती है। Rootful Docker daemon के socket तक पहुँच का अर्थ host पर root access के बराबर है, क्योंकि जो भी उस API को call कर सकता है, वह host filesystem को mount करके एक container शुरू कर सकता है। Docker-backed runner इसी socket का उपयोग करता है। इसका परिणाम यह है कि runner process उतनी ही संवेदनशील है जितनी gateway। SSH terminator भी उसी socket को mount करता है ताकि वह sandbox containers में exec कर सके, और compose file की टिप्पणियाँ स्वयं उस mount को host पर root-equivalent मानती हैं, इसलिए port 10257 को loopback पर ही रखें जब तक कि उसे खोलने का कोई ठोस कारण न हो।
Shared-kernel boundary को सावधानी से देखें। व्यवहार में इसका अर्थ तीन आदतें अपनाना है।
- OneCLI को ऐसे server पर चलाएँ जो कोई अन्य कार्य न करता हो। उस पर कोई unrelated production service, shared database या किसी अन्य टीम का डेटा न रखें।
- यह मानकर चलें कि यदि किसी agent को sandbox के अंदर arbitrary code execution मिल जाए, तो वह host तक पहुँच सकता है। इस स्थिति से बचने के लिए backups को server से बाहर सुरक्षित रखें।
- किसी सहकर्मी को यह बताने से पहले कि agent पूरी तरह सुरक्षित (contained) है,
apps/runner/srcको पढ़ें या upstream से पूछें।
Documented boundary कैसी दिखती है और upstream से क्या सवाल पूछने चाहिए, यह समझने के लिए इसकी तुलना एक वास्तविक agent sandbox boundary कैसी दिखती है से करें। मुख्य प्रश्न यह है कि क्या documented mechanism उन खतरों को रोकता है जिन्हें आप रोकना चाहते हैं।
लाइसेंस का विभाजन, और निर्माण से पहले जांच क्यों आवश्यक है
OneCLI का कोर Apache-2.0 है, और इसे प्रोडक्शन में self-host करने की अनुमति है। ee/ नाम की डायरेक्टरी एक अलग OneCLI Enterprise License के अंतर्गत आती हैं: यह डेवलपमेंट, टेस्टिंग और इवैल्यूएशन के लिए मुफ्त है, लेकिन प्रोडक्शन उपयोग के लिए सब्सक्रिप्शन आवश्यक है। 18 अगस्त 2026 के v2.0.1 रिलीज नोट्स में GitHub पर पहचाने जाने योग्य Apache-2.0 लाइसेंस फाइल को बहाल करने का उल्लेख है, इसलिए रिपॉजिटरी पेज पर लगा बैज हाल ही में बदल गया है। किसी अन्य तिथि पर लिखे गए सारांश के बजाय उस टैग की जांच करें जिसे आप वास्तव में डिप्लॉय कर रहे हैं।
cd onecli && find . -type d -name ee -not -path '*/node_modules/*'उन पाथ्स के अंतर्गत आने वाली कोई भी चीज़ कमर्शियल हिस्सा है। यदि कोई फीचर जिस पर आप निर्भर रहने की योजना बना रहे हैं, वहां स्थित है, तो उसके इर्द-गिर्द कोई प्रोसेस बनाने से पहले उसकी कीमत का आकलन कर लें।
अपग्रेड, माइग्रेशन और वह एक फाइल जिसे आप खो नहीं सकते
अपग्रेड के दौरान सर्विस इमेजेस और अलग एजेंट इमेज को रिफ्रेश करना आवश्यक है, और उसके बाद चल रहे सैंडबॉक्स को रीस्टार्ट करना होता है। प्रत्येक up पर API से पहले एक वन-शॉट माइग्रेशन सर्विस चलती है। यदि माइग्रेशन विफल हो जाता है, तो स्टैक शुरू होने से मना कर देता है, बजाय इसके कि वह आधे-अधूरे माइग्रेट किए गए स्कीमा पर काम करे। यही वह व्यवहार है जो आप चाहते हैं, क्योंकि एक विफल अपग्रेड एक आउटेज की तरह दिखता है, न कि चुपचाप होने वाले करप्शन की तरह, और docker compose logs migrations इसका कारण बताता है।
एक चरण ऐसा है जिसे भूलना आसान है। सेल्फ-होस्टिंग डॉक्यूमेंट केवल docker compose pull && docker compose up -d के साथ अपग्रेड करने के खिलाफ चेतावनी देता है, क्योंकि एजेंट सैंडबॉक्स इमेज एक Compose सर्विस नहीं है। यह रनर पर RUNNER_AGENT_IMAGE वैल्यू है, इसलिए docker compose pull इसे कभी नहीं देखता है, और होस्ट किए गए एजेंट बिना किसी चेतावनी के पुरानी सैंडबॉक्स इमेज पर बने रह सकते हैं। चेकआउट अपडेट करें, पिन को मूव करें, और डॉक्यूमेंट किए गए अपग्रेड टूल को चलाएं, जो सैंडबॉक्स इमेज को पुल करता है और चल रहे सैंडबॉक्स को रीस्टार्ट करता है।
cd onecli
git pull
sed -i 's/^ONECLI_VERSION=.*/ONECLI_VERSION=2.17.0/' docker/.env
pnpm install
pnpm run setup --upgrade
cd docker
docker compose logs migrations2.17.0 को उस रिलीज से बदलें जिस पर आप जा रहे हैं। सैंडबॉक्स रीस्टार्ट होने से चल रहे काम में बाधा आती है; प्रत्येक एजेंट का ड्यूरेबल वर्कस्पेस सुरक्षित रहता है।
यदि आपने इसके बजाय इंस्टॉल स्क्रिप्ट का उपयोग करके इंस्टॉल किया है, तो मैन्युअल रूप से पुल करने के बजाय उस स्क्रिप्ट को फिर से चलाएं, ताकि compose फाइल उन इमेजेस के साथ तालमेल में रहे जिन्हें वह रेफर करती है। यदि आप किसी विशिष्ट रिलीज को चाहते हैं तो पहले ONECLI_VERSION को एक्सपोर्ट करें, क्योंकि स्क्रिप्ट उस पिन को ओवरराइड कर देती है जो केवल उसकी .env फाइल में रखी गई है।
डेटाबेस, कॉन्फ़िगरेशन और एजेंट वर्कस्पेस वॉल्यूम का बैकअप लें। PostgreSQL में एजेंट, बातचीत, मेमोरी और एन्क्रिप्टेड सीक्रेट्स होते हैं। docker/.env फाइल में SECRET_ENCRYPTION_KEY होता है, और उस की (key) के बिना एन्क्रिप्टेड सीक्रेट्स को पढ़ा नहीं जा सकता, भले ही बाकी डेटाबेस को रिस्टोर कर लिया जाए। प्रत्येक एजेंट का /workspace एक अलग ड्यूरेबल वॉल्यूम पर रहता है और उसे अपने स्वयं के बैकअप की आवश्यकता होती है।
cd onecli/docker
docker compose exec -T postgres pg_dump -U onecli onecli | gzip > ~/onecli-db.sql.gz
install -m 600 .env ~/onecli-env.backupउन प्रतियों और वर्कस्पेस बैकअप को सर्वर से बाहर रखें। यह रूटीन वही है जिसकी किसी भी स्टेटफुल Compose स्टैक को आवश्यकता होती है, इसलिए यदि आप पहले से ही Docker Compose स्टैक का बैकअप और अपग्रेड शेड्यूल पर करते हैं, तो उसमें डेटाबेस, कॉन्फ़िगरेशन और वर्कस्पेस वॉल्यूम को जोड़ें और इसके बारे में चिंता करना छोड़ दें।
जब यह काम न करे
- स्टैक कभी भी healthy नहीं होता और
docker compose up -d --waitनॉन-जीरो एग्जिट कोड देता है। सबसे पहलेdocker compose logs migrationsपढ़ें, क्योंकि API जानबूझकर उस सर्विस के लिए प्रतीक्षा करता है। - एक एजेंट निष्क्रिय बैठा रहता है और कोई सैंडबॉक्स दिखाई नहीं देता। जाँचें कि
COMPOSE_PROFILES=runner,docker/.envमें मौजूद है औरdocker compose psमें एक रनर सूचीबद्ध है। फिर जाँचें कि एजेंट के पास एक ग्रांटेड मॉडल की (model key) है, क्योंकि इसके बिना सैंडबॉक्स लॉन्च नहीं होते। - कोई स्लॉट खाली नहीं है।
RUNNER_MAX_SANDBOXESका डिफ़ॉल्ट मान 4 है, और बैकग्राउंड प्रोसेस वाला सैंडबॉक्स तब तक अपना स्लॉट घेरे रखता है जब तक कि held-awake सीमा उसे हटा न दे।docker psदिखाता है कि वास्तव में क्या चल रहा है। - स्टैक स्टार्ट नहीं होता और Docker रिपोर्ट करता है कि पोर्ट पहले से उपयोग में है।
runnerप्रोफाइल चालू होने पर, SSH फ्रंट डोर को अन्य चार पोर्ट्स के साथ-साथ10257की भी आवश्यकता होती है। - कंटेनर गायब हो जाते हैं, या होस्ट बहुत धीमा हो जाता है।
dmesg -T | grep -i oomके साथ मेमोरी की कमी की जाँच करें; डिफ़ॉल्ट मेमोरी कैप एक सैंडबॉक्स को 2048 MB तक उपयोग करने की अनुमति देता है। - एजेंट की HTTPS कॉल प्रमाणीकरण त्रुटियों (authentication errors) के बजाय सर्टिफिकेट सत्यापन त्रुटियों (certificate verification errors) के साथ विफल हो जाती हैं। इसका HTTP क्लाइंट गेटवे की सर्टिफिकेट अथॉरिटी पर भरोसा नहीं करता है।
- एजेंट को हटाने के बाद भी पुराने कंटेनर या वॉल्यूम रह जाते हैं। रनर हर 60 सेकंड में रिकॉन्सिल (reconcile) करता है और
RUNNER_ORPHAN_GRACE_SECONDSसे पुराने अनाथ (orphans) को नष्ट कर देता है, जिसका डिफ़ॉल्ट मान 3600 है, इसलिए इसे लीक कहने से पहले एक घंटे प्रतीक्षा करें।
क्या इसे चलाना आपके लिए सही है?
Fit test संक्षिप्त है। जब कई लोगों को अलग-अलग agent की आवश्यकता हो और आप credentials को एक ही स्थान पर रखना चाहते हैं, तो OneCLI एक उपयोगी विकल्प है: एक ऐसा store जिसे rotate किया जा सके, एक audit log जिसे पढ़ा जा सके, और एक ऐसा dashboard जहाँ किसी व्यक्ति का access revoke करने पर वह वास्तव में हट जाए। यह एक वास्तविक operational समस्या है, और छह अलग-अलग laptops में API key कॉपी करना इसका एक खराब समाधान है।
एक व्यक्ति के लिए इतने infrastructure components चलाने से कोई वास्तविक लाभ नहीं मिलता। एक single agent के लिए आपको PostgreSQL, एक control plane, एक gateway और एक runner चलाने पड़ेंगे। Gateway जिस credential समस्या को हल करता है, वह तब लगभग होती ही नहीं जब key रखने वाला व्यक्ति केवल आप हों। इसके बजाय छोटे box पर एक single harness चलाएँ: VPS पर single agent harness यही काम बहुत कम memory में करता है। यदि आपने अभी तक कोई दिशा तय नहीं की है, तो self-hosted AI agents की तुलना वाला सर्वेक्षण पहले पढ़ना अधिक किफायती कदम है। यदि अपरिचित हिस्सा agents स्वयं हैं, न कि वे servers जिन पर वे चलते हैं, तो पहले agents वास्तव में कैसे काम करते हैं, इसे सीखने का चरणबद्ध मार्ग पूरा करें। Tool call और memory store वास्तव में क्या करते हैं, यह समझने से ही तय किया जा सकता है कि प्रत्येक व्यक्ति के agent को कौन-से grants मिलने चाहिए।
FAQ
OneCLI को self-host करने के लिए न्यूनतम सर्वर आवश्यकताएँ क्या हैं?
Docker के साथ Compose plugin का 2.24.0 या उससे नया वर्ज़न, यहाँ उपयोग किए गए setup wizard के लिए Node.js और pnpm, और पर्याप्त memory। PostgreSQL compose file के साथ आता है, इसलिए आपको इसे अलग से install करने की आवश्यकता नहीं है। Memory ही plan तय करती है: runner डिफ़ॉल्ट रूप से प्रत्येक agent sandbox को 2048 MB पर सीमित करता है, और इसका documentation डिफ़ॉल्ट चार sandboxes की क्षमता के लिए base stack के अलावा लगभग 10 GiB खाली memory का सुझाव देता है। chart के 2 GB base-stack बजट के अनुसार, 4 GB का box एक sandbox को उसकी पूरी क्षमता पर चलाने के लिए पर्याप्त है और 16 GB का box डिफ़ॉल्ट concurrency limit को पूरा करता है। ये केवल योजना बनाने के आंकड़े हैं, न कि मापी गई न्यूनतम आवश्यकताएँ या निश्चित memory allocation।
क्या OneCLI को PostgreSQL की आवश्यकता है, या यह SQLite का उपयोग कर सकता है?
इसे PostgreSQL की आवश्यकता है। DATABASE_URL को PostgreSQL connection string के रूप में document किया गया है, प्रदान की गई compose file postgres:18-alpine को pgdata volume के साथ चलाती है, और API शुरू होने से पहले एक अलग migrations service schema को लागू करती है। कोई SQLite विकल्प document नहीं किया गया है। बाहरी PostgreSQL सर्वर के लिए, API और migrations service दोनों को इसे उपयोग करने के लिए configure करें; प्रदान की गई compose file उनके connection strings को अपने bundled PostgreSQL service पर सेट करती है।
क्या OneCLI agent sandbox एक वास्तविक सुरक्षा सीमा (security boundary) है?
document किया गया Compose mechanism memory, CPU और process caps वाला एक Docker container है, जो internal: true चिह्नित network से जुड़ा है ताकि बाहरी traffic gateway से होकर जाए। egress control वास्तविक है और आप इसे docker network inspect के साथ verify कर सकते हैं। agent node के रूप में चलता है, जिसमें no-new-privileges, सभी Linux capabilities को हटाया गया है और Docker का डिफ़ॉल्ट seccomp profile लागू है, जबकि यह host kernel को साझा करता है। runner और SSH terminator दोनों /var/run/docker.sock को mount करते हैं, जो rootful Docker daemon का उपयोग करने वाले host पर root के बराबर है। OneCLI को एक dedicated box पर चलाएँ, और backups को उस box से बाहर रखें।
क्या मुझे OneCLI के लिए कोई inbound port खोलने की आवश्यकता है?
नहीं। runner केवल outbound है और कोई भी ऐसा port नहीं रखता जिसे बाहरी दुनिया access कर सके, इसलिए यह बिना किसी tunnel के NAT के पीछे काम करता है। compose file डिफ़ॉल्ट रूप से dashboard, gateway, API, PostgreSQL और runner profile के तहत, 10257 पर SSH front door को 127.0.0.1 पर bind करती है। dashboard को SSH tunnel के माध्यम से access करें, या यदि कई लोगों को इसकी आवश्यकता है, तो TLS के साथ upstream के reverse proxy configuration का उपयोग करें और आवश्यक dashboard, API और gateway routes को configure करें, यह याद रखते हुए कि registration उस हर व्यक्ति के लिए खुला रहता है जो इसे access कर सकता है। 10255 पर gateway agents के लिए है, और एक ही box पर वे agents इसे internal Docker network के माध्यम से access करते हैं।
क्या OneCLI कंपनी के भीतर उपयोग करने के लिए निःशुल्क है?
इसका core Apache-2.0 है और self-hosted production उपयोग की अनुमति है, जिसके लिए किसी commercial licence की आवश्यकता नहीं है। ee/ नाम की directories OneCLI Enterprise License के अंतर्गत आती हैं, जो development, testing और evaluation के लिए निःशुल्क है लेकिन production में इसके लिए subscription की आवश्यकता होती है। यह विभाजन releases के बीच बदलता रहता है, और 18 August 2026 के v2.0.1 notes में GitHub-detectable Apache-2.0 licence file को बहाल करने का उल्लेख है, इसलिए किसी भी feature पर workflow बनाने से पहले सटीक tag में LICENSE और ee/ directories की जाँच करें।