آموزش میزبانی KiroCrew روی VPS و اجرای دائمی آن

چرا KiroCrew را به جای لپ‌تاپ روی یک VPS میزبانی کنیم

میزبانی شخصی KiroCrew تنها زمانی نتیجه‌بخش است که روی دستگاهی اجرا شود که هرگز خاموش نمی‌شود؛ بنابراین VPS مکان مناسبی برای آن است و لپ‌تاپ گزینه مناسبی نیست. KiroCrew تاریخچه نشست‌ها، حافظه معنایی، وظایف زمان‌بندی‌شده و صف تأیید را روی دیسک ذخیره می‌کند و هنگام راه‌اندازی مجدد پردازش، تمام این موارد را بارگذاری می‌کند. اگر پردازش در ساعت 03:00 که زمان اجرای یک وظیفه زمان‌بندی‌شده است در حال اجرا نباشد، هیچ‌کدام از این قابلیت‌ها کارایی نخواهند داشت و لپ‌تاپ بسته نیز این پردازش را اجرا نمی‌کند.

KiroCrew یک فضای کاری عامل (agent workspace) متن‌باز از تیم Kiro است که تحت مجوز Apache 2.0 منتشر شده و اولین نسخه‌های عمومی آن در اوایل اوت 2026 عرضه شده‌اند. یک پردازش به نام gateway، وضعیت را مدیریت کرده و یک داشبورد وب را روی پورت 5476 ارائه می‌دهد. شما از طریق داشبورد، از طریق kirocrew CLI یا از طریق یک کانال گفتگو مانند Slack به این gateway دسترسی پیدا می‌کنید. gateway تنها بخشی است که شما شخصاً میزبانی می‌کنید، بنابراین این راهنما بر نحوه فعال نگه داشتن آن، دور نگه داشتن آن از اینترنت عمومی و توانایی بازگرداندن آن پس از یک ارتقای ناموفق تمرکز دارد.

دو نکته که باید پیش از شروع بدانید. KiroCrew از kiro-cli استفاده می‌کند که نیاز به یک بار ورود با حساب کاربری Kiro دارد و هزینه استنتاج عامل (agent inference) از طریق طرح Kiro محاسبه می‌شود، بنابراین تا اوت 2026 این یک پیکربندی کاملاً آفلاین نیست. این پروژه همچنین تنها چند هفته عمر دارد. فرض را بر این بگیرید که در مقطعی نیاز به بازگشت به نسخه قبلی (rollback) خواهید داشت و آن را به گونه‌ای نصب کنید که این امکان را به شما بدهد. اگر قبلاً عاملی را روی سرور اجرا نکرده‌اید، اجرای یک عامل کدنویسی روی VPS اصول اولیه‌ای را پوشش می‌دهد که این راهنما بر پایه آن‌ها بنا شده است. اگر بخش عامل (agent) برای شما جدیدتر از بخش سرور است، یادگیری ماهیت حلقه عامل، ابزارها و حافظه آن ابتدا باعث می‌شود انتخاب‌های زیر برای شما به عنوان تصمیمات آگاهانه تلقی شوند، نه دستورات جادویی.

نیازهای KiroCrew و محل ذخیره وضعیت آن

نصب بومی (native) به Python 3.10 یا جدیدتر (پروژه نسخه 3.12 را توصیه می‌کند)، Node.js 18 یا جدیدتر برای ساخت داشبورد از سورس، و kiro-cli نیاز دارد که در اولین اجرا به‌طور خودکار نصب و پیکربندی می‌شود. نصب کانتینری به هیچ‌کدام از این موارد روی میزبان نیاز ندارد و تنها به Docker وابسته است. این اصلی‌ترین دلیل برای ترجیح دادن روش کانتینری است.

وضعیت (state) در ~/.kiro/crew ذخیره می‌شود و متغیر محیطی KIROCREW_HOME می‌تواند این مسیر را تغییر دهد. محتویات این دایرکتوری عبارتند از:

