SSD Nodes Learn Hosting plans →
راهنماها Matt Connorتوسط Matt Connor

میزبانی شخصی OneCLI؛ یک agent برای هر نفر

OneCLI برای هر نفر یک agent ایزوله می‌سازد و کلیدها را در یک gateway نگه می‌دارد. راه‌اندازی با Docker Compose و PostgreSQL، با نیاز واقعی 2 GiB رم برای هر sandbox.

مزایای میزبانی شخصی OneCLI

با میزبانی شخصی OneCLI، هر یک از اعضای تیم شما صاحب یک agent اختصاصی می‌شود که در sandbox مجزای خود اجرا می‌گردد. کلیدهای API در یک gateway نگهداری می‌شوند و agentها هرگز به آن‌ها دسترسی مستقیم ندارند. نصب این سرویس از طریق یک stack شامل Docker Compose و یک دیتابیس PostgreSQL انجام می‌شود که در http://localhost:10254 در دسترس است. برای این کار یک سرور واقعی در نظر بگیرید. مقدار پیش‌فرض مستند شده برای هر sandbox، سقف حافظه 2 GiB است؛ بنابراین بودجه‌بندی حافظه را برای stack پایه و حافظه کاری واقعی agentها به‌صورت جداگانه انجام دهید.

این stack شامل هشت بخش است که شناخت هر یک، مطالعه ادامه این راهنما را آسان‌تر می‌کند.

  • داشبورد وب (Next.js)، پورت 10254. برای ایجاد agent، چت، ویرایش حافظه و مهارت‌ها، و مدیریت اتصالات و secrets.
  • سرور API، پورت 10256. صفحه کنترل: شامل دیتابیس، مدیریت گفتگوها و صف‌های کاری.
  • Gateway مبتنی بر Rust، پورت 10255. درخواست‌های خروجی از agentها را رهگیری کرده و credentials را تزریق می‌کند.
  • Runner. در فایل README به‌عنوان مؤلفه‌ای توصیف شده که "sandboxهای agent را راه‌اندازی، متوقف و پاکسازی می‌کند. فقط خروجی است و هرگز با دیتابیس تعامل ندارد."
  • Sandbox Supervisor. در فایل README به‌عنوان مؤلفه‌ای توصیف شده که "درون هر sandbox اجرا می‌شود و با یک رابط harness مستقل از فروشنده ارتباط برقرار می‌کند تا runtime مربوط به agent قابل جایگزینی باشد."
  • SSH terminator، پورت 10257. در فایل README به‌عنوان "دروازه ورودی SSH" شناخته می‌شود: این بخش SSH را با گواهی‌های کوتاه‌مدت صادر شده توسط API خاتمه داده و هر نشست را به sandbox یک agent متصل می‌کند. این بخش تحت همان پروفایل runner مربوط به runner اجرا می‌شود.
  • Channel adapter. یک daemon که به یک Slack app متصل می‌شود تا agent بتواند در کانال‌ها و پیام‌های مستقیم (DM) با نام اختصاصی خود پاسخ دهد.
  • PostgreSQL. فایل compose ارائه شده، postgres:18-alpine را با یک volume از نوع pgdata اجرا می‌کند.

نام CLI است، اما محصول یک سرور است

OneCLI یک پلتفرم سروری است. نام آن به ابزار خط فرمانی اشاره دارد که روی لپ‌تاپ نصب می‌کنید، اما این تصور برای چیزی که در این راهنما معرفی می‌شود، نادرست است. یک کلاینت خط فرمان مجزا در مخزن onecli/onecli-cli وجود دارد که ترافیک یک agent کدنویسی محلی را از طریق یک gateway هدایت می‌کند. آنچه شما در اینجا مستقر می‌کنید، یک برنامه وب چندکاربره است: یک سیستم حساب کاربری با سازمان‌ها و دعوت‌نامه‌ها، پایگاه داده‌ای از گفتگوها و اسرار، و یک runner که کانتینرها را اجرا می‌کند.

مدل «هر نفر یک agent» کل طراحی این سیستم است. در فایل README آمده است: «شما برای هر نفر یک agent ایجاد می‌کنید، دسترسی‌های لازم را به آن می‌دهید و agent در یک sandbox کار می‌کند؛ این ارتباط از طریق gatewayای هدایت می‌شود که اعتبارنامه‌ها را تزریق کرده و سیاست‌های شما را اعمال می‌کند.» هر agent دارای فایل‌سیستم و shell اختصاصی، صفحه گفتگوی مجزا، حافظه‌ای که پلتفرم نگهداری می‌کند و مهارت‌هایی است که یک‌بار می‌نویسید. نحوه کارکرد اعتبارنامه‌ها در اینجا برعکس مدل‌های معمول است. به‌جای کپی کردن یک API key در محیط هر شخص، شما کلید را یک‌بار ذخیره کرده و آن را به agentهایی که اجازه استفاده از آن را دارند، اختصاص می‌دهید.

