OneCLI को self-host कैसे करें: सेटअप और सर्वर गाइड

OneCLI को self-host करने पर आपको क्या मिलता है

OneCLI को self-host करें और आपकी टीम के प्रत्येक व्यक्ति को अपना स्वयं का agent मिलता है, जिनमें से प्रत्येक अपने स्वयं के sandbox में चलता है। API keys एक gateway में सुरक्षित रहती हैं जिसे agents कभी नहीं पढ़ पाते। इसका इंस्टॉलेशन एक Docker Compose stack है जिसके पीछे PostgreSQL है, जो http://localhost:10254 पर उपलब्ध है। एक वास्तविक सर्वर (real box) की योजना बनाएं। प्रलेखित डिफ़ॉल्ट (documented default) प्रति agent sandbox 2 GiB मेमोरी है, इसलिए यह 1 GB VPS के लिए उपयुक्त workload नहीं है।

उस stack में सात घटक (pieces) शामिल हैं, और यह जानना कि कौन सा क्या है, इस गाइड के बाकी हिस्सों को पढ़ना आसान बनाता है।

• Web dashboard (Next.js), port 10254। Agent निर्माण, चैट, मेमोरी और स्किल्स एडिटिंग, कनेक्शन और सीक्रेट्स।
• API server, port 10256। कंट्रोल प्लेन: डेटाबेस, कन्वर्सेशन हैंडलिंग, वर्क क्यू।
• Rust gateway, port 10255। Agents से बाहर जाने वाले अनुरोधों (outbound requests) को इंटरसेप्ट करता है और क्रेडेंशियल्स इंजेक्ट करता है।
• Runner। README इसे उस घटक के रूप में वर्णित करता है जो "agent sandboxes को शुरू करता है, पार्क करता है और समाप्त करता है। यह केवल आउटबाउंड है, और डेटाबेस को कभी नहीं छूता है।"
• Sandbox Supervisor। README इसे "प्रत्येक sandbox के अंदर चलने वाले, एक वेंडर-न्यूट्रल हार्नेस इंटरफ़ेस पर बात करने वाले" के रूप में वर्णित करता है ताकि agent runtime को बदला जा सके।
• Channel adapter। एक daemon जो Slack app को कनेक्ट करता है, ताकि एक agent अपने नाम से channels और DMs में उत्तर दे सके।
• PostgreSQL। शिप की गई compose फ़ाइल postgres:18-alpine को pgdata वॉल्यूम के साथ चलाती है।

नाम CLI है, लेकिन यह एक सर्वर प्रोडक्ट है

OneCLI एक सर्वर प्लेटफॉर्म है। इसका नाम एक ऐसे कमांड लाइन टूल की ओर इशारा करता है जिसे आप लैपटॉप पर इंस्टॉल करते हैं, लेकिन इस गाइड में जिस चीज़ की बात हो रही है, उसके लिए यह धारणा गलत है। एक अलग कमांड लाइन क्लाइंट onecli/onecli-cli रिपॉजिटरी में मौजूद है, और यह एक लोकल कोडिंग एजेंट के ट्रैफिक को गेटवे के माध्यम से रूट करता है। आप यहाँ जिस चीज़ को डिप्लॉय कर रहे हैं, वह एक मल्टी-यूज़र वेब एप्लिकेशन है: एक अकाउंट सिस्टम जहाँ पहला अकाउंट इंस्टेंस का मालिक होता है, बातचीत और सीक्रेट्स का एक डेटाबेस, और एक रनर जो कंटेनर्स को स्टार्ट करता है।