• config.json: تنظیمات gateway و اعتبارنامه‌های کانال‌های گفتگو.
• .env: موارد محرمانه (secrets).
• workspace/memory/: ترجیحات، یادداشت‌های پروژه و تاریخچه گفتگوها.
• memory.db و memory_index.db: ایندکس‌های معنایی و تمام‌متن.
• models/: مدل embedding که در اولین اجرا دانلود می‌شود.
• gateway.log و security_events.jsonl: لاگ زمان اجرا و لاگ رویدادهای امنیتی.

این دایرکتوری در واقع همان محل نصب است. با کپی کردن آن در یک VPS جدید، عامل (agent) خود را منتقل کرده‌اید؛ به همین دلیل بخش پشتیبان‌گیری در ادامه، اهمیت بیشتری نسبت به بخش نصب دارد.

برای دیسک برنامه‌ریزی کنید، نه RAM. این gateway یک پردازش Python است؛ آنچه واقعاً بار سیستم را افزایش می‌دهد، کارهایی است که عامل اجرا می‌کند، مانند یک build یا یک مجموعه تست. دایرکتوری وضعیت با افزایش تاریخچه گفتگوها رشد می‌کند و مدل embedding نیز در اولین اجرا اضافه می‌شود؛ بنابراین به‌جای اعتماد به ارقام منتشر شده در ماه اول پروژه، پس از چند هفته استفاده، حجم آن را روی سیستم خود با du -sh ~/.kiro/crew اندازه‌گیری کنید. این موضوع را با محیط اجرایی که به هر worker یک کانتینر و مرورگر اختصاصی می‌دهد مقایسه کنید، جایی که میزبانی شخصی همکاران هوش مصنوعی OpenBot باعث می‌شود تعیین اندازه پیش از آنکه به دیسک مربوط باشد، به RAM وابسته باشد.

از کدام‌یک از سه مسیر نصب باید استفاده کنید

این پروژه سه روش انتشار دارد. نصب‌کننده تک‌خطی، یک wheel دریافت کرده و kirocrew را در PATH شما قرار می‌دهد:

curl -fsSL https://download.crew.kiro.dev/cli.sh | sh

این دستور از یک پرچم کانال و یک پرچم نسخه استفاده می‌کند:

curl -fsSL https://download.crew.kiro.dev/cli.sh | sh -s -- --channel insider
curl -fsSL https://download.crew.kiro.dev/cli.sh | sh -s -- --version 0.1.3

ایمیج کانتینر در ghcr.io/kirodotdev/kirocrew، برای linux/amd64 و linux/arm64 تحت هر تگ منتشر می‌شود. بیلد از روی سورس شامل git clone به علاوه make build است و برای کسانی است که کد را تغییر می‌دهند، نه برای کسانی که آن را اجرا می‌کنند.

از کانتینر استفاده کنید. نصب بومی (native)، بسته‌های Python، Node و kiro-cli را روی همان میزبانی قرار می‌دهد که سایر سرویس‌های شما را اجرا می‌کند؛ بنابراین اگر یک ارتقا با مشکل مواجه شود، باید آن را به‌صورت دستی اصلاح کنید. کانتینر، محیط اجرا (runtime) را در یک ایمیج و وضعیت (state) را در یک volume نگه می‌دارد که باعث می‌شود بازگشت به نسخه قبلی (rollback) تنها با تغییر تگ و راه‌اندازی مجدد انجام شود.

تصویر را به یک تگ انتشار (release tag) متصل کنید، نه به stable

نمونهٔ خود پروژه از تگ stable استفاده می‌کند:

docker run -d --name kirocrew \
  -p 127.0.0.1:5476:5476 \
  -v kirocrew-home:/home/kirocrew \
  ghcr.io/kirodotdev/kirocrew:stable