پیش‌نیازهای لازم برای شروع کار

  • Docker به همراه افزونه Compose نسخه 2.24.0 یا جدیدتر. فایل compose ارائه شده از نگاشت‌های اختیاری env_file با required: false استفاده می‌کند که Docker از نسخه 2.24.0 از آن‌ها پشتیبانی می‌کند. توضیحات مربوط به مهاجرت در این نسخه، حداقل نسخه 2.19 را برای پشتیبانی از وابستگی‌های یک‌باره (one-shot) تحت up --wait ذکر کرده است، اما این موضوع شامل فایل‌های محیطی (environment files) اختیاری این فایل نمی‌شود.
  • حافظه (RAM)، که محدودیت اصلی است. پیش از انتخاب پلن، بخش مربوط به تعیین اندازه (sizing) را در ادامه مطالعه کنید.
  • پورت‌های آزاد loopback شامل 10254، 10255، 10256، 10257 و 5432. پورت 10257 درگاه ورودی SSH است که با پروفایل runner که در این راهنما فعال می‌شود، شروع به کار می‌کند.

نیازی نیست PostgreSQL را شخصاً نصب کنید: فایل compose آن را به عنوان یک سرویس اجرا می‌کند. ویزارد راه‌اندازی در ادامه، به Node.js و pnpm روی میزبان نیاز دارد. کار بر روی خود کد نیز از mise برای تعیین دقیق نسخه ابزارها (pinning toolchain) استفاده می‌کند که شامل Rust برای gateway نیز می‌شود.

چند sandbox عامل (agent) روی VPS شما جای می‌گیرد؟

مستندات خودِ runner به‌جای حدس و گمان، اعداد واقعی را ارائه می‌دهد. هر sandbox به 2048 مگابایت حافظه (RUNNER_SANDBOX_MEMORY_MB)، یک CPU (RUNNER_SANDBOX_CPUS) و 512 پردازش (RUNNER_SANDBOX_PIDS) محدود شده است. سقف هم‌زمانی (concurrency) برابر با 4 (RUNNER_MAX_SANDBOXES) است و مستندات توصیه می‌کند برای پشتیبانی از این سقف، حدود 10 گیگابایت حافظه آزاد علاوه بر پشته (stack) پایه در نظر بگیرید.

نمودار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
  }
]

این تعداد جایگاه‌ها یک محاسبه ریاضی است، نه یک بنچمارک: کل حافظه، منهای حدود 2 گیگابایت فرض‌شده برای PostgreSQL و سایر سرویس‌های در حال اجرا، تقسیم بر سقف 2 گیگابایتی هر sandbox. بر این اساس، 2 GB box بودجه‌ای برای 0 عدد sandbox با سقف کامل حافظه در نظر می‌گیرد؛ عدد صفر به این معنی نیست که Docker از اجرای عامل خودداری می‌کند، بلکه یعنی تحت این فرضیات، بودجه‌ای برای سقف کامل وجود ندارد. یک 16 GB box فضایی برای 7 فراهم می‌کند که به‌راحتی بالاتر از سقف پیش‌فرض چهار و فراتر از 10 گیگابایت حافظه آزاد توصیه‌شده در مستندات runner است. گزینه 32 GB box شما را به 15 می‌رساند. اجرای بیش از چهار مورد به‌طور هم‌زمان، نیازمند افزایش RUNNER_MAX_SANDBOXES نیز هست.

دو عامل این محاسبات را تغییر می‌دهند. یک sandbox که پردازشی در پس‌زمینه دارد، هرگز متوقف (park) نمی‌شود، بنابراین جایگاه خود را به‌طور دائم اشغال می‌کند؛ این یعنی شما باید RUNNER_MAX_SANDBOXES را برای بار کاری پایدار تنظیم کنید، نه برای شلوغ‌ترین لحظه. پلتفرم برای این مورد سقف تعیین کرده است: به‌طور پیش‌فرض هر runner حداکثر RUNNER_MAX_SANDBOXES منهای یک sandbox فعال را نگه می‌دارد (هرگز کمتر از یک، قابل بازنویسی با MAX_HELD_AWAKE_SANDBOXES در API) و فراتر از آن، قدیمی‌ترین sandbox بیکار را حذف کرده و پردازش تحت نظارت آن را به‌عنوان ازدست‌رفته گزارش می‌کند. مصرف حافظه و CPU به نوع کار بستگی دارد. هر sandbox به یک CPU محدود است، بنابراین چهار عامل مشغول می‌توانند از چهار هسته استفاده کنند، اما تنظیم 2 گیگابایت حافظه یک سقف است، نه یک رزرو: چهار عاملِ بیکار اما فعال، به‌طور خودکار 8 گیگابایت حافظه مصرف نمی‌کنند.

تنظیمات runner که ممکن است بخواهید تغییر دهید
  • RUNNER_MAX_SANDBOXES (پیش‌فرض 4): تعداد sandboxهایی که هم‌زمان اجرا می‌شوند.
  • RUNNER_SANDBOX_MEMORY_MB (پیش‌فرض 2048): سقف حافظه برای هر sandbox.
  • RUNNER_SANDBOX_CPUS (پیش‌فرض 1): سقف CPU برای هر sandbox.
  • RUNNER_SANDBOX_PIDS (پیش‌فرض 512): سقف پردازش برای هر sandbox.
  • RUNNER_NETWORK_INTERNAL (پیش‌فرض true): شبکه sandbox را بدون مسیر خروجی نگه می‌دارد. آن را فعال بگذارید.
  • RUNNER_SANDBOX_NETWORK (پیش‌فرض onecli-sandboxes): شبکه‌ای که sandboxها به آن متصل می‌شوند.
  • RUNNER_RECONCILE_SECONDS (پیش‌فرض 60): تناوب زمانی که runner وضعیت را تطبیق می‌دهد.
  • RUNNER_ORPHAN_GRACE_SECONDS (پیش‌فرض 3600): سنی که پس از آن کانتینرها و volumeهای یتیم (orphaned) حذف می‌شوند.
  • RUNNER_AGENT_IMAGE: تصویر (image) sandbox را بازنویسی می‌کند، که در غیر این صورت از ONECLI_VERSION پیروی می‌کند.

