SSD Nodes Learn Hosting plans →
নির্দেশিকা Matt Connorদ্বারা Matt Connor

কিভাবে নিজের সার্ভারে OneCLI সেলফ-হোস্ট করবেন

Docker Compose ও PostgreSQL ব্যবহার করে নিজের VPS-এ OneCLI সেটআপ করার পূর্ণাঙ্গ গাইড। প্রতিটি এজেন্টের জন্য 2 জিবি র‍্যামের প্রয়োজনীয়তা ও সিকিউরিটি গেটওয়ে কনফিগারেশন জানুন।

Self-host OneCLI করলে যা পাবেন

Self-host OneCLI করলে আপনার দলের প্রত্যেক ব্যক্তি নিজস্ব একটি agent পাবেন। প্রতিটি agent আলাদা sandbox-এ চলবে। API key এমন একটি gateway-এ সংরক্ষিত থাকবে, যেটি agent-গুলো কখনও পড়তে পারবে না। ইনস্টলেশনে PostgreSQL-সহ একটি Docker Compose stack থাকে, যা http://localhost:10254-এ পৌঁছানো যায়। এর জন্য উপযুক্ত বাস্তব সার্ভার প্রস্তুত রাখুন। নথিভুক্ত default অনুযায়ী, প্রতিটি agent sandbox-এর memory cap 2 GiB। তাই base stack এবং agent-গুলোর প্রকৃত working memory-এর জন্য আলাদাভাবে capacity নির্ধারণ করুন।

এই stack-এ আটটি component থাকে। কোন component-এর কাজ কী, তা জানলে এই guide-এর পরের অংশ বোঝা সহজ হবে।

  • Web dashboard (Next.js), port 10254। Agent তৈরি, chat, memory ও skills সম্পাদনা, connections এবং secrets ব্যবস্থাপনা।
  • API server, port 10256। এটি control plane: database, conversation handling এবং work queue পরিচালনা করে।
  • Rust gateway, port 10255। এটি agent-গুলোর outbound request intercept করে এবং credentials সংযুক্ত করে।
  • Runner। README অনুযায়ী, এটি "agent sandbox শুরু, স্থগিত এবং সরিয়ে ফেলার" component। এটি শুধু outbound connection ব্যবহার করে এবং কখনও database-এ access করে না।
  • Sandbox Supervisor। README অনুযায়ী, এটি "প্রতিটি sandbox-এর ভেতরে চলে এবং vendor-neutral harness interface-এর মাধ্যমে কাজ করে, যাতে agent runtime পরিবর্তন করা যায়।"
  • SSH terminator, port 10257। README এটিকে "SSH front door" হিসেবে উল্লেখ করেছে। এটি API থেকে জারি করা স্বল্পমেয়াদি certificate দিয়ে SSH connection terminate করে এবং প্রতিটি session সংশ্লিষ্ট agent-এর sandbox-এ bridge করে। এটি runner-এর মতো একই runner profile-এর অধীনে চলে।
  • Channel adapter। এটি এমন একটি daemon, যা একটি Slack app-এর সঙ্গে সংযোগ স্থাপন করে। ফলে agent নিজের নামে channel এবং DM-এ উত্তর দিতে পারে।
  • PostgreSQL। সরবরাহ করা compose file-টি postgres:18-alpine চালায় এবং pgdata volume ব্যবহার করে।

নামটি CLI বললেও পণ্যটি একটি server

OneCLI একটি server platform। নামটি এমন একটি command line tool-এর ইঙ্গিত দেয়, যা আপনি laptop-এ install করেন। কিন্তু এই guide-এ যে পণ্যটির কথা বলা হচ্ছে, সেটি এমন নয়। onecli/onecli-cli repository-তে একটি আলাদা command line client আছে। এটি local coding agent-এর traffic gateway-এর মাধ্যমে পাঠায়। এখানে আপনি যে জিনিসটি deploy করবেন, সেটি একটি multi-user web application: organizations ও invitations-সহ একটি account system, conversations ও secrets সংরক্ষণের জন্য একটি database, এবং containers চালু করার জন্য একটি runner।

প্রতি ব্যক্তির জন্য আলাদা model-ই এই নকশার মূল ভিত্তি। README-তে বলা হয়েছে: “আপনি প্রতি ব্যক্তির জন্য একটি agent তৈরি করবেন, প্রতিটি agent-কে তার প্রয়োজনীয় access দেবেন, এবং সেটি একটি sandbox-এ কাজ করবে। সেই traffic একটি gateway-এর মাধ্যমে যাবে, যা credentials inject করবে এবং আপনার policy প্রয়োগ করবে।” প্রতিটি agent-এর নিজস্ব filesystem ও shell, নিজস্ব conversation page, platform-এ সংরক্ষিত নিজস্ব memory এবং একবার লিখে পুনর্ব্যবহার করা যায় এমন skills থাকে। Credentials ব্যবহারের পদ্ধতি প্রচলিত setup-এর ঠিক বিপরীত। প্রতিটি ব্যক্তির environment-এ API key কপি না করে, key-টি একবার সংরক্ষণ করুন এবং যে agent-গুলো এটি ব্যবহার করতে পারবে, শুধু তাদের access দিন।