stable یک تگ متغیر (moving tag) است. این تگ به هر نسخه‌ای که در حال حاضر جدیدترین نسخهٔ پایدار باشد اشاره می‌کند، بنابراین در pull بعدی ممکن است نسخه‌ای که اجرا می‌کنید بدون انتخاب شما تغییر کند و تگ هیچ رکوردی از اینکه آن نسخه چه بوده است، ثبت نمی‌کند. تگ‌های نسخه تغییرناپذیر هستند، بنابراین یکی از آن‌ها را انتخاب کنید. جدیدترین نسخه تا تاریخ 6 August 2026 برابر با 0.1.3 است که در 5 August 2026 منتشر شده است. همچنین یک تگ nightly وجود دارد که در پروژه‌ای به این تازگی، به این معنی است که کد همین امروز صبح تغییر کرده است.

فایل /opt/kirocrew/compose.yaml را بنویسید:

services:
  kirocrew:
    image: ghcr.io/kirodotdev/kirocrew:0.1.3
    container_name: kirocrew
    restart: unless-stopped
    ports:
      - "127.0.0.1:5476:5476"
    volumes:
      - kirocrew-home:/home/kirocrew

volumes:
  kirocrew-home:

آن را اجرا کنید و سپس endpoint سلامت (health endpoint) که تصویر از آن برای HEALTHCHECK خود استفاده می‌کند را بررسی کنید:

cd /opt/kirocrew
docker compose up -d
docker compose ps
curl -s http://127.0.0.1:5476/api/health

docker compose ps باید ظرف حدود یک دقیقه وضعیت container را به عنوان healthy گزارش کند و /api/health بدون نیاز به token پاسخ دهد (همان‌طور که /api/live و /api/ready پاسخ می‌دهند، که همین ویژگی آن‌ها را برای استفاده به عنوان probe مناسب می‌کند). اگر وضعیت روی starting باقی ماند، پیش از تغییر هر چیزی، docker logs kirocrew را مطالعه کنید. اجرای اول، مدل embedding را دانلود می‌کند، بنابراین در صورت کند بودن اتصال، اولین راه‌اندازی طولانی خواهد بود.

حفظ پایداری سرویس با systemd

restart: unless-stopped باعث می‌شود کانتینر پس از کرش کردن یا ریبوت شدن سیستم، به شرطی که Docker در زمان بوت بالا بیاید، دوباره اجرا شود. یک unit file این وابستگی را صریح می‌کند و به شما یک دستور واحد می‌دهد تا پیش از گرفتن بک‌آپ، کل stack را متوقف کنید. شروع یک Docker Compose stack در زمان بوت الگوی کلی این کار را پوشش می‌دهد. این شکل پیاده‌سازی KiroCrew در /etc/systemd/system/kirocrew.service آمده است:

[Unit]
Description=KiroCrew gateway
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/kirocrew
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now kirocrew
systemctl status kirocrew

systemctl status kirocrew باید active (exited) را نشان دهد که نتیجه سالم برای این unit است. Type=oneshot با RemainAfterExit=yes در اینجا صحیح است، زیرا docker compose up -d بلافاصله پس از شروع کانتینر بازمی‌گردد: systemd در حال ردیابی وضعیت بالا بودن stack است، نه یک پردازش foreground. اگر به جای آن Type=simple را بنویسید، systemd می‌بیند که دستور بلافاصله خاتمه می‌یابد، سرویس را dead علامت‌گذاری می‌کند و بسته به تنظیمات Restart= شما، یا تسلیم می‌شود یا در یک حلقه restart گیر می‌کند. برای نصب native، پروژه فایل معادل خود یعنی kirocrew service install را ارائه می‌دهد که /etc/systemd/system/kirocrew.service را می‌نویسد و gateway را با کاربر شما اجرا می‌کند. هر دو unit را همزمان اجرا نکنید. نسخه جامع‌تر این موضوع در سرویس‌ها و تایمرهای systemd روی یک VPS موجود است. یک unit که پس از شکست دوباره بالا نمی‌آید، ساکت می‌ماند مگر اینکه آن را وادار به اطلاع‌رسانی کنید؛ بنابراین یک handler برای OnFailure= اضافه کنید که یک هشدار به سرور ntfy شخصی شما ارسال کند تا به جای متوجه شدن از طریق یک job زمان‌بندی‌شده که هرگز اجرا نشده، از طریق گوشی خود بفهمید که gateway از دسترس خارج شده است.