نصب OneCLI با Docker Compose

مستندات اصلی self-hosting در توالی اولیه خود، سه secret را در docker/.env در کنار فایل compose می‌نویسد. آن توالی، runner token، گروه Docker socket و اعتبارنامه‌های 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 بدون کوتیشن است، بنابراین shell شما هر head -c 32 /dev/urandom | base64 را اجرا کرده و نتیجه را می‌نویسد، نه متن تحت‌اللفظی آن را. SECRET_ENCRYPTION_KEY کلید AES-256-GCM برای تمام secretهای موجود در دیتابیس است. GATEWAY_INTERNAL_SECRET هویت gateway را برای API تأیید می‌کند. BETTER_AUTH_SECRET کوکی‌های نشست (session cookies) را امضا می‌کند. COMPOSE_PROFILES=runner مهم‌ترین خط است، زیرا سرویس runner پشت یک Compose profile قرار دارد: اگر آن را حذف کنید، stack بدون مشکل بالا می‌آید اما هیچ agent sandboxای شروع به کار نخواهد کرد.

--wait منتظر می‌ماند تا سرویس‌ها در وضعیت running یا healthy قرار بگیرند و وابستگی migrations با موفقیت تکمیل شود؛ بنابراین خروجی غیر صفر (non-zero exit)، اولین نشانه شما از وجود مشکل است. سپس بررسی کنید چه چیزی واقعاً بالا آمده است.

docker compose ps
docker compose logs migrations

نسخه را ثابت (pin) کنید. ONECLI_VERSION تگ تمام سرویس‌ها را به‌طور هم‌زمان تنظیم می‌کند و image مربوط به agent sandbox نیز از آن پیروی می‌کند، مگر اینکه RUNNER_AGENT_IMAGE به جای دیگری اشاره کند. از شماره نسخه خام استفاده کنید: تگ‌های منتشرشده image فاقد پیشوند v هستند. تا تاریخ 1 November 2026، نسخه فعلی v2.17.0 است که در 31 October 2026 منتشر شده است. آن را به همان فایل اضافه کنید و سپس از مسیر ارتقای مستندشده استفاده کنید تا sandboxهای در حال اجرا نیز به آن image منتقل شوند.

echo 'ONECLI_VERSION=2.17.0' >> .env
cd ..
pnpm run setup --upgrade
cd docker

یک نصب‌کننده به نام curl -fsSL https://onecli.sh/install | sh نیز وجود دارد که پیکربندی خود را در ~/.onecli/.env می‌نویسد و همان کار را انجام می‌دهد. این ابزار برای اجرای خود ONECLI_VERSION=latest را تنظیم می‌کند که جایگزین نسخه ثابت‌شده در فایل .env می‌شود. مسیر Compose روشی است که در آن می‌توانید پیش از اجرای هر چیزی، تمام فایل‌ها را بخوانید؛ این روش برای سروری که از قبل stackهای Compose دیگری روی آن در حال اجراست، مناسب است. روش checkout در بالا، با استفاده از pnpm run setup --upgrade ارتقا می‌یابد. آن مسیر به Node.js و pnpm روی host نیاز دارد و کار روی خود کد، mise و Rust را برای gateway اضافه می‌کند؛ بنابراین برای کسانی که قصد تغییر در OneCLI را دارند مناسب است. برای Kubernetes، نسخه v2.11.0 (مورخ 8 October 2026) یک Helm chart اضافه کرد؛ chart فعلی، agent sandboxها را به عنوان Job با persistent volume و بدون نیاز به Docker daemon اجرا می‌کند و مستندات مربوط به secretها، دیتابیس و پیکربندی مسیریابی را نیز ارائه می‌دهد.

دسترسی به داشبورد از لپ‌تاپ