শুরু করার আগে সার্ভারে যা প্রয়োজন

  • Docker এবং 2.24.0 বা তার পরের সংস্করণের Compose plugin। সরবরাহ করা compose file-এ required: false-এর সঙ্গে ঐচ্ছিক env_file mapping ব্যবহার করা হয়েছে, যা Docker 2.24.0 থেকে সমর্থন করে। এর migration comment-এ up --wait-এর অধীনে one-shot dependency সমর্থনের জন্য 2.19-এর ন্যূনতম সংস্করণ বলা হয়েছে। তবে এতে file-এর ঐচ্ছিক environment file সমর্থন অন্তর্ভুক্ত নয়।
  • Memory, কারণ এটিই প্রকৃত সীমাবদ্ধতা। Plan বাছাই করার আগে নিচের sizing section পড়ুন।
  • অব্যবহৃত loopback port 10254, 10255, 10256, 10257 এবং 5432। Port 10257 হলো SSH-এর প্রবেশদ্বার। এই guide-এ এটি runner profile দিয়ে চালু করা হয়।

আপনাকে নিজে PostgreSQL install করতে হবে না। compose file এটিকে একটি service হিসেবে চালায়। নিচের setup wizard চালাতে host-এ Node.js এবং pnpm প্রয়োজন। Code নিয়ে কাজ করলেও toolchain নির্দিষ্ট রাখতে mise ব্যবহার করা হয়, যার মধ্যে gateway-এর জন্য Rust-ও রয়েছে।

আপনার VPS-এ কতগুলো agent sandbox চলতে পারে?

runner-এর নিজস্ব documentation অনুমানের বদলে বাস্তব সংখ্যা দেয়। প্রতিটি sandbox-এ memory সর্বোচ্চ 2048 MB (RUNNER_SANDBOX_MEMORY_MB), 1টি CPU (RUNNER_SANDBOX_CPUS) এবং 512টি process (RUNNER_SANDBOX_PIDS) নির্ধারিত থাকে। একসঙ্গে চলার সীমা 4 (RUNNER_MAX_SANDBOXES)। এই সীমা পূরণ করতে base stack-এর অতিরিক্ত প্রায় 10 GiB free memory রাখার পরামর্শ documentation-এ দেওয়া হয়েছে।