اجرای نخست: ورود به سیستم و دریافت توکن داشبورد

کانتینر، gateway را اجرا می‌کند، اما runtime ایجنت هنوز وارد سیستم نشده است. داخل کانتینر وارد شوید:

docker exec -it kirocrew kiro-cli login

این دستور یک کد دستگاه و یک URL چاپ می‌کند که باید آن را در مرورگر خود باز کنید. سپس یک توکن داشبورد ایجاد کنید:

docker exec kirocrew kirocrew token --ttl 2h

URL داشبورد http://localhost:5476/?token=<the token> است. توکن‌ها منقضی می‌شوند: نشست‌ها به‌صورت پیش‌فرض یک ساعت اعتبار دارند و حداکثر زمان مستندشده برای آن‌ها 20 ساعت است. اگر داشبورد خالی بارگذاری می‌شود یا بلافاصله شما را به صفحه ورود بازمی‌گرداند، معمولاً به دلیل انقضای توکن است؛ بنابراین یک توکن جدید ایجاد کنید. هرگز توکن را در تیکت یا پیام چت کپی نکنید، زیرا هر کسی که آن را در اختیار داشته باشد، به ایجنت شما دسترسی خواهد داشت.

دسترسی به داشبورد از طریق SSH و عدم انتشار پورت 5476

به آدرس bind در مثال پروژه یعنی -p 127.0.0.1:5476:5476 دوباره نگاه کنید. داخل کانتینر، gateway روی 0.0.0.0 گوش می‌دهد، زیرا باید از طریق نگاشت پورت (port mapping) در دسترس باشد، اما خودِ نگاشت فقط روی loopback میزبان منتشر می‌شود. اگر پیشوند 127.0.0.1: را حذف کنید، gateway برای هر کسی که آن پورت را اسکن کند، در اینترنت عمومی قرار می‌گیرد. قوانین فایروال نیز شما را نجات نخواهند داد: Docker پورت‌ها را با نوشتن قوانین DNAT منتشر می‌کند که پیش از فیلترینگ ufw ارزیابی می‌شوند، بنابراین ufw deny 5476 روی پورت منتشرشده هیچ اثری ندارد. مقاله دور زدن ufw توسط پورت‌های Docker این مکانیزم را بررسی می‌کند.

در عوض، پورت را از لپ‌تاپ خود از طریق SSH فوروارد کنید:

ssh -N -L 5476:127.0.0.1:5476 you@your-server.example.com

آن را در حال اجرا بگذارید و http://localhost:5476/?token=<the token> را به‌صورت محلی باز کنید. برای اینکه این فوروارد در هر اتصال به‌صورت خودکار انجام شود، آن را در ~/.ssh/config قرار دهید:

Host your-server.example.com
    LocalForward 5476 127.0.0.1:5476

اگر پورت 5476 قبلاً روی لپ‌تاپ شما در حال استفاده است، فقط عدد سمت چپ را تغییر دهید: ssh -N -L 45476:127.0.0.1:5476 you@your-server.example.com، سپس به http://localhost:45476/?token=... بروید. به‌محض اینکه عامل دوم (agent) از سرور استفاده کند، شما فورواردها را به همین شکل روی هم می‌چینید، زیرا میزبانی شخصی open-kritt برای اسکن امنیتی یک داشبورد دیگر با محدودیت loopback را روی همان سرور و پورت 5173 قرار می‌دهد.

یک رفتار مستند که باید در تونل انتظار آن را داشته باشید این است: gateway درخواست‌های فوروارد شده را به عنوان درخواست از راه دور (remote) می‌خواند، بنابراین endpointهای مربوط به نوشتن تنظیمات (config-write) و نمایش اسرار (secret-reveal) در داشبورد آن‌ها را رد می‌کنند. تغییری در تنظیمات که از طریق SSH ذخیره نمی‌شود، به دلیل این رفتار است و یک باگ نیست. در عوض، فایل پیکربندی را روی میزبان ویرایش کنید:

docker cp kirocrew:/home/kirocrew/.kiro/crew/config.json .
# edit config.json here
docker cp config.json kirocrew:/home/kirocrew/.kiro/crew/config.json
docker exec -u 0 kirocrew chown kirocrew:kirocrew /home/kirocrew/.kiro/crew/config.json
docker restart kirocrew

برای دسترسی با تلفن، پروژه به tailscale serve متعلق به Tailscale اشاره می‌کند که داشبورد را داخل tailnet خودتان نگه می‌دارد و آن را روی یک نام میزبان عمومی قرار نمی‌دهد. این روش را به reverse proxy عمومی ترجیح دهید. token در URL منتقل می‌شود و URL در هر access log موجود در مسیر آن ثبت می‌شود. این قاعده به چیزی مربوط است که پشت پورت قرار دارد، نه خود پورت: چیزی مانند Halcyon که یک کتابخانه Jellyfin را به فروشگاه ویدئویی قابل‌مرور با حال‌وهوای دهه 90 بازسازی می‌کند برای بازکردن توسط افراد دیگر ارائه می‌شود و گزینه مناسبی برای reverse proxy است؛ اما gatewayای که بتواند روی سرور شما command اجرا کند، چنین نیست.

کمترین شعاع انفجار ممکن را به عامل اختصاص دهید

کانتینر در اولین اجرا، پشتیبانی از sandbox را بررسی می‌کند و نتیجهٔ این بررسی تعیین می‌کند که آیا عامل‌ها اجازهٔ اجرای هیچ دستوری را دارند یا خیر. اگر جداسازی namespace در دسترس باشد، زیرفرآیندهای عامل به‌صورت ایزوله اجرا می‌شوند. اگر این قابلیت در دسترس نباشد و KIROCREW_ALLOW_UNSANDBOXED=1 تنظیم نشده باشد، از اجرا جلوگیری می‌شود تا از اجرای ناامن (unconfined) جلوگیری شود؛ بنابراین اگر دروازه‌ای (gateway) دارید که سالم به‌نظر می‌رسد اما تمام وظایف در آن متوقف شده‌اند، معمولاً دلیل آن همین است. تصمیم نهایی در docker logs kirocrew از همان اجرای اول ذخیره می‌شود. این پروژه همچنین یک پروفایل seccomp (حالت محاسبات امن) منتشر می‌کند که می‌توانید آن را اعمال کنید:

curl -fsSL https://raw.githubusercontent.com/kirodotdev/KiroCrew/main/docker/seccomp/kirocrew-seccomp.json \
  -o /opt/kirocrew/kirocrew-seccomp.json

    security_opt:
      - seccomp:./kirocrew-seccomp.json

اگر KIROCREW_ALLOW_UNSANDBOXED=1 را تنظیم می‌کنید، دقیقاً بدانید چه چیزی تغییر کرده است: کانتینر اکنون تنها مرز بین عامل و سرور شماست. هشدار پروژه ارزش تکرار کامل دارد. مسیرهای میزبان (host paths) را که مستقیماً به عامل نمی‌سپارید، mount نکنید. در عمل، این موضوع شامل سوکت Docker، هرگونه bind mount از / و هر دایرکتوری که داده‌های سرویس دیگری را در خود نگه می‌دارد، می‌شود.

