اجراگر

اجراگر برنامه‌ای است که روی سرور شما می‌نشیند، تسک‌های تأییدشده را برمی‌دارد و ترمینال را اجرا می‌کند. با آن، کار بدون حضور شما جلو می‌رود.

چرا روی سرور خودتان

چون رمزها آن‌جا می‌مانند. کلید SSH سرور مشتری، توکن گیت، رمز دیتابیس — هیچ‌کدام به کاربانر نمی‌رسند. Runner آن‌ها را از فایل محلی می‌خواند و فقط به محیط ترمینال تزریق می‌کند.

لاگ اجرا هم محلی است. اگر کاری شکست بخورد، فقط کد خروج و مسیر لاگ در کامنت ثبت می‌شود، نه خودِ خروجی.

نصب

cd runner && ./install.sh
karbaner-runner init          # ~/.karbaner/runner.toml را می‌سازد

بعد در runner.toml سه چیز را پر کنید:

• token — از پنل ← توکن‌ها ← نوع اجراگر
• command — دستور اجرای انجین. کاربانر انجین پیش‌فرض ندارد؛ هرچه دارید استفاده کنید.
• workspaces_dir — پوشه‌ای که هر پروژه زیرش workspace خودش را می‌گیرد

karbaner-runner register
karbaner-runner run

CLI را هم روی همان ماشین نصب کنید (cd cli && ./install.sh، یا باینری در /usr/local/bin/karbaner): ترمینال طبق پروتکل با karbaner tasks … کار می‌کند و اجراگر آدرس و توکن را خودش به محیط انجین می‌دهد، پس karbaner login لازم نیست. بدون CLI، ترمینال ناچار است خودش با API حرف بزند — کار می‌کند ولی پرخطاتر است.

وصل‌کردن پروژه

در تنظیمات پروژه: اجراگر را انتخاب کنید و حالت اجرا را خودکار کنید. از آن به بعد هر تسکی که تأیید کنید، ظرف چند ثانیه برداشته می‌شود.

اجرای دائمی

پروسه‌ی ترمینالی با بستن پنجره از بین می‌رود. برای همیشه‌روشن بودن:

• لینوکس: deploy/karbaner-runner.service (systemd)
• macOS: ./deploy/install-macos.sh (launchd)

هر دو بعد از کرش خودشان بالا می‌آیند.

secretها

برای هر پروژه یک فایل بسازید:

~/.karbaner/secrets/<project-slug>.env

هر خطش یک KEY=value است و در محیط ترمینال قرار می‌گیرد. مقدارِ این فایل هرگز به کاربانر فرستاده نمی‌شود.

از پنل هم می‌شود مدیریتش کرد — بدون اینکه مقداری به کاربانر برسد. در تنظیمات پروژه، بخش secretهای پروژه، نامِ متغیرهای موجود را می‌بینید (اجراگر فقط نام‌ها را گزارش می‌کند) و می‌توانید متغیری اضافه، جایگزین یا حذف کنید. مقداری که می‌نویسید در همان مرورگر با کلید عمومیِ اجراگر رمز می‌شود؛ کاربانر فقط پاکتِ رمزشده را تا لحظه‌ی اعمال نگه می‌دارد، اجراگر با کلید خصوصی‌اش (که فقط روی همان ماشین است) بازش می‌کند و در همین فایل می‌نویسد. به همین دلیل خواندنِ مقدار از پنل ممکن نیست — نه برای شما، نه برای ما.

• اجراگر کلیدش را با اولین اجرا می‌سازد (~/.karbaner/state/secrets-key) و اثرانگشتش را در لاگ و در karbaner-runner status نشان می‌دهد؛ همان اثرانگشت در پنل کنار نام اجراگر می‌آید.
• تغییرها با heartbeat اعمال می‌شوند (معمولاً زیر یک دقیقه). اجراگرِ آفلاین بعد از آنلاین‌شدن اعمالشان می‌کند.
• اگر اجراگر را از نو نصب کنید، کلید تازه می‌سازد و تغییرهای در صف «ناموفق» می‌شوند؛ دوباره بفرستید. همین‌طور اگر اجراگرِ پروژه را عوض کنید یا بردارید: تغییرهای در صف ناموفق می‌شوند و فهرست نام‌ها تا اولین گزارشِ اجراگر تازه خالی است (فایل روی ماشین قبلی دست نمی‌خورد).
• این کار فقط دست صاحب کسب‌وکار است؛ نیرو نه نام‌ها را می‌بیند نه می‌تواند تغییری بدهد.

سهمیه‌ی حساب انجین

اگر انجین شما اشتراکِ محدود دارد (مثل پنجره‌ی ۵ ساعته و هفتگیِ Claude)، پنل نشان می‌دهد چقدرش مصرف شده — همان چیزی که /usage در خودِ انجین می‌گوید. عدد از خودِ انجین می‌آید: در سشن زنده‌ی گفتگوی مستقیم، اجراگر رویداد rate_limit_event را از خروجی stream-json برمی‌دارد و با heartbeat بعدی درصدِ هر پنجره و زمانِ بازنشانی را به هاب می‌دهد. جایش:

• صفحه‌ی اجراگرها، ستونِ «سهمیه‌ی حساب» — هر پنجره با درصد؛ زرد از ۷۰، قرمز از ۹۰. زمانِ بازنشانی و زمانِ آخرین گزارش در tooltip.
• سرصفحه‌ی صفحه‌ی ترمینال هر پروژه، کنارِ پُری سشن.

تا وقتی هیچ نوبتِ گفتگویی روی اجراگر نرفته، چیزی نشان داده نمی‌شود. هیچ تماسِ جداگانه‌ای با سرویس‌دهنده زده نمی‌شود و جز درصد و زمان چیزی از خروجی انجین به هاب نمی‌رسد.

رفتارهای محافظتی

• تسکی که همین حالا اجرا شد یا شکست خورد، بلافاصله دوباره برداشته نمی‌شود.
• بعد از سه تلاش بی‌ثمر — چه شکست، چه اجرایی که هیچ چیزی را جلو نبرد — تسک با یک کامنت توضیحی به شما برگردانده می‌شود.
• وضعیت‌های «منتظر» و «بازبینی» اصلاً واگذار نمی‌شوند؛ آن‌ها یعنی نوبت یک انسان است.
• با خاموش‌شدن اجراگر، کار در جریان قطع نمی‌شود؛ تا پایان یا تا مهلت drain_seconds صبر می‌کند.
• حذف اجراگر از پنل توکنش را هم باطل می‌کند. سرویسی که هنوز روی آن ماشین می‌چرخد دیگر نمی‌تواند خودش را دوباره ثبت کند (در لاگش «توکن runner نامعتبر یا باطل شده» می‌بینید) — خاموش‌کردنِ آن سرویس با خودتان است. برای وصل‌کردنِ دوباره‌ی همان ماشین، توکن تازه بسازید.