চার্টAgent memory budgets per box, using the documented 2 GiB cap
এই চার্টের পেছনের ডেটা
[
  {
    "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 সংখ্যাগুলো benchmark নয়, arithmetic হিসাব। মোট memory থেকে PostgreSQL এবং অন্যান্য দীর্ঘসময় চলা service-এর জন্য আনুমানিক 2 GB বাদ দিয়ে অবশিষ্ট memory-কে sandbox-এর 2 GiB সীমা দিয়ে ভাগ করা হয়েছে। সেই ভিত্তিতে 2 GB box plan-এ পূর্ণ memory cap-এ 0টি sandbox চালানোর budget থাকে। zero-এর অর্থ হলো এই অনুমান অনুযায়ী পূর্ণ-cap sandbox-এর জন্য budget নেই; Docker agent start করতে অস্বীকার করে, এমন নয়। একটি 16 GB box plan-এ 7টির জন্য জায়গা থাকে। এটি default cap 4-এর চেয়ে যথেষ্ট বেশি এবং runner documentation-এ চাওয়া প্রায় 10 GiB free memory-এরও বেশি। 32 GB box আপনাকে 15-এ নিয়ে যায়। একই সময়ে 4টির বেশি চালাতে হলে RUNNER_MAX_SANDBOXES-এর মানও বাড়াতে হবে।

দুটি বিষয় এই arithmetic হিসাবকে প্রভাবিত করে। কোনো sandbox-এ background process চললে সেটি idle অবস্থায় যায় না। তাই sandbox-টি স্থায়ীভাবে তার slot ধরে রাখে। ফলে সবচেয়ে ব্যস্ত এক মিনিটের জন্য নয়, দীর্ঘস্থায়ী load-এর জন্য RUNNER_MAX_SANDBOXES নির্ধারণ করতে হবে। Platform এই সংখ্যারও একটি সর্বোচ্চ সীমা নির্ধারণ করে। Defaultভাবে প্রতিটি runner সর্বোচ্চ RUNNER_MAX_SANDBOXES minus 1টি জাগ্রত রাখা sandbox ধরে রাখে, তবে সংখ্যা কখনো 1-এর কম হয় না। API-তে MAX_HELD_AWAKE_SANDBOXES ব্যবহার করে এই সীমা পরিবর্তন করা যায়। সীমা অতিক্রম করলে runner সবচেয়ে দীর্ঘ সময় idle থাকা sandbox-টি সরিয়ে দেয় এবং সেটির monitored process-কে হারিয়ে গেছে বলে জানায়। Memory ও CPU ব্যবহার কাজের ধরন অনুযায়ী নির্ভর করে। প্রতিটি sandbox-এ 1টি CPU-র সীমা থাকে। তাই 4টি ব্যস্ত agent 4টি core ব্যবহার করতে পারে। তবে 2 GiB memory setting হলো সর্বোচ্চ সীমা, reserved memory নয়। 4টি idle কিন্তু জাগ্রত agent স্বয়ংক্রিয়ভাবে 8 GiB memory ব্যবহার করে না।

যে Runner settings পরিবর্তন করতে পারেন
  • RUNNER_MAX_SANDBOXES (default 4): একই সময়ে কতগুলো sandbox চলবে।
  • RUNNER_SANDBOX_MEMORY_MB (default 2048): প্রতিটি sandbox-এর memory cap।
  • RUNNER_SANDBOX_CPUS (default 1): প্রতিটি sandbox-এর CPU cap।
  • RUNNER_SANDBOX_PIDS (default 512): প্রতিটি sandbox-এর process cap।
  • RUNNER_NETWORK_INTERNAL (default true): sandbox network-এ বাইরের দিকে route না থাকার বিষয়টি বজায় রাখে। এটি চালু রাখুন।
  • RUNNER_SANDBOX_NETWORK (default onecli-sandboxes): sandbox-গুলো যে network-এ যুক্ত হবে।
  • RUNNER_RECONCILE_SECONDS (default 60): runner কত ঘন ঘন state সমন্বয় করবে।
  • RUNNER_ORPHAN_GRACE_SECONDS (default 3600): যে বয়সে orphaned container ও volume ধ্বংস করা হবে।
  • RUNNER_AGENT_IMAGE: sandbox image পরিবর্তন করে। অন্যথায় এটি ONECLI_VERSION অনুসরণ করে।

Docker Compose দিয়ে OneCLI ইনস্টল করুন

Upstream self-hosting নথির raw sequence-এ compose file-এর পাশে docker/.env-এ 3টি secret লেখা হয়। এই sequence-এ সক্রিয় করা service-গুলোর জন্য প্রয়োজনীয় runner token, Docker socket group এবং SSH credential বাদ রয়েছে। তাই 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

চালানোর আগে ওই block-টি পড়ুন। heredoc marker-এ quote নেই। তাই shell প্রতিটি head -c 32 /dev/urandom | base64 চালিয়ে literal text-এর বদলে তার ফল লিখবে। SECRET_ENCRYPTION_KEY database-এর প্রতিটি secret-এর জন্য AES-256-GCM key। GATEWAY_INTERNAL_SECRET gateway-কে API-তে authenticate করে। BETTER_AUTH_SECRET session cookie sign করে। COMPOSE_PROFILES=runner সবচেয়ে গুরুত্বপূর্ণ line, কারণ runner service একটি Compose profile-এর পেছনে থাকে। এটি বাদ দিলে stack healthy অবস্থায় চালু হবে, কিন্তু কোনো agent sandbox শুরু হবে না।

--wait service-গুলো running বা healthy হওয়া এবং migrations dependency সফলভাবে সম্পন্ন হওয়া পর্যন্ত অপেক্ষা করে। তাই non-zero exit হলো কোনো সমস্যা আছে কি না বোঝার প্রথম সংকেত। এরপর বাস্তবে কোন service চালু হয়েছে তা দেখুন।

docker compose ps
docker compose logs migrations

Version নির্দিষ্ট করে দিন। ONECLI_VERSION একসঙ্গে প্রতিটি service-এর tag নির্ধারণ করে। RUNNER_AGENT_IMAGE অন্য কোথাও নির্দেশ না করলে agent sandbox image-ও একই tag অনুসরণ করে। শুধু version number ব্যবহার করুন। Published image tag-এ v prefix নেই। 1 November 2026 অনুযায়ী বর্তমান release হলো v2.17.0, যা 31 October 2026-এ প্রকাশিত হয়েছে। একই file-এ এটি যোগ করুন। এরপর নথিভুক্ত upgrade path ব্যবহার করুন, যাতে চলমান sandbox-গুলোও ওই 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 file-এ রাখা pin কার্যকর থাকে না। Compose path-এ কোনো কিছু চালানোর আগে প্রতিটি file পড়ে দেখা যায়। একই host-এ অন্য Compose stack চললে এই path ব্যবহার করুন। উপরের checkout setup-টি pnpm run setup --upgrade দিয়ে upgrade করে। এই path-এ host-এ Node.js এবং pnpm থাকতে হয়। Code নিজে পরিবর্তন করতে চাইলে gateway-এর জন্য mise এবং Rust-ও প্রয়োজন। তাই যারা OneCLI পরিবর্তন করতে চান, তাদের জন্য এই path উপযুক্ত। Kubernetes-এর জন্য release v2.11.0 (8 October 2026)-এ একটি Helm chart যোগ করা হয়েছে। বর্তমান chart persistent volume ব্যবহার করে agent sandbox-গুলোকে Jobs হিসেবে চালায়। এতে Docker daemon লাগে না। প্রয়োজনীয় secret, database এবং routing configuration-ও এতে নথিভুক্ত আছে।

ল্যাপটপ থেকে dashboard-এ পৌঁছানো

প্রকাশিত compose file-এর প্রতিটি port ${ONECLI_BIND_HOST:-127.0.0.1}-এ bind করা থাকে। VPS-এ এর অর্থ হলো dashboard চালু আছে, কিন্তু সার্ভারের বাইরের কোনো সংযোগ এটি পেতে পারে না। এই default সঠিক। এটি অপরিবর্তিত রাখুন এবং tunnel ব্যবহার করুন:

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

এখন আপনার ল্যাপটপে http://localhost:10254 খুলুন। ট্রাফিকটি SSH connection-এর মাধ্যমে যায়। তাই public internet-এ dashboard-এর কোনো unencrypted সংযোগ থাকে না এবং firewall-এ অতিরিক্ত কোনো port খুলতে হয় না।

ONECLI_BIND_HOST=0.0.0.0 সেট করলে dashboard plain HTTP-এর মাধ্যমে প্রকাশিত হয়। একই সঙ্গে PostgreSQL-ও প্রকাশিত হয়। আপনি POSTGRES_PASSWORD সেট না করলে compose file-এর default password থাকে onecli। এটি port 10257-এ SSH front door-ও প্রকাশ করে। এই service Docker socket mount করে। একাধিক ব্যক্তির dashboard প্রয়োজন হলে সামনে TLS (transport layer security) সহ একটি reverse proxy রাখুন এবং bind host অপরিবর্তিত রাখুন। ONECLI_EXTERNAL_URL-এ এর HTTPS URL সেট করুন এবং upstream-এর reverse proxy configuration ব্যবহার করুন। এটি dashboard, API এবং gateway path-গুলো সংশ্লিষ্ট service-এ route করে।

শুধু একটি proxy ব্যবহার করলেই অপরিচিত ব্যক্তিদের আটকানো যায় না। Self-hosting document-এ বলা হয়েছে, নকশা অনুযায়ী registration উন্মুক্ত এবং এটি বন্ধ করার কোনো switch নেই। Dashboard-এ পৌঁছাতে পারে এমন যে কেউ একটি account তৈরি করতে পারে। সেই account-এর নিজস্ব organization থাকে। আপনার organization-এ যোগ দেওয়ার জন্যই শুধু invitation প্রয়োজন। Document-এর পরামর্শ হলো dashboard-কে আপনার network boundary-এর ভেতরে রাখা। আপনার অন্য self-hosted app-গুলোর সামনেও যদি একই proxy থাকে, তাহলে একটি self-hosted single sign-on layer-এর মাধ্যমে forward auth ব্যবহার করলে dashboard-ও দলের বিদ্যমান login-এর আড়ালে থাকে। ফলে এক জায়গায় কাউকে সরিয়ে দিলে এই প্রবেশপথও বন্ধ হয়ে যায়।

প্রথমে প্রথম account তৈরি করুন, তারপর একটি model key grant করুন

Dashboard খুলে সঙ্গে সঙ্গে আপনার account তৈরি করুন। প্রতিটি নতুন account-এর জন্য একটি আলাদা organization তৈরি হয়। Teammates invitation-এর মাধ্যমে আপনার organization-এ যোগ দেয়। এর পরেও registration চালু থাকে। তাই dashboard-কে tunnel বা authenticated proxy-এর পেছনে রাখা আরও গুরুত্বপূর্ণ। আপনি যদি login সমর্থন করার আগের কোনো release থেকে upgrade করেন, তাহলে সঙ্গে সঙ্গে register করুন। Self-hosting document অনুযায়ী, register করা প্রথম account-এ বিদ্যমান data চলে যায়। তাই host-এ সরাসরি পৌঁছানো গেলে সেই account আপনার হওয়া উচিত।

এরপর agent তৈরি করার আগে একটি model key store করুন। Hosted agent-এর জন্য একটি granted model key প্রয়োজন। এখানে ধাপের ক্রম গুরুত্বপূর্ণ: dashboard-এ key store করুন, agent-কে key grant করুন, তারপর conversation শুরু করুন। Grant না করলে sandbox কখনও launch হয় না। Agent thread-এ জানায় যে তার একটি model key প্রয়োজন।

শুধু প্রয়োজনীয় অনুমতি grant করুন। প্রতিটি agent কেবল আপনার grant করা জিনিসগুলোই পায়। Gateway প্রতিটি request-এ এই সীমা প্রয়োগ করে। তাই একটি repository পড়তে পারে এমন agent আপনার payment provider-এর key-তে পৌঁছাতে পারে না। একই grant list দিয়ে খরচও নিয়ন্ত্রণ করা যায়। আপনার মালিকানাধীন যেকোনো model call করতে পারে এমন per-person agent মানে per-person invoice। তাই দশটি agent দেওয়ার আগে agent-এর model call-এর খরচ সীমিত করার পদ্ধতি পড়ে নিন।

এজেন্টদের কাছ থেকে key কীভাবে গোপন রাখে gateway

gateway হলো Rust-এ লেখা একটি HTTPS proxy, যা port 10255-এ listening করে। এজেন্টের HTTP client-কে gateway-এর দিকে নির্দেশ করা হয়, এবং এজেন্ট প্রকৃত credential-এর বদলে একটি placeholder credential বহন করে। gateway outbound request-টি এজেন্টের grant-এর সঙ্গে মিলিয়ে দেখে, প্রকৃত secret decrypt করে, request-এ সেটি প্রতিস্থাপন করে এবং request forward করে। Secret-গুলো PostgreSQL-এ AES-256-GCM (advanced encryption standard, 256-bit, Galois/counter mode) ব্যবহার করে encrypted অবস্থায় সংরক্ষিত থাকে এবং কেবল request-এর সময় decrypt করা হয়। প্রতিটি call এজেন্টের identity এবং target-সহ log করা হয়। key যদি দশজনের shell profile-এ রাখা হয়, এই audit trail পাওয়া যায় না।

দুটি প্রক্রিয়া নির্ধারণ করে এটি কীভাবে deploy করবেন।

  • HTTPS interception হলো man-in-the-middle প্রক্রিয়া। gateway একটি local certificate authority তৈরি করে, এজেন্ট সেটিকে trust করে, এবং gateway এজেন্টের TLS connection terminate করে upstream service-এর কাছে একটি নতুন connection খোলে। তাই যে এজেন্টের HTTP client gateway-এর certificate authority trust করে না, সেটি authentication error-এর বদলে certificate verification error দেখিয়ে ব্যর্থ হয়।
  • এজেন্ট নিজেকে একটি Proxy-Authorization header দিয়ে শনাক্ত করে। একই box-এ এজেন্ট এবং gateway যদি একটি internal Docker network শেয়ার করে, তাহলে ওই header আপনার নিয়ন্ত্রণের বাইরের কোনো network অতিক্রম করে না। কোনো off-box এজেন্টকে gateway-এর দিকে নির্দেশ করলে connection-টি VPN বা TLS transport দিয়ে সুরক্ষিত করুন, কারণ ওই header একটি bearer token। raw CONNECT proxy port-এর জন্য upstream একটি VPN ব্যবহারের পরামর্শ দেয়।

প্রকৃত trade-off হলো: নকশা অনুযায়ী gateway আপনার এজেন্টগুলোর করা প্রতিটি request plaintext অবস্থায় পড়ে। এটি machine-এর সবচেয়ে sensitive process। সেই অনুযায়ী host-টিকে সুরক্ষিত রাখুন এবং সর্বনিম্ন privilege-যুক্ত Linux user দিয়ে login করতে পারে এমন মানুষের সংখ্যা কম রাখুন।

রানারের কোনো inbound port প্রয়োজন হয় না

রানার শুধু outbound connection ব্যবহার করে। এর documentation-এ বলা হয়েছে: "এটি এমন কোনো port open রাখে না যেটিতে বাইরের বিশ্ব থেকে পৌঁছানো যায়। তাই NAT-এর পেছনে থাকা laptop, homelab বা VPC—সবই ingress, tunnel এবং TLS termination ছাড়াই কাজ করে।" NAT হলো network address translation, যা home router করে থাকে। রানার control plane-এ outbound connection স্থাপন করে এবং সেখান থেকে কাজ সংগ্রহ করে। তাই কোনো port forward বা open করার প্রয়োজন হয় না।

এই নকশার সুবিধা sandbox network-এ স্পষ্ট। compose file-এ internal: true হিসেবে চিহ্নিত একটি দ্বিতীয় network সংজ্ঞায়িত করা আছে। Docker-এ এর অর্থ হলো এই network-এর external network connectivity নেই। Sandbox-গুলো এতে যুক্ত হয়। Gateway উভয় network-এ dual-homed, তাই বাইরে যাওয়ার একমাত্র পথ এটিই। Runner documentation-এ বিষয়টি স্পষ্টভাবে বলা হয়েছে: "gateway-কে dual-homed করে একটি internal network ব্যবহার করলেই gateway-only egress একটি বাস্তব boundary হয়, শুধু পরামর্শ থাকে না।" কোনো agent external address-এ সরাসরি connection খুলে gateway এড়াতে পারে না। কোন request অনুমোদিত হবে, তা gateway-এর policy-ই নির্ধারণ করে।

উপরের অনুচ্ছেদটি শুধু বিশ্বাস না করে নিজের box-এ এটি নিশ্চিত করুন।

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

আপনি "Internal": true দেখতে পাবেন। সেখানে false দেখা গেলে egress control বন্ধ রয়েছে এবং gateway আবার শুধু একটি পরামর্শে পরিণত হয়েছে। docker network ls যে sandbox network name print করে, সেটিই ব্যবহার করুন, কারণ onecli-sandboxes কেবল default।

OneCLI sandbox কতটা শক্তিশালী?

এই অংশটি ধীরে পড়ুন। কারণ প্রকল্পের নিজস্ব বর্ণনায় “sandboxed” শব্দটির গুরুত্ব অনেক, কিন্তু ব্যবহৃত mechanism-টি runner documentation এবং backend code-এ নথিভুক্ত আছে।

README-তে বলা হয়েছে, প্রতিটি agent “its own isolated sandbox, with a filesystem and a shell” পায়। সেখানে Sandbox Supervisor-কে এমন একটি component হিসেবে উল্লেখ করা হয়েছে, যা “runs inside each sandbox, speaking a vendor-neutral harness interface so the agent runtime is swappable”। এই দুটি বাক্যের কোনোটিই isolation কী দিয়ে তৈরি, তা বলে না। Runner-এর documentation তা স্পষ্ট করে: default backend হলো Docker (RUNNER_BACKEND=docker), এবং sandbox হলো একটি Docker container, যাতে memory cap, CPU cap এবং process cap থাকে এবং যা internal network-এর সঙ্গে যুক্ত। Code-এ অন্যান্য backend ব্যবহারের জন্য একটি seam রয়েছে। বর্তমান runner code-এ Kubernetes backend-ও implement করা হয়েছে, যা Helm chart sandbox Jobs এবং persistent volumes-এর জন্য ব্যবহার করে। এই guide-এর Compose installation-এ sandbox হলো একটি Docker container।

Runner documentation এখন Docker boundary-টি বর্ণনা করে: agent node হিসেবে চলে, তার সঙ্গে no-new-privileges থাকে, সব Linux capability বাদ দেওয়া হয় এবং Docker-এর default seccomp profile ব্যবহৃত হয়। Backend agent-এর durable home-টি শুধু তার sandbox-এ mount করে। তাই বিষয়টিকে সংকীর্ণ অর্থে বিবেচনা করুন। Caps হলো resource cap। Internal network একটি প্রকৃত egress control। Agent এবং আপনার host-এর মধ্যে isolation এই container control-গুলোর ওপর নির্ভর করে, এবং একটি container host kernel share করে।

আরেকটি বিষয়ও বিবেচনায় নিতে হবে। Runner service /var/run/docker.sock mount করে, কারণ sandbox তৈরি করার জন্য এটির সেটিই প্রয়োজন। Rootful Docker daemon-এর socket-এ access থাকা host-এর root access-এর সমতুল্য। কারণ যে ব্যক্তি ওই API call করতে পারে, সে host filesystem container-এর ভেতরে mount করে container চালু করতে পারে। Shipped Docker-backed runner ওই socket ব্যবহার করে। এর ফলে runner process gateway-এর মতোই sensitive। SSH terminator একই socket mount করে, যাতে sandbox container-এর ভেতরে exec করতে পারে। Compose file-এর comment-এও host-এ ওই mount-কে root-equivalent বলা হয়েছে। তাই port 10257 loopback-এ রাখুন, যদি এটি উন্মুক্ত করার নির্দিষ্ট কারণ না থাকে।

Shared-kernel boundary-কে রক্ষণশীলভাবে বিবেচনা করুন। বাস্তবে এর অর্থ তিনটি অভ্যাস।

  1. OneCLI এমন একটি box-এ চালান, যা অন্য কোনো কাজ করে না। কোনো unrelated production service, shared database বা অন্য team-এর data সেখানে রাখবেন না।
  2. ধরে নিন, কোনো agent তার sandbox-এর ভেতরে arbitrary code execution পেলে host-এ পৌঁছাতে পারে। এই পরিস্থিতি সামলানোর জন্য box-এর বাইরে backup রাখুন।
  3. কোনো সহকর্মীকে agent contained আছে বলার আগে apps/runner/src পড়ুন অথবা upstream-কে জিজ্ঞাসা করুন।

Documented boundary কেমন হওয়া উচিত এবং upstream-কে কোন প্রশ্ন করা মূল্যবান, তা দেখতে বাস্তব agent sandbox boundary কেমন দেখায়-এর সঙ্গে এটি তুলনা করুন। মূল প্রশ্ন হলো, documented mechanism আপনার থামাতে চাওয়া threat-গুলো প্রতিহত করার জন্য যথেষ্ট কি না।

লাইসেন্স বিভাজন এবং কেন বিল্ড করার আগে যাচাই করবেন

OneCLI-এর মূল অংশটি Apache-2.0 লাইসেন্সভুক্ত এবং প্রোডাকশনে এটি সেলফ-হোস্ট করা অনুমোদিত। ee/ নামে চিহ্নিত ডিরেক্টরিগুলো একটি আলাদা OneCLI Enterprise License-এর আওতাভুক্ত: এগুলো ডেভেলপমেন্ট, টেস্টিং এবং মূল্যায়নের জন্য বিনামূল্যে ব্যবহার করা যায়, তবে প্রোডাকশন ব্যবহারের জন্য সাবস্ক্রিপশন প্রয়োজন। 18 আগস্ট 2026-এর v2.0.1 রিলিজ নোটে GitHub-এ শনাক্তযোগ্য Apache-2.0 লাইসেন্স ফাইলটি পুনরুদ্ধার করার কথা উল্লেখ করা হয়েছে, তাই রিপোজিটরি পৃষ্ঠার ব্যাজটি সম্প্রতি পরিবর্তিত হয়েছে। অন্য কোনো তারিখে লেখা সারাংশের ওপর নির্ভর না করে আপনি বাস্তবে যে ট্যাগটি ডিপ্লয় করছেন তা যাচাই করুন।

cd onecli && find . -type d -name ee -not -path '*/node_modules/*'

ওই পাথগুলোর অধীনে থাকা যেকোনো কিছু বাণিজ্যিক অংশের অন্তর্ভুক্ত। আপনি যদি এমন কোনো ফিচারের ওপর নির্ভর করার পরিকল্পনা করেন যা সেখানে অবস্থিত, তবে সেটিকে ঘিরে কোনো প্রসেস তৈরি করার আগেই তার মূল্য নির্ধারণ করে নিন।

আপগ্রেড, migration এবং যে একটি ফাইল হারানো যাবে না

আপগ্রেডের সময় service image এবং আলাদা agent image নতুন করতে হবে। এরপর চলমান sandbox পুনরায় চালু করতে হবে। প্রতিটি up-এ API চালুর আগে একটি one-shot migration service চলে। কোনো migration ব্যর্থ হলে stack চালু হতে অস্বীকার করে। ফলে অর্ধেক migration সম্পন্ন schema ব্যবহার করে service চালু থাকে না। এটিই প্রত্যাশিত আচরণ। কারণ ব্যর্থ আপগ্রেড তখন outage হিসেবে দেখা যায়, নীরব data corruption হিসেবে নয়। docker compose logs migrations-এ এর কারণ ব্যাখ্যা করা হয়েছে।

একটি ধাপ সহজেই বাদ পড়ে। self-hosting নথিতে bare docker compose pull && docker compose up -d দিয়ে আপগ্রেড না করতে বলা হয়েছে। কারণ agent sandbox image কোনো Compose service নয়। এটি runner-এর RUNNER_AGENT_IMAGE value। তাই docker compose pull এটি দেখতে পায় না। ফলে hosted agent-গুলো কোনো সতর্কতা ছাড়াই পুরোনো sandbox image ব্যবহার করতে পারে। checkout আপডেট করুন, pin পরিবর্তন করুন এবং নথিভুক্ত upgrade tool চালান। এই tool sandbox image pull করে এবং চলমান sandbox পুনরায় চালু করে।

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 migrations

2.17.0-এর জায়গায় যে release-এ আপগ্রেড করছেন সেটি বসান। Sandbox পুনরায় চালু করলে চলমান কাজ সাময়িকভাবে বাধাগ্রস্ত হয়। প্রতিটি agent-এর durable workspace অক্ষত থাকে।

আপনি যদি install script ব্যবহার করে install করে থাকেন, তাহলে হাতে image pull না করে সেই script আবার চালান। এতে compose file তার ব্যবহৃত image-গুলোর সঙ্গে সামঞ্জস্যপূর্ণ থাকে। নির্দিষ্ট release ব্যবহার করতে চাইলে আগে ONECLI_VERSION export করুন। কারণ script শুধু তার .env file-এ রাখা pin override করে।

Database, configuration এবং agent workspace volume-এর backup নিন। PostgreSQL agent, conversation, memory এবং encrypted secret সংরক্ষণ করে। docker/.env file-এ SECRET_ENCRYPTION_KEY থাকে। এই key ছাড়া database-এর বাকি অংশ restore করা হলেও encrypted secret পড়া যায় না। প্রতিটি agent-এর /workspace আলাদা durable volume-এ থাকে। তাই প্রতিটির নিজস্ব backup প্রয়োজন।

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

এই copy এবং workspace backup server-এর বাইরে সংরক্ষণ করুন। এই পদ্ধতি যেকোনো stateful Compose stack-এর মতোই। তাই আপনি যদি নিয়মিত Docker Compose stack-এর backup ও upgrade নিয়ে থাকেন, এতে database, configuration এবং workspace volume যোগ করুন। এরপর এটি নিয়মিত চালু রাখুন।

যখন এটি কাজ করে না

  • Stack কখনও healthy অবস্থায় আসে না এবং docker compose up -d --wait non-zero status নিয়ে বন্ধ হয়। প্রথমে docker compose logs migrations পড়ুন, কারণ API ইচ্ছাকৃতভাবে ওই service-এর জন্য অপেক্ষা করে।
  • একটি agent idle অবস্থায় থাকে এবং কোনো sandbox দেখা যায় না। COMPOSE_PROFILES=runner, docker/.env-এর মধ্যে আছে কি না এবং docker compose ps কোনো runner দেখাচ্ছে কি না পরীক্ষা করুন। এরপর agent-টির জন্য granted model key আছে কি না দেখুন, কারণ এটি ছাড়া sandbox চালু হয় না।
  • কোনো slot খালি নেই। RUNNER_MAX_SANDBOXES-এর default মান 4। Background process চলমান থাকা একটি sandbox-এর slot held-awake ceiling সেটিকে সরিয়ে না দেওয়া পর্যন্ত ধরে রাখে। বাস্তবে কোনগুলো চালু আছে, তা docker ps দেখায়।
  • Stack start হয় না এবং Docker জানায় যে একটি port ইতিমধ্যে ব্যবহৃত হচ্ছে। runner profile চালু থাকলে SSH front door-এর জন্য অন্য চারটি port-এর পাশাপাশি 10257-ও প্রয়োজন।
  • Container অদৃশ্য হয়ে যায়, অথবা host অত্যন্ত ধীর হয়ে যায়। dmesg -T | grep -i oom দিয়ে memory exhaustion পরীক্ষা করুন; default memory cap অনুযায়ী একটি sandbox সর্বোচ্চ 2048 MB ব্যবহার করতে পারে।
  • কোনো agent-এর HTTPS call authentication error-এর পরিবর্তে certificate verification error নিয়ে ব্যর্থ হয়। এর HTTP client gateway-এর certificate authority-কে trust করে না।
  • কোনো agent delete করার পর পুরোনো container বা volume থেকে যায়। Runner প্রতি 60 সেকেন্ডে reconciliation চালায় এবং RUNNER_ORPHAN_GRACE_SECONDS-এর চেয়ে পুরোনো orphan ধ্বংস করে। এর default মান 3600। তাই এটিকে leak বলার আগে এক ঘণ্টা অপেক্ষা করুন।

এটি কি আপনার ব্যবহারের জন্য সঠিক সমাধান?

ফিট টেস্টটি সংক্ষিপ্ত। যখন একাধিক ব্যক্তির জন্য আলাদা এজেন্টের প্রয়োজন হয় এবং আপনি সব ক্রেডেনশিয়াল এক জায়গায় রাখতে চান, তখন OneCLI কার্যকর হয়: একটি স্টোর যেখানে রোটেশন করা যায়, একটি অডিট লগ যা পড়া যায়, এবং একটি ড্যাশবোর্ড যেখানে কারো অ্যাক্সেস বাতিল করলে তা কার্যকর হয়। এটি একটি বাস্তব অপারেশনাল সমস্যা, এবং ছয়টি ল্যাপটপে একটি API key কপি করা এর কোনো ভালো সমাধান নয়।

একজনের জন্য কোনো ব্যবহারিক লাভ ছাড়াই এটি অপ্রয়োজনীয়ভাবে জটিল। নিজেকে একটি agent দেওয়ার জন্য আপনাকে PostgreSQL, একটি control plane, একটি gateway এবং একটি runner চালাতে হবে। gateway যে credential সমস্যার সমাধান করে, একমাত্র key-এর ধারক যখন আপনি নিজেই, তখন সেই সমস্যা প্রায় থাকেই না। এর বদলে ছোট একটি box-এ একটি harness চালান: একটি VPS-এ single agent harness একই কাজ অনেক কম memory-তে করে। আপনি যদি এখনো কোনো দিকই নির্ধারণ না করে থাকেন, তাহলে self-hosted AI agent-এর তুলনা-সংক্রান্ত survey-টি কম খরচের প্রথম পদক্ষেপ। আপনার কাছে অপরিচিত বিষয়টি যদি agent নিজেই হয়, সেগুলো যে server-এ চলে তা নয়, তাহলে আগে agent কীভাবে বাস্তবে কাজ করে তা শেখার ধাপে ধাপে পথ অনুসরণ করুন। কারণ tool call এবং memory store আসলে কী করে তা জানলেই বোঝা যায়, প্রতিটি ব্যক্তির agent-কে কোন grant দেওয়া উচিত।

FAQ

OneCLI self-host করার জন্য ন্যূনতম server requirement কী?

এখানে ব্যবহৃত setup wizard-এর জন্য Compose plugin-সহ Docker 2.24.0 বা পরবর্তী সংস্করণ, Node.js, pnpm এবং পর্যাপ্ত memory প্রয়োজন। PostgreSQL compose file-এর সঙ্গেই থাকে, তাই এটি আলাদাভাবে install করতে হয় না। পরিকল্পনা নির্ধারণ করে memory: runner ডিফল্টভাবে প্রতিটি agent sandbox-এর সীমা 2048 MB রাখে, এবং default চারটি sandbox চালানোর জন্য base stack-এর অতিরিক্ত প্রায় 10 GiB free memory রাখার পরামর্শ documentation-এ দেওয়া আছে। Chart-এ ধরে নেওয়া 2 GB base-stack budget অনুযায়ী, 4 GB server-এ পূর্ণ সীমায় একটি sandbox চালানোর memory থাকে এবং 16 GB server default concurrency cap পূরণ করে। এগুলো পরিকল্পনার হিসাব; পরিমাপ করা ন্যূনতম requirement বা নির্দিষ্ট memory allocation নয়।

OneCLI-এর কি PostgreSQL দরকার, নাকি SQLite ব্যবহার করা যায়?

PostgreSQL প্রয়োজন। DATABASE_URL-কে PostgreSQL connection string হিসেবে নথিভুক্ত করা হয়েছে, সরবরাহ করা compose file postgres:18-alpine-কে pgdata volume-সহ চালায়, এবং API start হওয়ার আগে একটি পৃথক migrations service schema প্রয়োগ করে। SQLite ব্যবহারের কোনো option নথিভুক্ত নেই। External PostgreSQL server ব্যবহার করতে হলে API এবং migrations service—উভয়কেই সেটি ব্যবহার করার জন্য configure করুন; সরবরাহ করা compose file-এ তাদের connection string bundled PostgreSQL service-এর দিকে নির্ধারিত থাকে।

OneCLI agent sandbox কি প্রকৃত security boundary?

নথিভুক্ত Compose mechanism হলো একটি Docker container, যেখানে memory, CPU এবং process cap নির্ধারিত থাকে। এটি internal: true হিসেবে চিহ্নিত একটি network-এর সঙ্গে যুক্ত থাকে, যাতে external traffic gateway-এর মধ্য দিয়ে যায়। Egress control কার্যকর, এবং docker network inspect দিয়ে তা যাচাই করতে পারেন। Agent node হিসেবে চলে, no-new-privileges সহ; সব Linux capability বাদ দেওয়া থাকে এবং Docker-এর default seccomp profile ব্যবহৃত হয়। তবে এটি host kernel share করে। Runner এবং SSH terminator উভয়েই /var/run/docker.sock mount করে। Rootful Docker daemon ব্যবহার করা host-এ এটি root access-এর সমতুল্য। OneCLI একটি dedicated server-এ চালান এবং backup ওই server-এর বাইরে রাখুন।

OneCLI-এর জন্য কি কোনো inbound port খুলতে হবে?

না। Runner শুধু outbound connection ব্যবহার করে এবং বাইরে থেকে পৌঁছানো যায় এমন কোনো port ধরে রাখে না। তাই tunnel ছাড়াই এটি NAT-এর পেছনে কাজ করে। Compose file ডিফল্টভাবে dashboard, gateway, API, PostgreSQL এবং runner profile-এর অধীনে SSH front door-এর 10257 port 127.0.0.1-এ bind করে। SSH tunnel-এর মাধ্যমে dashboard-এ পৌঁছান। একাধিক ব্যক্তির প্রয়োজন হলে TLS-সহ upstream-এর reverse proxy configuration এবং প্রয়োজনীয় dashboard, API ও gateway route ব্যবহার করুন। মনে রাখবেন, registration-এ যে কেউ পৌঁছাতে পারলে তা খোলা থাকে। 10255 port-এর gateway agent-দের জন্য ব্যবহৃত হয়। একটি server-এ ওই agent-গুলো internal Docker network-এর মাধ্যমে gateway-এ পৌঁছায়।

কোনো company-র ভেতরে OneCLI বিনামূল্যে ব্যবহার করা যায়?

Core অংশ Apache-2.0-এর অধীন, এবং commercial licence ছাড়াই self-hosted production use অনুমোদিত। ee/ নামে থাকা directory-গুলো OneCLI Enterprise License-এর আওতায় পড়ে। Development, testing এবং evaluation-এর জন্য এটি বিনামূল্যে, কিন্তু production-এ subscription প্রয়োজন। Release অনুযায়ী এই বিভাজন পরিবর্তিত হয়। 18 August 2026-এর v2.0.1 notes-এ GitHub শনাক্ত করতে পারে এমন Apache-2.0 licence file পুনরায় যুক্ত করার কথা বলা হয়েছে। তাই কোনো একটি feature-এর ওপর workflow নির্ভর করে তৈরি করার আগে যে exact tag deploy করবেন, তাতে LICENSE এবং ee/ directory পরীক্ষা করুন।

এই লেখাটি কি কাজে লেগেছে?