باقی موارد، چارچوبی است که برای هر عاملی که اجازهٔ اجرای دستور دارد، اعمال می‌شود. دسترسی‌های (credentials) آن را به یک مخزن یا یک bucket خاص که نیاز دارد محدود کنید؛ هرگز از یک توکن شخصی با دسترسی‌های کل حساب استفاده نکنید. آن را به‌عنوان یک کاربر اختصاصی اجرا کنید که دایرکتوری home او حاوی هیچ چیز دیگری نیست؛ این همان هدفی است که کاربران با حداقل دسترسی روی یک VPS برای آن در نظر گرفته شده است. هنگامی که عامل کد می‌نویسد و سپس آن کد را اجرا می‌کند، ماشینی را در اختیارش بگذارید که اجازهٔ خراب کردنش را دارد: یک VM یک‌بارمصرف برای عامل‌های برنامه‌نویس مرز قوی‌تری نسبت به هر flag در این فایل compose است، زیرا به‌جای پاکسازی، آن را حذف می‌کنید. همین استدلال، اجرای امن OpenClaw روی یک VPS و میزبانی شخصی عامل Hermes روی یک VPS را شکل می‌دهد. ابزارها نیز بخشی از شعاع انفجار محسوب می‌شوند: دادن قابلیت جستجوی وب به عامل، هر صفحه‌ای که دریافت می‌کند را به ورودی غیرقابل‌اعتماد تبدیل می‌کند؛ بنابراین اتصال آن به نمونهٔ SearXNG خودتان، بیش از آنکه یک تصمیم فنی باشد، یک تصمیم برای مقابله با prompt injection است. کارهای زمان‌بندی‌شده نیز در حالی که خواب هستید هزینه ایجاد می‌کنند، زیرا استنتاج (inference) از طرح Kiro شما کسر می‌شود؛ بنابراین پیش از افزودن یک وظیفهٔ شبانه، محدودیت‌های شرح داده شده در کنترل هزینه‌های عامل هوش مصنوعی روی یک VPS را تنظیم کنید.

پیش از هر ارتقا، از volume وضعیت نسخه پشتیبان تهیه کنید

ابتدا نام واقعی volume را پیدا کنید. Compose پیشوندهایی را با نام پروژه به volumeهای نام‌گذاری‌شده اضافه می‌کند که به‌صورت پیش‌فرض همان نام دایرکتوری است؛ بنابراین volume تعریف‌شده با kirocrew-home در /opt/kirocrew/compose.yaml، با نام kirocrew_kirocrew-home ایجاد می‌شود:

docker volume ls

پیش از کپی کردن هر فایلی، gateway را متوقف کنید. فایل‌های memory.db و memory_index.db پایگاه‌داده‌های SQLite هستند و کپی کردن پایگاه‌داده در حین نوشتن، ممکن است منجر به ثبت یک تراکنش ناقص شود که هنگام بازیابی، فایل را خراب می‌کند. دستورالعمل‌های مهاجرت خود پروژه نیز بر همین موضوع تأکید دارند: انتقال داده‌ها را فقط زمانی انجام دهید که gatewayها متوقف شده‌اند. این قانونِ «توقف پیش از اقدام» مختص KiroCrew نیست؛ اگر یک سرور عکس نیز روی همان سرور باشد، مقایسه PhotoPrism و Immich دستورات دقیق پشتیبان‌گیری مورد نیاز برای هر کدام را ارائه می‌دهد.

sudo systemctl stop kirocrew
docker run --rm -v kirocrew_kirocrew-home:/data:ro -v "$PWD":/backup \
  alpine tar czf /backup/kirocrew-2026-08-06.tgz -C /data .
sudo systemctl start kirocrew

آرشیو را از روی سرور کپی کنید. بازیابی با همان دستور و در حالی که container متوقف است انجام می‌شود، با این تفاوت که tar xzf جایگزین tar czf می‌شود:

sudo systemctl stop kirocrew
docker run --rm -v kirocrew_kirocrew-home:/data -v "$PWD":/backup \
  alpine tar xzf /backup/kirocrew-2026-08-06.tgz -C /data
sudo systemctl start kirocrew

انتقال به یک میزبان جدید با بازیابی در محل تفاوت دارد و پروژه در این مورد دستورالعمل‌های خاصی دارد. تاریخچه چت و یادداشت‌های پروژه در مسیر workspace/memory/ منتقل می‌شوند؛ همین‌طور دو فایل پایگاه‌داده و config.json. فایل‌های PID، لاگ رویدادهای امنیتی و .env به میزبان قدیمی وابسته‌اند، بنابراین آن‌ها را رها کنید و secrets را دوباره در میزبان جدید وارد نمایید.

چگونه یک ارتقای ناموفق را بازگردانی (Roll back) کنیم