प्रति-व्यक्ति (per-person) मॉडल ही इसका पूरा डिज़ाइन है। README के अनुसार: "आप प्रत्येक व्यक्ति के लिए एक एजेंट बनाते हैं, प्रत्येक एजेंट को उसकी ज़रूरत के अनुसार एक्सेस देते हैं, और यह एक सैंडबॉक्स में काम करता है, जिसे एक ऐसे गेटवे के माध्यम से रूट किया जाता है जो क्रेडेंशियल्स को इंजेक्ट करता है और आपकी पॉलिसी को लागू करता है।" प्रत्येक एजेंट का अपना फाइलसिस्टम और शेल, अपना कन्वर्सेशन पेज, प्लेटफॉर्म द्वारा रखी गई मेमोरी, और आपके द्वारा एक बार लिखे गए स्किल्स होते हैं। क्रेडेंशियल्स सामान्य सेटअप से विपरीत तरीके से काम करते हैं। प्रत्येक व्यक्ति के एनवायरनमेंट में API key कॉपी करने के बजाय, आप की (key) को एक बार स्टोर करते हैं और इसे उन एजेंट्स को प्रदान करते हैं जिन्हें इसका उपयोग करने की अनुमति है।

शुरू करने से पहले सिस्टम की आवश्यकताएं

• Docker, जिसमें Compose plugin का version 2.19 या उससे नया हो। Compose file एक one-shot migrations service का उपयोग करती है जिस पर API निर्भर है, और उस dependency form के लिए 2.19 की आवश्यकता होती है।
• Memory, जो कि मुख्य बाधा है। कोई भी plan चुनने से पहले नीचे दिए गए sizing section को पढ़ें।
• Free loopback ports 10254, 10255, 10256 और 5432।

आपको स्वयं PostgreSQL install करने की आवश्यकता नहीं है: compose file इसे एक service के रूप में चलाती है। आपको Node.js या Rust की भी आवश्यकता नहीं है। ये केवल build-from-source path के लिए हैं, जहाँ mise toolchain को pin करता है।

आपके VPS पर कितने agent sandboxes आ सकते हैं?

Runner का अपना documentation अनुमानों के बजाय वास्तविक संख्याएँ प्रदान करता है। प्रत्येक sandbox को 2048 MB memory (RUNNER_SANDBOX_MEMORY_MB), एक CPU (RUNNER_SANDBOX_CPUS) और 512 processes (RUNNER_SANDBOX_PIDS) मिलते हैं। Concurrency की सीमा 4 (RUNNER_MAX_SANDBOXES) है, और documentation इस सीमा को पूरा करने के लिए base stack के अलावा लगभग 10 GiB खाली memory रखने की सलाह देता है।