هر پورتی که در فایل compose ارائه‌شده منتشر می‌شود، به ${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 یعنی onecli (مگر اینکه POSTGRES_PASSWORD را تنظیم کرده باشید) در دسترس قرار می‌دهد. این کار همچنین درگاه SSH را روی پورت 10257 منتشر می‌کند؛ سرویسی که Docker socket را mount می‌کند. اگر چندین نفر به داشبورد نیاز دارند، یک reverse proxy با TLS (امنیت لایه انتقال) در مقابل آن قرار دهید و bind host را تغییر ندهید. مقدار ONECLI_EXTERNAL_URL را روی URL HTTPS آن تنظیم کنید و از پیکربندی reverse proxy ارائه‌شده توسط upstream استفاده کنید که مسیرهای داشبورد، API و gateway را به سرویس‌های مربوطه هدایت می‌کند. یک پروکسی به‌تنهایی مانع دسترسی افراد غریبه نمی‌شود. مستندات self-hosting بیان می‌کند که ثبت‌نام به‌صورت پیش‌فرض باز است و هیچ کلیدی برای غیرفعال کردن آن وجود ندارد: هر کسی که به داشبورد دسترسی پیدا کند می‌تواند یک حساب کاربری ایجاد کند که سازمان مخصوص به خود را خواهد داشت، و تنها عضویت در سازمان شما نیاز به دعوت‌نامه دارد. توصیه این است که داشبورد را پشت مرز شبکه خود نگه دارید. اگر آن پروکسی در حال حاضر در مقابل سایر برنامه‌های self-hosted شما قرار دارد، استفاده از forward auth از طریق یک لایه single sign-on خودمیزبان، داشبورد را پشت سیستم ورودی که تیم شما از قبل دارد قرار می‌دهد، بنابراین حذف دسترسی یک نفر در یک نقطه، این در را نیز می‌بندد.

ایجاد اولین حساب کاربری و سپس اعطای کلید مدل

داشبورد را باز کرده و بلافاصله حساب کاربری خود را ایجاد کنید. هر حساب جدید، سازمان (organization) اختصاصی خود را دارد و هم‌تیمی‌ها از طریق دعوت‌نامه به سازمان شما ملحق می‌شوند. ثبت‌نام پس از آن باز می‌ماند، که این خود دلیل دیگری است که چرا داشبورد باید پشت یک تونل یا یک پروکسی احراز هویت‌شده قرار بگیرد. اگر در حال ارتقا از نسخه‌ای هستید که پیش از سیستم ورود به سیستم (logins) منتشر شده، فوراً ثبت‌نام کنید: مستندات self-hosting بیان می‌کنند که داده‌های موجود به اولین حسابی که ثبت‌نام کند اختصاص می‌یابد، بنابراین در یک میزبان قابل دسترس، می‌خواهید آن حساب متعلق به شما باشد.

سپس پیش از ایجاد یک agent، یک کلید مدل (model key) ذخیره کنید. یک agent میزبانی‌شده نیاز به یک کلید مدل اعطا شده دارد و ترتیب انجام این کار مهم است: کلید را در داشبورد ذخیره کنید، آن را به agent اعطا کنید و تنها پس از آن گفتگو را شروع کنید. اگر مرحله اعطا را نادیده بگیرید، sandbox هرگز اجرا نمی‌شود؛ agent در همان رشته گفتگو پاسخ می‌دهد و توضیح می‌دهد که به یک کلید مدل نیاز دارد.

اعطا را به‌صورت محدود انجام دهید. هر agent تنها به آنچه به آن اعطا کرده‌اید دسترسی دارد و gateway این موضوع را در هر درخواست اعمال می‌کند، بنابراین agentای که یک مخزن (repository) را می‌خواند، هیچ راهی به کلید ارائه‌دهنده پرداخت شما ندارد. همین لیست اعطا، اهرم شما برای کنترل هزینه‌هاست. یک agent شخصی که می‌تواند هر مدلی که مالک آن هستید را فراخوانی کند، به معنای یک صورت‌حساب برای هر شخص است، بنابراین پیش از آنکه ده مورد از آن‌ها را توزیع کنید، ارزش دارد که محدود کردن هزینه‌های یک agent برای فراخوانی مدل‌ها را مطالعه کنید.

چگونه گیت‌وی کلیدها را از دسترس ایجنت‌ها دور نگه می‌دارد

گیت‌وی یک پروکسی HTTPS است که با زبان Rust نوشته شده و روی پورت 10255 گوش می‌دهد. کلاینت HTTP ایجنت به سمت این گیت‌وی تنظیم می‌شود و ایجنت به‌جای اعتبارنامه واقعی، یک اعتبارنامه جایگزین (placeholder) حمل می‌کند. گیت‌وی درخواست خروجی را با دسترسی‌های (grants) آن ایجنت تطبیق می‌دهد، رمز واقعی را رمزگشایی می‌کند، آن را در درخواست جای‌گذاری کرده و سپس ارسال می‌کند. رمزها در PostgreSQL با استاندارد AES-256-GCM (استاندارد رمزنگاری پیشرفته، 256 بیتی، حالت Galois/counter) ذخیره شده و فقط در زمان درخواست رمزگشایی می‌شوند. هر فراخوانی با هویت ایجنت و مقصد آن ثبت (log) می‌شود؛ این یک مسیر حسابرسی (audit trail) است که وقتی کلیدها در پروفایل shell ده نفر مختلف پراکنده باشند، به آن دسترسی نخواهید داشت.

دو مکانیسم نحوه استقرار آن را تعیین می‌کنند.

  • رهگیری HTTPS در واقع یک حمله man-in-the-middle است. گیت‌وی یک مرجع صدور گواهی (CA) محلی تولید می‌کند، ایجنت به آن اعتماد می‌کند، و گیت‌وی اتصال TLS ایجنت را خاتمه داده و یک اتصال جدید به سرویس بالادستی (upstream) باز می‌کند. به همین دلیل است که اگر کلاینت HTTP ایجنت به مرجع صدور گواهی گیت‌وی اعتماد نداشته باشد، با خطای تایید گواهی (certificate verification error) مواجه می‌شود، نه خطای احراز هویت.
  • ایجنت خود را با هدر Proxy-Authorization شناسایی می‌کند. روی یک ماشین واحد، جایی که ایجنت‌ها و گیت‌وی یک شبکه داخلی Docker مشترک دارند، این هدر هرگز از شبکه‌ای که تحت کنترل شما نیست عبور نمی‌کند. اگر ایجنتی خارج از ماشین را به گیت‌وی متصل می‌کنید، حتماً اتصال را با VPN یا لایه انتقال TLS محافظت کنید، زیرا آن هدر یک bearer token محسوب می‌شود؛ تیم بالادستی برای پورت خام CONNECT proxy استفاده از VPN را توصیه می‌کند.

معامله صادقانه: گیت‌وی طبق طراحی، تمام درخواست‌هایی که ایجنت‌های شما ارسال می‌کنند را به صورت متن ساده (plaintext) می‌خواند. این حساس‌ترین پردازش روی ماشین است. با میزبان آن مطابق با همین حساسیت رفتار کنید و تعداد افرادی که اجازه ورود (login) دارند را با استفاده از کاربران لینوکس با حداقل دسترسی محدود نگه دارید.

چرا runner به هیچ پورت ورودی نیاز ندارد

این runner فقط به صورت outbound (خروجی) عمل می‌کند. طبق مستندات آن: «این برنامه هیچ پورتی را که دنیای خارج بتواند به آن دسترسی داشته باشد باز نمی‌کند، بنابراین یک لپ‌تاپ، یک homelab یا یک VPC پشت NAT، همگی بدون نیاز به ingress، تونل یا پیاده‌سازی TLS termination کار می‌کنند.» NAT یا همان Network Address Translation، مکانیزمی است که روترهای خانگی از آن استفاده می‌کنند. runner با برقراری ارتباط خروجی با control plane، وظایف را از آن دریافت می‌کند؛ بنابراین نیازی به forward کردن پورت یا باز کردن هیچ مسیری نیست.

این طراحی در شبکه sandbox نتیجه‌بخش است. فایل compose یک شبکه دوم را تعریف می‌کند که با internal: true مشخص شده است؛ این در Docker به معنای عدم وجود اتصال به شبکه خارجی است. sandboxها به این شبکه متصل می‌شوند. gateway در هر دو شبکه حضور دارد (dual-homed)، بنابراین تنها راه خروج از آن است. مستندات runner این نکته را به صراحت بیان می‌کند: «یک شبکه internal که gateway در آن به صورت dual-homed قرار گرفته، باعث می‌شود خروج از طریق gateway یک مرز قطعی باشد، نه صرفاً یک پیشنهاد.» یک agent نمی‌تواند با باز کردن اتصال مستقیم به یک آدرس خارجی، gateway را دور بزند؛ چرا که سیاست‌های gateway همچنان تعیین می‌کند کدام درخواست‌ها مجاز هستند.

به جای اعتماد به پاراگراف بالا، این موضوع را روی سیستم خود بررسی کنید.

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

شما باید "Internal": true را مشاهده کنید. اگر مقدار آن false باشد، کنترل خروجی غیرفعال است و gateway دوباره تنها یک پیشنهاد محسوب می‌شود. از هر نامی که docker network ls برای شبکه sandbox چاپ می‌کند استفاده کنید، زیرا onecli-sandboxes فقط مقدار پیش‌فرض است.

میزان امنیت sandbox در OneCLI چقدر است؟

این بخش را با دقت مطالعه کنید، زیرا واژه «sandboxed» در توضیحات پروژه بار معنایی زیادی دارد، در حالی که جزئیات مکانیزم آن در مستندات runner و کدهای backend نهفته است.

در فایل README ذکر شده که هر agent «یک sandbox ایزوله با فایل‌سیستم و shell اختصاصی خود» دارد و از Sandbox Supervisor به عنوان مؤلفه‌ای یاد شده که «درون هر sandbox اجرا می‌شود و با یک رابط استاندارد و مستقل از فروشنده ارتباط برقرار می‌کند تا runtime ایجنت قابل جایگزینی باشد». هیچ‌کدام از این جملات مشخص نمی‌کنند که این ایزولاسیون دقیقاً از چه چیزی تشکیل شده است. مستندات runner این موضوع را روشن می‌کند: backend پیش‌فرض Docker است (RUNNER_BACKEND=docker) و هر sandbox یک کانتینر Docker با محدودیت حافظه، CPU و تعداد پردازش است که به شبکه داخلی متصل شده است. کد برنامه برای پشتیبانی از backendهای دیگر نیز انعطاف‌پذیر است. کد فعلی runner یک backend برای Kubernetes نیز پیاده‌سازی کرده که Helm chart از آن برای Jobهای sandbox و volumeهای دائمی استفاده می‌کند. در نصب Compose که در این راهنما آمده، هر sandbox یک کانتینر Docker است.

مستندات runner اکنون مرزهای Docker را این‌گونه توصیف می‌کند: ایجنت با کاربر node اجرا می‌شود، دارای no-new-privileges است، تمامی قابلیت‌های (capabilities) لینوکس از آن سلب شده و از پروفایل پیش‌فرض seccomp در Docker استفاده می‌کند. backend تنها دایرکتوری home دائمی ایجنت را در sandbox آن mount می‌کند. بنابراین، برداشت دقیق از این موضوع این است: محدودیت‌ها از نوع منابع سیستمی هستند. شبکه داخلی یک کنترل خروجی (egress) واقعی است. ایزولاسیون بین یک ایجنت و میزبان (host) شما از این کنترل‌های کانتینری استفاده می‌کند و یک کانتینر با میزبان در هسته (kernel) مشترک است.

واقعیت دومی نیز وجود دارد که باید در نظر گرفت. سرویس runner مسیر /var/run/docker.sock را mount می‌کند، زیرا این روشی است که sandboxها را ایجاد می‌کند. دسترسی به socket یک Docker daemon با دسترسی root، معادل داشتن دسترسی root روی میزبان است؛ چرا که هر کسی که بتواند آن API را فراخوانی کند، می‌تواند کانتینری را با فایل‌سیستم میزبان در آن mount کند. runner مبتنی بر Docker که ارائه شده، از همین socket استفاده می‌کند. نتیجه این است که پردازش runner به اندازه gateway حساس است. سرویس SSH terminator نیز همان socket را mount می‌کند تا بتواند دستورات را درون کانتینرهای sandbox اجرا کند. در کامنت‌های فایل compose نیز ذکر شده که این mount معادل دسترسی root روی میزبان است؛ بنابراین پورت 10257 را روی loopback نگه دارید، مگر اینکه دلیل موجهی برای باز کردن آن داشته باشید.

با مرز مشترک هسته (shared-kernel) محتاطانه برخورد کنید. در عمل، این به معنای رعایت سه عادت است:

  1. OneCLI را روی ماشینی اجرا کنید که هیچ کار دیگری انجام نمی‌دهد. هیچ سرویس تولیدی (production) نامرتبط، دیتابیس مشترک یا داده‌های تیم‌های دیگر روی آن نباشد.
  2. فرض کنید ایجنتی که به اجرای کد دلخواه (arbitrary code execution) در sandbox خود دست یافته، می‌تواند به میزبان نفوذ کند. بنابراین، با نگهداری نسخه‌های پشتیبان در خارج از آن ماشین، شرایط را به گونه‌ای مدیریت کنید که در صورت بروز چنین اتفاقی، داده‌ها قابل بازیابی باشند.
  3. پیش از آنکه به همکار خود بگویید ایجنت کاملاً ایزوله است، apps/runner/src را مطالعه کنید یا از توسعه‌دهندگان اصلی (upstream) سؤال بپرسید.

برای درک اینکه یک مرز مستندشده چگونه تعریف می‌شود و چه پرسش‌هایی ارزش مطرح کردن با توسعه‌دهندگان اصلی را دارند، این موضوع را با آنچه یک مرز sandbox واقعی برای ایجنت به نظر می‌رسد مقایسه کنید. پرسش اصلی این است که آیا مکانیزم مستندشده، تهدیداتی را که نیاز دارید متوقف کند، پوشش می‌دهد یا خیر.

تفکیک مجوز و دلایل بررسی پیش از ساخت

هسته اصلی OneCLI تحت مجوز Apache-2.0 است و میزبانی شخصی (self-hosting) آن در محیط عملیاتی مجاز است. دایرکتوری‌هایی که با نام ee/ مشخص شده‌اند، تحت یک مجوز جداگانه به نام OneCLI Enterprise License قرار می‌گیرند: این بخش برای توسعه، تست و ارزیابی رایگان است، اما برای استفاده در محیط عملیاتی نیاز به اشتراک دارد. یادداشت‌های انتشار نسخه v2.0.1 در تاریخ 18 August 2026 به بازگردانی یک فایل مجوز Apache-2.0 که توسط GitHub قابل شناسایی است اشاره دارند، بنابراین نشان (badge) موجود در صفحه مخزن اخیراً تغییر کرده است. تگی را که واقعاً مستقر (deploy) می‌کنید بررسی کنید و به خلاصه‌ای که در تاریخ دیگری نوشته شده است، اکتفا نکنید.

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

هر چیزی که در آن مسیرها قرار دارد، بخش تجاری محسوب می‌شود. اگر قابلیتی که قصد دارید به آن وابسته باشید در آن مسیرها قرار دارد، پیش از آنکه فرآیندی را پیرامون آن شکل دهید، قیمت آن را استعلام کنید.

ارتقا، مهاجرت و فایلی که نباید از دست بدهید

ارتقا باید ایمیج‌های سرویس و ایمیج جداگانه agent را به‌روزرسانی کند و سپس sandboxهای در حال اجرا را مجدداً راه‌اندازی نماید. یک سرویس مهاجرت یک‌باره (one-shot) پیش از API در هر up اجرا می‌شود و اگر مهاجرت با شکست مواجه شود، stack به‌جای سرویس‌دهی با یک شمای نیمه‌مهاجرت‌شده، از شروع به کار خودداری می‌کند. این همان رفتاری است که شما می‌خواهید، زیرا ارتقای ناموفق در این حالت به‌صورت یک قطعی (outage) دیده می‌شود و نه خرابی خاموش، و docker compose logs migrations دلیل آن را توضیح می‌دهد.

یک مرحله وجود دارد که به‌راحتی نادیده گرفته می‌شود. مستندات self-hosting نسبت به ارتقا با یک docker compose pull && docker compose up -d خام هشدار می‌دهد، زیرا ایمیج sandbox مربوط به agent یک سرویس Compose نیست. این مقدار RUNNER_AGENT_IMAGE روی runner است، بنابراین docker compose pull هرگز آن را نمی‌بیند و agentهای میزبانی‌شده ممکن است بدون هیچ هشداری روی یک ایمیج sandbox قدیمی باقی بمانند. checkout را به‌روز کنید، pin را جابه‌جا کنید و ابزار ارتقای مستندشده را اجرا کنید که ایمیج sandbox را pull کرده و sandboxهای در حال اجرا را restart می‌کند.

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ها کارهای در حال انجام را قطع می‌کند؛ فضای کاری پایدار (durable workspace) هر agent باقی می‌ماند.

اگر به‌جای آن با اسکریپت نصب، عملیات را انجام داده‌اید، به‌جای pull دستی، همان اسکریپت را مجدداً اجرا کنید تا فایل compose با ایمیج‌هایی که به آن‌ها ارجاع می‌دهد همگام باقی بماند. اگر نسخه خاصی مد نظر شماست، ابتدا ONECLI_VERSION را export کنید، زیرا اسکریپت مقداری که فقط در فایل .env آن نگهداری می‌شود را بازنویسی می‌کند.

از دیتابیس، پیکربندی و volumeهای فضای کاری agent نسخه پشتیبان تهیه کنید. PostgreSQL شامل agentها، گفتگوها، حافظه و secretهای رمزنگاری‌شده است. فایل docker/.env حاوی SECRET_ENCRYPTION_KEY است و بدون آن کلید، secretهای رمزنگاری‌شده حتی در صورت بازیابی بقیه دیتابیس، غیرقابل خواندن خواهند بود. فضای کاری /workspace هر agent روی یک volume پایدار جداگانه قرار دارد و نیاز به پشتیبان‌گیری اختصاصی دارد.

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

آن نسخه‌ها و پشتیبان‌های فضای کاری را خارج از سرور نگهداری کنید. این روال همان روالی است که هر stack دارای state در Compose به آن نیاز دارد، بنابراین اگر قبلاً پشتیبان‌گیری و ارتقای یک Docker Compose stack را طبق برنامه انجام می‌دهید، دیتابیس، پیکربندی و volumeهای فضای کاری را به آن اضافه کنید و دیگر نگران آن نباشید.

هنگامی که کار نمی‌کند

  • استک هرگز به وضعیت سالم نمی‌رسد و docker compose up -d --wait با کد خروجی غیر صفر متوقف می‌شود. ابتدا docker compose logs migrations را بخوانید، زیرا API عمداً منتظر آن سرویس می‌ماند.
  • یک ایجنت بیکار می‌ماند و هیچ سندباکسی ظاهر نمی‌شود. بررسی کنید که COMPOSE_PROFILES=runner در docker/.env موجود باشد و docker compose ps یک رانر را لیست کند. سپس بررسی کنید که ایجنت یک کلید مدل معتبر داشته باشد، زیرا سندباکس‌ها بدون آن اجرا نمی‌شوند.
  • اسلات خالی وجود ندارد. مقدار پیش‌فرض RUNNER_MAX_SANDBOXES برابر با 4 است و یک سندباکس که فرآیند پس‌زمینه در حال اجرا دارد، اسلات خود را تا زمانی که سقف نگهداری (held-awake) آن را بیرون نیندازد، اشغال می‌کند. docker ps نشان می‌دهد که واقعاً چه چیزی فعال است.
  • استک شروع نمی‌شود و Docker گزارش می‌دهد که پورت قبلاً در حال استفاده است. با فعال بودن پروفایل runner، درگاه SSH علاوه بر چهار پورت دیگر، به 10257 نیز نیاز دارد.
  • کانتینرها ناپدید می‌شوند یا هاست کند می‌شود. با استفاده از dmesg -T | grep -i oom کمبود حافظه را بررسی کنید؛ سقف حافظه پیش‌فرض به هر سندباکس اجازه می‌دهد تا 2048 مگابایت استفاده کند.
  • تماس‌های HTTPS یک ایجنت به جای خطاهای احراز هویت، با خطاهای تأیید گواهی مواجه می‌شوند. کلاینت HTTP آن به مرجع صدور گواهی (CA) گیت‌وی اعتماد ندارد.
  • کانتینرها یا ولوم‌های قدیمی پس از حذف یک ایجنت باقی می‌مانند. رانر هر 60 ثانیه وضعیت را همگام‌سازی (reconcile) می‌کند و یتیم‌هایی که قدیمی‌تر از RUNNER_ORPHAN_GRACE_SECONDS هستند را از بین می‌برد. مقدار پیش‌فرض این پارامتر 3600 است، بنابراین پیش از آنکه آن را نشت حافظه یا فایل بنامید، یک ساعت صبر کنید.

آیا این ابزار مناسب نیاز شماست؟

تست تناسب بسیار کوتاه است. OneCLI زمانی ارزشمند است که چندین نفر به یک agent نیاز داشته باشند و بخواهید اعتبارنامه‌ها را در یک مکان متمرکز کنید: یک مخزن برای چرخش کلیدها، یک لاگ حسابرسی برای بررسی، و یک داشبورد که در آن لغو دسترسی یک شخص، واقعاً دسترسی او را قطع کند. این یک چالش عملیاتی واقعی است و کپی کردن یک API key در شش لپ‌تاپ، راهکار بدتری برای آن محسوب می‌شود.

برای یک نفر، این مجموعه اجزا هزینه و پیچیدگی زیادی دارد و مزیت محسوسی ایجاد نمی‌کند. برای ارائه یک agent منفرد باید PostgreSQL، یک control plane، یک gateway و یک runner اجرا کنید؛ درحالی‌که مشکل credential که gateway حل می‌کند، زمانی که تنها دارنده key خود شما هستید، تقریباً وجود ندارد. در عوض، یک harness منفرد را روی یک ماشین کوچک‌تر اجرا کنید: یک harness منفرد برای agent روی VPS همین کار را با کسری از حافظه انجام می‌دهد. اگر هنوز هیچ مسیری را انتخاب نکرده‌اید، مرور کلی مقایسه agentهای self-hosted گزینه ارزان‌تری برای شروع است. اگر بخش ناآشنا خود agentها هستند، نه سرورهایی که روی آن‌ها اجرا می‌شوند، ابتدا مسیری مرحله‌ای برای یادگیری نحوه واقعی کار agentها را دنبال کنید؛ زیرا دانستن این‌که یک tool call و یک memory store واقعاً چه کاری انجام می‌دهند، مشخص می‌کند agent هر فرد باید چه grantهایی داشته باشد.

FAQ

حداقل نیازمندی‌های سرور برای میزبانی شخصی OneCLI چیست؟

نیاز به Docker با افزونه Compose نسخه 2.24.0 یا جدیدتر، Node.js و pnpm برای ویزارد راه‌اندازی (که در اینجا استفاده شده) و حافظه کافی دارید. PostgreSQL همراه با فایل compose ارائه می‌شود، بنابراین نیازی به نصب جداگانه آن نیست. حافظه، تعیین‌کننده پلن شماست: runner به‌صورت پیش‌فرض هر sandbox ایجنت را به 2048 مگابایت محدود می‌کند و مستندات آن پیشنهاد می‌دهد حدود 10 گیگابایت فضای آزاد علاوه بر پشته پایه برای پشتیبانی از سقف پیش‌فرض چهار sandbox در نظر بگیرید. با فرض بودجه 2 گیگابایتی برای پشته پایه، یک سرور 4 گیگابایتی برای یک sandbox با سقف کامل و یک سرور 16 گیگابایتی برای سقف هم‌زمانی پیش‌فرض کافی است. این‌ها ارقام برنامه‌ریزی هستند، نه حداقل نیازمندی‌های اندازه‌گیری‌شده یا تخصیص‌های حافظه ثابت.

آیا OneCLI به PostgreSQL نیاز دارد یا می‌تواند از SQLite استفاده کند؟

این برنامه به PostgreSQL نیاز دارد. DATABASE_URL به‌عنوان یک رشته اتصال PostgreSQL مستند شده است، فایل compose ارائه‌شده، postgres:18-alpine را با یک volume از نوع pgdata اجرا می‌کند و یک سرویس مهاجرت (migrations) جداگانه، طرح‌واره (schema) را پیش از شروع API اعمال می‌کند. هیچ گزینه‌ای برای SQLite مستند نشده است. برای استفاده از یک سرور PostgreSQL خارجی، هم سرویس API و هم سرویس مهاجرت را برای استفاده از آن پیکربندی کنید؛ فایل compose ارائه‌شده، رشته‌های اتصال آن‌ها را روی سرویس PostgreSQL داخلی خود تنظیم می‌کند.

آیا sandbox ایجنت OneCLI یک مرز امنیتی واقعی است؟

مکانیزم مستندشده Compose، یک کانتینر Docker با محدودیت‌های حافظه، CPU و پردازش است که به شبکه‌ای با برچسب internal: true متصل شده تا ترافیک خارجی از طریق gateway عبور کند. کنترل خروجی (egress) واقعی است و می‌توانید آن را با docker network inspect بررسی کنید. ایجنت با کاربر node و با no-new-privileges اجرا می‌شود، در حالی که تمام قابلیت‌های لینوکس (Linux capabilities) حذف شده و از پروفایل پیش‌فرض seccomp در Docker استفاده می‌کند، اما همچنان از هسته (kernel) میزبان به‌صورت مشترک استفاده می‌نماید. runner و SSH terminator هر دو مسیر /var/run/docker.sock را mount می‌کنند که در یک میزبان با Docker daemon ریشه‌دار (rootful)، معادل دسترسی root است. OneCLI را روی یک سرور اختصاصی اجرا کنید و نسخه‌های پشتیبان را خارج از آن سرور نگهداری کنید.

آیا نیاز است پورت ورودی برای OneCLI باز کنم؟

خیر. runner فقط خروجی است و هیچ پورتی را که دنیای خارج بتواند به آن دسترسی داشته باشد باز نمی‌کند، بنابراین پشت NAT و بدون نیاز به تونل کار می‌کند. فایل compose به‌صورت پیش‌فرض داشبورد، gateway، API، PostgreSQL و در پروفایل runner، درگاه SSH روی پورت 10257 را به 127.0.0.1 متصل می‌کند. برای دسترسی به داشبورد از تونل SSH استفاده کنید، یا اگر چندین نفر به آن نیاز دارند، از پیکربندی reverse proxy بالادستی با TLS و مسیرهای لازم برای داشبورد، API و gateway استفاده کنید؛ به یاد داشته باشید که ثبت‌نام برای هر کسی که به آن دسترسی داشته باشد باز می‌ماند. gateway روی پورت 10255 برای ایجنت‌ها است و در یک سرور واحد، ایجنت‌ها از طریق شبکه داخلی Docker به آن دسترسی پیدا می‌کنند.

آیا استفاده از OneCLI در شرکت رایگان است؟

هسته اصلی تحت مجوز Apache-2.0 است و استفاده در محیط تولید (production) به‌صورت میزبانی شخصی بدون نیاز به مجوز تجاری مجاز است. دایرکتوری‌های با نام ee/ تحت مجوز OneCLI Enterprise هستند که برای توسعه، تست و ارزیابی رایگان است اما در محیط تولید نیاز به اشتراک دارد. این تفکیک بین نسخه‌ها تغییر می‌کند و یادداشت‌های نسخه v2.0.1 مورخ 18 اوت 2026 به بازگرداندن فایل مجوز Apache-2.0 قابل شناسایی توسط GitHub اشاره دارند؛ بنابراین پیش از ساخت یک گردش‌کار روی هر ویژگی خاص، LICENSE و دایرکتوری‌های ee/ را در تگ دقیقی که مستقر می‌کنید، بررسی کنید.

آیا این مقاله مفید بود؟