فرآیند ارتقا کوتاه است و تنها به این دلیل ایمن است که شما یک نسخه خاص را ثابت (pin) کرده‌اید. ابتدا نسخه پشتیبان تهیه کنید و سپس تگ را تغییر دهید:

sudo systemctl stop kirocrew
# take the backup here, as above
sudo nano /opt/kirocrew/compose.yaml   # set the new image tag
sudo systemctl start kirocrew
docker compose -f /opt/kirocrew/compose.yaml ps
curl -s http://127.0.0.1:5476/api/health

docker compose up -d اگر image مورد نظر روی سیستم موجود نباشد، آن را دانلود می‌کند؛ بنابراین ویرایش تگ، تمام کاری است که برای ارتقا انجام می‌شود. بازگردانی به نسخه قبل نیز دقیقاً با همان توالی و با استفاده از شماره نسخه قدیمی انجام می‌شود و دقیقاً همان image قبلی را به شما بازمی‌گرداند، زیرا تگ‌های نسخه تغییرناپذیر هستند.

فایل باینری به‌طور تمیز بازگردانی می‌شود، اما وضعیت (state) ممکن است این‌طور نباشد. یک gateway جدیدتر ممکن است config.json را بازنویسی کند یا پایگاه‌داده‌های حافظه را به شکلی تغییر دهد که gateway قدیمی قادر به خواندن آن نباشد؛ تا تاریخ August 2026 هیچ مسیر رسمی برای دانگرید (downgrade) مستند نشده است. بنابراین اگر image قدیمی اجرا شد اما رفتار عجیبی داشت، وقت خود را صرف عیب‌یابی نکنید. آن را متوقف کنید، نسخه پشتیبانی که پیش از ارتقا تهیه کرده بودید را بازیابی کنید و دوباره شروع کنید. این دقیقاً همان دلیلی است که تهیه نسخه پشتیبان باید در اولویت باشد و به همین دلیل است که عادتِ «ابتدا ارتقا و سپس پشتیبان‌گیری» در پروژه‌ای به این جوانی، با شکست مواجه می‌شود.

مواردی که در اینجا اثبات نشده‌اند

در مورد قدمت این نرم‌افزار صادق باشید. نسخه 0.1.3 در زمان نگارش این متن تنها چند روز عمر دارد، یادداشت‌های انتشار آن صرفاً لینک‌های خودکار به changelog هستند و نه راهنمای مهاجرت، و هنوز هیچ سابقه عملیاتی برای ارتقا وجود ندارد. هیچ‌کدام از موارد این راهنما نتیجه استفاده طولانی‌مدت نیستند؛ بنابراین رشد حافظه، حجم پایگاه داده و پایداری زمان‌بندی (scheduler) را به عنوان مواردی در نظر بگیرید که باید روی سرور خودتان اندازه‌گیری کنید، نه مواردی که بتوان به آن‌ها اطمینان کرد.

دو رفتار وجود دارد که پیش از تکیه بر آن‌ها، ارزش تست کردن توسط خودتان را دارند. نخست، اینکه آیا دانگرید (downgrade) می‌تواند وضعیت نوشته‌شده توسط نسخه جدیدتر را بخواند یا خیر: این کار را روی یک کپی از volume در زمانی که اهمیت حیاتی ندارد انجام دهید، نه در حین قطعی سرویس. دوم، اینکه وقتی ورود به سیستم Kiro منقضی می‌شود و در همان زمان یک job زمان‌بندی‌شده باید اجرا شود، gateway چه واکنشی نشان می‌دهد. هر دو مورد از آن دست لبه‌های تیز پروژه‌های نوپا هستند که معمولاً در نسخه‌های بعدی بی‌سروصدا اصلاح می‌شوند و بررسی هر دو در حال حاضر کم‌هزینه است.

FAQ

چرا داشبورد KiroCrew روی IP عمومی سرور من باز نمی‌شود؟