[
  {
    "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 नहीं: कुल memory में से PostgreSQL और चार long-running services के लिए लगभग 2 GB घटाकर, उसे 2 GiB sandbox cap से विभाजित किया जाता है। इस आधार पर 2 GB box में 0 sandboxes आ सकते हैं, इसलिए सबसे सस्ता plan किसी hosted agent को चलाने में सक्षम नहीं है। एक 16 GB box में 7 के लिए जगह बचती है, जो चार की default सीमा और runner documentation द्वारा सुझाई गई 10 GiB खाली memory से काफी अधिक है। 32 GB box आपको 15 तक ले जाता है।

दो चीजें इस गणित को बदल देती हैं। Background process चलाने वाला sandbox कभी park नहीं होता, इसलिए वह अपना slot स्थायी रूप से घेर कर रखता है। इसका अर्थ है कि आप RUNNER_MAX_SANDBOXES को sustained load के लिए निर्धारित करते हैं, न कि सबसे व्यस्त मिनट के लिए। और CPU से पहले memory खत्म हो जाती है। प्रत्येक sandbox एक CPU तक सीमित है, इसलिए चार व्यस्त agents को चार cores चाहिए, लेकिन चार idle-but-awake agents भी 8 GiB memory घेर कर रखते हैं।

Docker Compose के साथ OneCLI इंस्टॉल करना

अपस्ट्रीम self-hosting दस्तावेज़ इस सटीक क्रम को बताता है। यह compose फ़ाइल के बगल में docker/.env में तीन secrets लिखता है, फिर stack को start करता है।

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
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 के लिए authenticate करता है। BETTER_AUTH_SECRET session cookies को sign करता है। COMPOSE_PROFILES=runner वह लाइन है जो सबसे अधिक मायने रखती है, क्योंकि runner service एक Compose profile के पीछे स्थित है: यदि आप इसे छोड़ देते हैं, तो stack healthy स्थिति में आ जाता है लेकिन कोई भी agent sandbox start नहीं होता है।

--wait shell को तब तक रोके रखता है जब तक कि प्रत्येक service healthy रिपोर्ट न कर दे, इसलिए non-zero exit आपका पहला संकेत है कि कुछ गलत है। फिर देखें कि वास्तव में क्या start हुआ है।

docker compose ps
docker compose logs migrations

Version को pin करें। ONECLI_VERSION एक साथ सभी services के लिए tag सेट करता है, और agent sandbox image भी उसी का अनुसरण करती है जब तक कि RUNNER_AGENT_IMAGE कहीं और न ले जाए। 19 August 2026 तक, वर्तमान release v2.0.1 है, जिसे 18 August 2026 को प्रकाशित किया गया था। इसे उसी फ़ाइल में जोड़ें और stack को वापस up लाएं।

echo 'ONECLI_VERSION=v2.0.1' >> .env
docker compose up -d --wait

एक installer भी मौजूद है, curl -fsSL https://onecli.sh/install | sh, जो अपना configuration ~/.onecli/.env में लिखता है और वही काम करता है। Compose path वह है जहाँ आप कुछ भी चलने से पहले हर फ़ाइल को पढ़ सकते हैं, और यह उस सर्वर पर उपयोग करने के लिए सही है जिस पर पहले से ही अन्य Compose stacks चल रहे हैं। Source से build करना तीसरा रास्ता है, जिसे cloned repository में pnpm install और फिर pnpm run setup के रूप में प्रलेखित किया गया है। उस path के लिए mise, gateway के लिए Rust, और वैसे भी Docker की आवश्यकता होती है, और यह उन लोगों के लिए मौजूद है जो code को बदलना चाहते हैं।

अपने लैपटॉप से डैशबोर्ड तक पहुँचना

शिप की गई compose file में हर published port ${ONECLI_BIND_HOST:-127.0.0.1} पर bind होता है। एक VPS पर इसका मतलब है कि डैशबोर्ड चल रहा है, लेकिन बॉक्स के बाहर से कोई भी उस तक नहीं पहुँच सकता। यह डिफ़ॉल्ट सेटिंग सही है। इसे ऐसे ही रहने दें और tunnel का उपयोग करें:

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

अब अपने लैपटॉप पर http://localhost:10254 खोलें। ट्रैफ़िक SSH कनेक्शन के माध्यम से जाता है, इसलिए सार्वजनिक इंटरनेट पर कोई unencrypted डैशबोर्ड नहीं होता और firewall के लिए किसी अतिरिक्त port की आवश्यकता नहीं पड़ती।

ONECLI_BIND_HOST=0.0.0.0 सेटिंग डैशबोर्ड को plain HTTP पर publish करती है, और यह इसके साथ PostgreSQL को भी publish कर देती है। यदि कई लोगों को डैशबोर्ड की आवश्यकता है, तो port 10254 के सामने TLS (transport layer security) वाला एक reverse proxy लगाएँ और bind host को न बदलें। ऐसा तब करें जब instance का कोई owner न हो। अपस्ट्रीम दस्तावेज़ इसके कारण के बारे में स्पष्ट है: "जब तक आप ऐसा नहीं करते, instance का कोई owner नहीं होता, और एक reachable host पर जो भी वहाँ पहले पहुँचता है, वह owner बन जाता है।" यदि वह proxy पहले से ही आपके अन्य self-hosted ऐप्स के सामने है, तो एक self-hosted single sign-on layer के माध्यम से auth को forward करने से डैशबोर्ड उस लॉगिन के पीछे सुरक्षित हो जाता है जो आपकी टीम के पास पहले से है, इसलिए किसी को एक जगह से हटाने पर यह एक्सेस भी बंद हो जाता है।

पहला अकाउंट बनाएँ, फिर एक मॉडल की (model key) प्रदान करें

डैशबोर्ड खोलें और तुरंत अकाउंट बनाएँ। वह अकाउंट इंस्टेंस का स्वामी होता है, और एक बार इसके बन जाने के बाद, इसमें शामिल होने के लिए आमंत्रण की आवश्यकता होती है।

इसके बाद, एजेंट बनाने से पहले एक मॉडल की (model key) स्टोर करें। एक होस्ट किए गए एजेंट को एक प्रदान की गई मॉडल की की आवश्यकता होती है, और क्रम महत्वपूर्ण है: डैशबोर्ड में की (key) स्टोर करें, इसे एजेंट को प्रदान करें, और उसके बाद ही बातचीत शुरू करें। यदि आप प्रदान (grant) करने का चरण छोड़ देते हैं, तो सैंडबॉक्स कभी लॉन्च नहीं होगा, जो एक ऐसे एजेंट के रूप में दिखाई देगा जो बिना कुछ किए वहीं बैठा रहता है।

सीमित रूप से प्रदान (grant) करें। प्रत्येक एजेंट को केवल वही मिलता है जो आपने उसे प्रदान किया है और गेटवे हर अनुरोध पर इसे लागू करता है, इसलिए जो एजेंट एक रिपॉजिटरी पढ़ता है, उसके पास आपके पेमेंट प्रोवाइडर की की (key) तक पहुँचने का कोई रास्ता नहीं होता है। यही ग्रांट लिस्ट खर्च पर आपका नियंत्रण है। प्रति-व्यक्ति एजेंट जो आपके स्वामित्व वाले किसी भी मॉडल को कॉल कर सकता है, वह प्रति-व्यक्ति इनवॉइस है, इसलिए दस एजेंट देने से पहले यह पढ़ना उचित है कि एजेंट मॉडल कॉल पर कितना खर्च कर सकता है, इसकी सीमा कैसे तय करें।

गेटवे एजेंटों से कुंजियों (keys) को कैसे सुरक्षित रखता है

गेटवे Rust में लिखा गया एक HTTPS प्रॉक्सी है, जो port 10255 पर listen करता है। एजेंट का HTTP क्लाइंट इसकी ओर निर्देशित होता है और एजेंट वास्तविक क्रेडेंशियल के बजाय एक प्लेसहोल्डर क्रेडेंशियल रखता है। गेटवे आउटबाउंड अनुरोध का मिलान उस एजेंट के अनुदानों (grants) से करता है, वास्तविक secret को डिक्रिप्ट करता है, उसे अनुरोध में बदल देता है और आगे भेज देता है। Secrets, PostgreSQL में AES-256-GCM (एडवांस्ड एन्क्रिप्शन स्टैंडर्ड, 256-बिट, गैलुआ/काउंटर मोड) के साथ एन्क्रिप्टेड रहते हैं और केवल अनुरोध के समय ही डिक्रिप्ट किए जाते हैं। प्रत्येक कॉल को एजेंट की पहचान और उसके लक्ष्य के साथ लॉग किया जाता है, जो एक ऐसा ऑडिट ट्रेल है जिसे आप तब प्राप्त नहीं कर सकते जब कुंजियाँ दस लोगों की शेल प्रोफाइल में रहती हैं।

दो तंत्र यह तय करते हैं कि आप इसे कैसे तैनात (deploy) करते हैं।

• HTTPS इंटरसेप्शन एक मैन-इन-द-मिडल (man-in-the-middle) है। गेटवे एक स्थानीय सर्टिफिकेट अथॉरिटी बनाता है, एजेंट उस पर भरोसा करता है, और गेटवे एजेंट के TLS कनेक्शन को समाप्त (terminate) करके अपस्ट्रीम सर्विस के लिए एक नया कनेक्शन खोलता है। यही कारण है कि जिस एजेंट का HTTP क्लाइंट गेटवे सर्टिफिकेट अथॉरिटी पर भरोसा नहीं करता है, वह ऑथेंटिकेशन एरर के बजाय सर्टिफिकेट वेरिफिकेशन एरर के साथ विफल हो जाता है।
• एजेंट खुद को Proxy-Authorization हेडर के साथ पहचानता है। एक सिंगल बॉक्स पर, जहाँ एजेंट और गेटवे एक आंतरिक Docker नेटवर्क साझा करते हैं, वह हेडर कभी भी ऐसे नेटवर्क को पार नहीं करता है जिसे आप नियंत्रित नहीं करते हैं। यदि आप बॉक्स के बाहर के किसी एजेंट को गेटवे की ओर निर्देशित करते हैं, तो प्रॉक्सी पोर्ट को अपने स्वयं के TLS की आवश्यकता होती है, क्योंकि वह हेडर एक बेयरर टोकन (bearer token) है।

ईमानदार समझौता: गेटवे आपके एजेंटों द्वारा किए गए प्रत्येक अनुरोध को, डिज़ाइन के अनुसार, प्लेनटेक्स्ट में पढ़ता है। यह मशीन पर सबसे संवेदनशील प्रक्रिया है। इसके होस्ट के साथ तदनुसार व्यवहार करें, और उन लोगों की संख्या कम रखें जो least-privilege Linux users के साथ लॉग इन कर सकते हैं।

Runner को inbound port की आवश्यकता क्यों नहीं है

Runner केवल outbound कनेक्शन बनाता है। इसके documentation के अनुसार: "यह ऐसे किसी port को open नहीं रखता जिसे बाहरी दुनिया एक्सेस कर सके, इसलिए laptop, homelab, या NAT के पीछे स्थित VPC बिना किसी ingress, tunnel, या TLS termination के काम करते हैं।" NAT का अर्थ network address translation है, जो एक home router द्वारा किया जाने वाला कार्य है। Runner control plane से जुड़ता है और वहाँ से काम (work) प्राप्त करता है, इसलिए port forward करने या खोलने की कोई आवश्यकता नहीं होती।

यह डिज़ाइन sandbox network में बहुत प्रभावी है। Compose file एक दूसरा network परिभाषित करती है जिसे internal: true चिह्नित किया गया है, जिसका Docker में अर्थ है कि host से बाहर जाने का कोई मार्ग नहीं है। Sandboxes इससे जुड़ते हैं। Gateway दोनों networks पर dual-homed है, इसलिए बाहर जाने का यही एकमात्र रास्ता है। Runner documentation इस बात को स्पष्ट रूप से कहता है: "एक internal network जिस पर gateway dual-homed हो, वही gateway-only egress को एक सुझाव के बजाय एक सीमा (boundary) बनाता है।" यदि कोई agent आपके source code को अपनी पसंद के किसी पते पर भेजने का निर्णय लेता है, तो उसके पास ऐसा करने के लिए कोई मार्ग नहीं होता।

ऊपर दिए गए पैराग्राफ पर भरोसा करने के बजाय इसे अपने box पर स्वयं जाँचे।

docker network ls
docker network inspect onecli-sandboxes | grep -i internal

आपको "Internal": true दिखाई देना चाहिए। यदि यह false दिखाता है, तो egress control बंद है और gateway केवल एक सुझाव मात्र है। docker network ls जो भी sandbox network नाम print करे, उसी का उपयोग करें, क्योंकि onecli-sandboxes केवल default नाम है।

OneCLI sandbox कितना सुरक्षित है?

इस अनुभाग को ध्यान से पढ़ें, क्योंकि प्रोजेक्ट के विवरण में "sandboxed" शब्द का बहुत महत्व है, जबकि इसकी कार्यप्रणाली का उल्लेख केवल एक ही स्थान पर किया गया है।

README के अनुसार प्रत्येक agent को "अपना अलग sandbox, एक filesystem और एक shell" मिलता है। इसमें Sandbox Supervisor को वह घटक बताया गया है जो "प्रत्येक sandbox के अंदर चलता है और एक vendor-neutral harness interface का उपयोग करता है ताकि agent runtime को बदला जा सके"। इनमें से कोई भी वाक्य यह नहीं बताता कि isolation किस तकनीक पर आधारित है। runner के documentation में यह स्पष्ट है: default backend Docker (RUNNER_BACKEND=docker) है, और एक sandbox का अर्थ है memory cap, CPU cap और process cap वाला एक Docker container, जो internal network से जुड़ा होता है। कोड में अन्य backends के लिए भी विकल्प मौजूद हैं, और documentation में Kubernetes और microVMs जैसे modules का उल्लेख है जिन्हें कोई भी लिख सकता है। वर्तमान में, आपके सिस्टम पर, एक sandbox केवल एक container है।

जो documentation में नहीं लिखा है, वह भी उतना ही महत्वपूर्ण है। यहाँ कोई threat model नहीं है। Docker daemon को rootless चलाने, user namespace remapping, Docker के defaults से परे seccomp या AppArmor profiles, या gVisor या microVM जैसी kernel boundary के बारे में कोई दावा नहीं किया गया है। इसलिए इसे सीमित अर्थ में ही लें। ये caps केवल resource caps हैं। internal network एक वास्तविक egress control है। एक agent और आपके host के बीच की isolation वही है जो एक सामान्य Docker container प्रदान करता है, और एक container host kernel को साझा करता है।

एक दूसरा तथ्य भी विचारणीय है। runner service /var/run/docker.sock को mount करती है, क्योंकि इसी तरह यह sandboxes बनाती है। Docker socket तक पहुँच का अर्थ host पर root access के समान है, क्योंकि जो कोई भी उस API को कॉल कर सकता है, वह host filesystem को mount करके एक container शुरू कर सकता है। हर Docker-backed runner इसी तरह काम करता है। इसका परिणाम यह है कि runner process उतनी ही संवेदनशील है जितनी कि gateway।

जब तक upstream इसे स्पष्ट रूप से न लिखे, इस boundary को अप्रमाणित मानें। व्यवहार में इसका अर्थ तीन आदतें अपनाना है।

1. OneCLI को ऐसे सर्वर पर चलाएं जो कोई अन्य कार्य न करता हो। वहां कोई unrelated production service, shared database या किसी अन्य टीम का डेटा नहीं होना चाहिए।
2. यह मानकर चलें कि यदि किसी agent को sandbox के अंदर arbitrary code execution मिल जाए, तो वह host तक पहुँच सकता है। इस स्थिति से बचने के लिए backups को उस सर्वर से बाहर रखें।
3. किसी सहकर्मी को यह बताने से पहले कि agent सुरक्षित रूप से contained है, apps/runner/src पढ़ें या upstream से पूछें।

एक प्रलेखित boundary कैसी दिखती है और upstream से क्या प्रश्न पूछने चाहिए, यह समझने के लिए इसकी तुलना एक वास्तविक agent sandbox boundary कैसी दिखती है से करें। अंतर इस बात में है कि क्या किसी ने कार्यप्रणाली को लिखित रूप में दर्ज किया है और यह क्या रोकने में सक्षम नहीं है।

लाइसेंस का विभाजन, और निर्माण से पहले जांच क्यों आवश्यक है

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 इसका कारण बताता है।

cd onecli/docker
docker compose pull
docker compose up -d --wait
docker compose logs migrations

यदि आपने इसके बजाय इंस्टॉल स्क्रिप्ट का उपयोग करके इंस्टॉल किया है, तो मैन्युअल रूप से पुल करने के बजाय उस स्क्रिप्ट को फिर से चलाएं, ताकि compose फाइल उन इमेज के साथ तालमेल में रहे जिन्हें वह रेफर करती है।

दो चीजों का बैकअप लें। PostgreSQL में एजेंट, बातचीत, मेमोरी और एन्क्रिप्टेड सीक्रेट्स होते हैं। docker/.env फाइल में SECRET_ENCRYPTION_KEY होता है, और उस की (key) के बिना एन्क्रिप्टेड सीक्रेट्स को पढ़ा नहीं जा सकता, इसलिए केवल डेटाबेस डंप से कुछ भी उपयोगी रिस्टोर नहीं होगा।

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 non-zero exit code देता है। सबसे पहले docker compose logs migrations पढ़ें, क्योंकि API जानबूझकर उस सर्विस के लिए प्रतीक्षा करती है।
• एक एजेंट निष्क्रिय रहता है और कोई सैंडबॉक्स दिखाई नहीं देता। जाँचें कि COMPOSE_PROFILES=runner, docker/.env में मौजूद है और docker compose ps में एक रनर सूचीबद्ध है। फिर जाँचें कि एजेंट के पास एक granted model key है या नहीं, क्योंकि इसके बिना सैंडबॉक्स लॉन्च नहीं होते।
• कोई स्लॉट खाली नहीं है। RUNNER_MAX_SANDBOXES डिफ़ॉल्ट रूप से 4 पर सेट होता है, और बैकग्राउंड प्रोसेस चलाने वाला सैंडबॉक्स अपना स्लॉट स्थायी रूप से घेरे रखता है। docker ps दिखाता है कि वास्तव में क्या चल रहा है।
• कंटेनर गायब हो जाते हैं, या होस्ट बहुत धीमा हो जाता है। आपकी मेमोरी समाप्त हो गई है। dmesg -T | grep -i oom कर्नेल के out-of-memory kills को रिकॉर्ड करता है, और एक अकेला सैंडबॉक्स 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 कॉपी करना इसका एक खराब समाधान है।

एक व्यक्ति के लिए, यह बिना किसी लाभ के बहुत अधिक तामझाम है। आप केवल एक agent चलाने के लिए PostgreSQL, एक control plane, एक gateway और एक runner का उपयोग करेंगे, जबकि gateway जिस credential समस्या को हल करता है, वह तब मौजूद ही नहीं होती जब key का एकमात्र धारक आप स्वयं हों। इसके बजाय एक छोटे server पर एक single harness चलाएं: VPS पर एक single agent harness यह काम बहुत कम memory में कर देता है। यदि आपने अभी तक कोई दिशा तय नहीं की है, तो self-hosted AI agents की तुलना वाला survey एक सस्ता और बेहतर शुरुआती कदम है।

FAQ

OneCLI को self-host करने के लिए न्यूनतम सर्वर आवश्यकताएं क्या हैं?

Docker के साथ Compose plugin का 2.19 या उससे नया वर्ज़न और पर्याप्त मेमोरी आवश्यक है। PostgreSQL compose file के साथ आता है, इसलिए आपको इसे अलग से इंस्टॉल करने की आवश्यकता नहीं है। मेमोरी ही प्लान तय करती है: runner डिफ़ॉल्ट रूप से प्रति agent sandbox 2048 MB आवंटित करता है। इसके दस्तावेज़ों के अनुसार, चार sandboxes की डिफ़ॉल्ट क्षमता को पूरा करने के लिए बेस स्टैक के अलावा लगभग 10 GiB खाली मेमोरी चाहिए, और लगभग 2 GB मेमोरी PostgreSQL और चार long-running services के लिए आवश्यक है। 4 GB वाला सर्वर एक समय में एक agent चला सकता है। 16 GB वाला सर्वर डिफ़ॉल्ट क्षमता को आसानी से संभाल लेता है। 1 GB या 2 GB वाले VPS पर hosted agent बिल्कुल भी शुरू नहीं हो सकता।

क्या OneCLI को PostgreSQL की आवश्यकता है, या यह SQLite का उपयोग कर सकता है?

इसे PostgreSQL की आवश्यकता है। DATABASE_URL को PostgreSQL कनेक्शन स्ट्रिंग के रूप में प्रलेखित किया गया है, प्रदान की गई compose file postgres:18-alpine को pgdata वॉल्यूम के साथ चलाती है, और API शुरू होने से पहले एक अलग migrations service स्कीमा को लागू करती है। कोई SQLite विकल्प प्रलेखित नहीं है। यदि आप पहले से ही कहीं और PostgreSQL चला रहे हैं, तो DATABASE_URL को उसकी ओर पॉइंट करें और migrations service को बनाए रखें, क्योंकि एक विफल माइग्रेशन स्टैक को रोक देता है, बजाय इसके कि वह आधा-अधूरा स्कीमा सर्व करे।

क्या OneCLI agent sandbox एक वास्तविक सुरक्षा सीमा (security boundary) है?

प्रलेखित तंत्र एक Docker container है जिसमें मेमोरी, CPU और प्रोसेस कैप्स लगे हैं। यह internal: true चिह्नित नेटवर्क से जुड़ा है, इसलिए gateway के अलावा इसका बाहर जाने का कोई रास्ता नहीं है। Egress कंट्रोल वास्तविक है और आप इसे docker network inspect के साथ सत्यापित कर सकते हैं। होस्ट आइसोलेशन कंटेनर-स्तर का है, और अपस्ट्रीम कोई थ्रेट मॉडल, rootless या user-namespace का दावा, या gVisor या microVM जैसी कोई कर्नल सीमा प्रकाशित नहीं करता है। runner /var/run/docker.sock को भी माउंट करता है, जो होस्ट पर root के बराबर है। agent-to-host सीमा को तब तक अप्रमाणित मानें जब तक अपस्ट्रीम इसका उल्लेख न करे। OneCLI को एक समर्पित सर्वर पर चलाएं और बैकअप उस सर्वर से अलग रखें।

क्या मुझे OneCLI के लिए कोई इनबाउंड पोर्ट खोलने की आवश्यकता है?

नहीं। runner केवल आउटबाउंड है और कोई भी ऐसा पोर्ट नहीं रखता जिसे बाहरी दुनिया एक्सेस कर सके, इसलिए यह बिना किसी टनल के NAT के पीछे काम करता है। compose file डिफ़ॉल्ट रूप से डैशबोर्ड, gateway, API और PostgreSQL को 127.0.0.1 पर बाइंड करती है। डैशबोर्ड तक पहुँचने के लिए SSH टनल का उपयोग करें, या यदि कई लोगों को इसकी आवश्यकता है, तो पोर्ट 10254 के सामने TLS के साथ एक reverse proxy लगाएँ। 10255 पर gateway agents के लिए है, और एक ही सर्वर पर वे agents इसे आंतरिक Docker नेटवर्क के माध्यम से एक्सेस करते हैं।

क्या OneCLI कंपनी के भीतर उपयोग करने के लिए मुफ्त है?

इसका कोर Apache-2.0 है और self-hosted प्रोडक्शन उपयोग की अनुमति है, जिसके लिए किसी कमर्शियल लाइसेंस की आवश्यकता नहीं है। ee/ नाम की डायरेक्टरी OneCLI Enterprise License के अंतर्गत आती हैं, जो डेवलपमेंट, टेस्टिंग और मूल्यांकन के लिए मुफ्त है, लेकिन प्रोडक्शन में इसके लिए सब्सक्रिप्शन की आवश्यकता होती है। यह विभाजन रिलीज़ के बीच बदलता रहता है, और 18 अगस्त 2026 के v2.0.1 नोट्स में GitHub-detectable Apache-2.0 लाइसेंस फ़ाइल को बहाल करने का उल्लेख है। इसलिए, किसी भी फीचर पर वर्कफ़्लो बनाने से पहले, जिस सटीक टैग को आप डिप्लॉय कर रहे हैं, उसमें LICENSE और ee/ डायरेक्टरी की जाँच करें।