زیرا نمونهٔ منتشرشده، پورت را به loopback متصل می‌کند. -p 127.0.0.1:5476:5476 پورت کانتینر را فقط به آدرس loopback میزبان نگاشت می‌کند که این کار عمدی است. برای دسترسی به آن، پورت را از طریق SSH با ssh -N -L 5476:127.0.0.1:5476 you@your-server فوروارد کنید و سپس http://localhost:5476/?token=<token> را در لپ‌تاپ خود باز کنید. حذف پیشوند 127.0.0.1: برای در دسترس قرار دادن آن، گیت‌وی را روی اینترنت عمومی قرار می‌دهد و یک قانون فایروال نمی‌تواند آن را محدود کند، زیرا قوانین DNAT پورت‌های منتشرشدهٔ Docker پیش از فیلتر شدن ترافیک توسط ufw ارزیابی می‌شوند.

KiroCrew داده‌های خود را کجا ذخیره می‌کند و از چه چیزی باید نسخه پشتیبان تهیه کنم؟

همه چیز در ~/.kiro/crew قرار دارد که در داخل ایمیج کانتینر /home/kirocrew/.kiro/crew است و KIROCREW_HOME آن را جابه‌جا می‌کند. در حالی که گیت‌وی متوقف است، از کل دایرکتوری یا کل Docker volume نسخه پشتیبان تهیه کنید. memory.db و memory_index.db پایگاه‌داده‌های SQLite هستند، بنابراین کپی‌برداری در حین نوشتن گیت‌وی می‌تواند منجر به ناسازگاری شود. هنگام انتقال به یک میزبان جدید، workspace/memory/، دو فایل پایگاه‌داده و config.json منتقل می‌شوند، در حالی که فایل‌های PID، لاگ رویدادهای امنیتی و .env متعلق به میزبان قدیمی هستند.

آیا باید از تگ stable استفاده کنم یا یک تگ نسخه؟

از یک تگ نسخه استفاده کنید. stable با هر بار انتشار نسخه جدید تغییر می‌کند، بنابراین نسخه‌ای که اجرا می‌کنید ممکن است در pull بعدی تغییر کند و خود تگ هیچ اطلاعاتی درباره آنچه در حال اجراست به شما نمی‌دهد. تگ‌های نسخه مانند 0.1.3 تغییرناپذیر هستند و دقیقاً همین ویژگی باعث می‌شود rollback کار کند: شما شماره قدیمی را برمی‌گردانید و همان ایمیج دقیق را دریافت می‌کنید. تا تاریخ 6 August 2026 جدیدترین نسخه 0.1.3 است.

چرا ایجنت من از اجرای هیچ دستوری خودداری می‌کند؟

کانتینر در اولین شروع خود، پشتیبانی از sandbox را بررسی می‌کند. اگر نتواند زیرفرآیندهای ایجنت را ایزوله کند و KIROCREW_ALLOW_UNSANDBOXED=1 تنظیم نشده باشد، از اجرای آن‌ها خودداری می‌کند تا اینکه آن‌ها را بدون محدودیت اجرا کند؛ بنابراین گیت‌وی سالم به نظر می‌رسد در حالی که همه وظایف متوقف شده‌اند. docker logs kirocrew تصمیم مربوط به sandbox را از همان اجرای اول نشان می‌دهد. تنظیم این متغیر باعث می‌شود کانتینر تنها مرز بین ایجنت و میزبان باشد، بنابراین اگر آن را تنظیم کردید، چیزی را mount نکنید که مستقیماً به ایجنت نمی‌سپارید.

آیا برای self-host کردن KiroCrew به حساب کاربری Kiro نیاز دارم؟

بله، تا آگوست 2026. KiroCrew نرم‌افزار آزاد تحت مجوز Apache 2.0 است، اما از kiro-cli استفاده می‌کند که نیاز به یک بار ورود به سیستم دارد و استنتاج ایجنت (agent inference) در قالب یک طرح Kiro صورت‌حساب می‌شود. در کانتینر، docker exec -it kirocrew kiro-cli login را اجرا کنید و کد دستگاه را در مرورگر خود تأیید کنید. تا زمانی که این ورود به سیستم کامل نشود، گیت‌وی شروع به کار می‌کند و داشبورد بارگذاری می‌شود، اما ایجنت مدلی برای ارتباط ندارد.