آموزش میزبانی KiroCrew روی VPS و اجرای دائمی آن
با اجرای KiroCrew در یک کانتینر Docker روی VPS، از پایداری حافظه و وظایف زمانبندیشده اطمینان حاصل کنید. این راهنما شامل تنظیم systemd، مدیریت پورت 5476 و روشهای بازگردانی نسخه است.
چرا KiroCrew را بهجای لپتاپ روی VPS میزبانی کنیم
میزبانی شخصی KiroCrew تنها زمانی نتیجهبخش است که روی دستگاهی اجرا شود که هرگز خاموش نمیشود؛ بنابراین VPS گزینه مناسبی است و لپتاپ خیر. KiroCrew تاریخچه نشستها، حافظه معنایی، وظایف زمانبندیشده و صف تأیید را روی دیسک ذخیره میکند و هنگام راهاندازی مجدد پردازش، تمام آنها را بارگذاری میکند. اگر پردازش در ساعت 03:00 که زمان اجرای یک وظیفه زمانبندیشده است در حال اجرا نباشد، هیچکدام از این قابلیتها کارایی ندارند و لپتاپ بسته نیز آن را اجرا نمیکند.
KiroCrew یک فضای کاری عامل (agent workspace) متنباز از تیم Kiro است که تحت مجوز Apache 2.0 ارائه شده و 0.1.0 در تاریخ 22 July 2026 منتشر شده است. یک پردازش به نام gateway، وضعیت را مدیریت کرده و یک داشبورد وب را روی پورت 5476 ارائه میدهد. شما از طریق داشبورد، از طریق CLI مربوط به kirocrew یا از طریق کانالهای چت مانند Slack به این gateway دسترسی پیدا میکنید. تنها چیزی که شما شخصاً میزبانی میکنید همین gateway است؛ بنابراین این راهنما بر حفظ پایداری آن، دور نگه داشتن آن از اینترنت عمومی و توانایی بازگردانی آن پس از یک ارتقای ناموفق تمرکز دارد.
دو نکته که باید پیش از شروع بدانید. از زمان 0.11.0، نصبهای جدید KiroCrew که انتخاب harness در آنها ذخیره نشده باشد، بهصورت پیشفرض از KAS استفاده میکنند و نیازی به kiro-cli ندارند؛ انتخابهای صریح قبلی در Kiro CLI حفظ میشوند. استنتاج (Inference) در بکاندهای Kiro از طرح اشتراکی Kiro شما استفاده میکند، بنابراین از تاریخ 1 November 2026، این تنظیمات پیشفرض آفلاین نیستند. این پروژه همچنین نوپا است و بهسرعت پیشرفت میکند: نسخههای پایدار آن از 0.1.3 در 5 August 2026 به 0.10.0 در 25 October 2026 رسید، در حالی که 0.8.0 در 9 October و 0.9.0 در 16 October در این میان منتشر شدند و یک کاندیدای انتشار 0.11.0 نیز در 25 October بهعنوان پیشانتشار عرضه شده بود. فرض را بر این بگیرید که در مقطعی نیاز به بازگشت به نسخه قبلی (roll back) خواهید داشت و آن را بهگونهای نصب کنید که این امکان فراهم باشد. اگر قبلاً عاملی را روی سرور اجرا نکردهاید، اجرای یک عامل برنامهنویسی روی VPS اصول اولیهای را پوشش میدهد که این راهنما بر پایه آنها بنا شده است. اگر مبحث عاملها برای شما جدیدتر از مبحث سرور است، یادگیری ماهیت حلقه عامل، ابزارها و حافظه آن باعث میشود تصمیمات زیر را آگاهانه اتخاذ کنید، نه اینکه صرفاً دستوراتی کورکورانه را اجرا کنید.
نیازمندیهای KiroCrew و محل ذخیرهسازی وضعیت آن
یک نصب بومی (native) به Python 3.12 یا جدیدتر نیاز دارد، و اگر قصد دارید داشبورد را از سورس کامپایل کنید، به Node.js 22.12.0 یا جدیدتر (پروژه Node 24 LTS را توصیه میکند). بکاند Kiro CLI به kiro-cli نیاز دارد که با kiro-cli login یا یک API key برای استفاده خودکار احراز هویت میشود؛ از زمان 0.10.0، موتور داخلی KAS بدون نیاز به نصب kiro-cli اجرا میشود و 0.11.0 آن را به گزینه پیشفرض برای نصبهای جدید بدون انتخاب harness ذخیرهشده تبدیل کرده است. نصب کانتینری به هیچکدام از این موارد روی میزبان نیاز ندارد. تنها پیشنیاز آن Docker است. این اصلیترین دلیل برای ترجیح دادن این روش است.
وضعیت (state) در ~/.kiro/crew ذخیره میشود و متغیر محیطی KIROCREW_HOME میتواند آن را به مسیر دیگری منتقل کند. محتویات این دایرکتوری عبارتند از:
config.json: تنظیمات gateway و اعتبارنامههای کانالهای گفتگو..env: اسرار (secrets).workspace/memory/: ترجیحات، یادداشتهای پروژه و تاریخچه گفتگوها.memory.dbوmemory_index.db: ایندکسهای معنایی (semantic) و تماممتن (full-text).models/: مدل embedding که در اولین اجرا دانلود میشود.security_events.jsonl: لاگ رویدادهای امنیتی.
آن دایرکتوری در واقع همان نصب شماست. با کپی کردن آن روی یک VPS جدید، ایجنت خود را منتقل کردهاید؛ به همین دلیل است که بخش پشتیبانگیری در ادامه، اهمیت بیشتری نسبت به بخش نصب دارد.
برای دیسک برنامهریزی کنید، نه RAM. گیتوی یک پردازش Python است؛ آنچه در واقع بار سیستم را افزایش میدهد، هر چیزی است که ایجنت اجرا میکند، مانند یک build یا یک مجموعه تست. دایرکتوری وضعیت با تاریخچه گفتگوها رشد میکند و مدل embedding در اولین اجرا دریافت میشود، بنابراین پس از چند هفته، آن را روی سیستم خود با du -sh ~/.kiro/crew اندازهگیری کنید و به ارقام منتشر شده در ماههای نخست پروژه اعتماد نکنید. این را با یک runtime مقایسه کنید که به هر worker یک کانتینر و مرورگر اختصاصی میدهد، جایی که میزبانی شخصی همکاران هوش مصنوعی OpenBot باعث میشود تعیین اندازه پیش از آنکه به دیسک مربوط باشد، به یک مسئله RAM تبدیل شود.
کدامیک از چهار مسیر نصب را باید انتخاب کنید
این پروژه چهار روش نصب ارائه میدهد: اپلیکیشن دسکتاپ، نصبکننده تکخطی wheel، سورسکد و Docker. نصبکننده تکخطی، یک فایل 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.8.0ایمیج کانتینر در ghcr.io/kirodotdev/kirocrew و برای linux/amd64 و linux/arm64 تحت تمامی تگها منتشر میشود. بیلد سورسکد شامل git clone به علاوه make build است و برای افرادی که قصد تغییر در کد را دارند مناسب است، نه برای کسانی که صرفاً میخواهند آن را اجرا کنند.
از کانتینر استفاده کنید. نصب بومی از طریق سورسکد، پکیجهای Python و Node را روی همان هاستی قرار میدهد که سایر سرویسهای شما در حال اجرا هستند، بهعلاوه kiro-cli هنگام استفاده از بکاند Kiro CLI؛ بنابراین اگر یک بهروزرسانی با مشکل مواجه شود، باید شخصاً آن را اصلاح کنید. کانتینر، محیط اجرا را در یک ایمیج و وضعیت (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) است و latest نیز همینطور؛ که به همان نسخه اشاره دارد. این تگ به هر نسخهای که در لحظه، جدیدترین نسخهٔ پایدار باشد اشاره میکند، بنابراین در pull بعدی ممکن است نسخهای که اجرا میکنید بدون انتخاب شما تغییر کند و تگ هیچ رکوردی از اینکه چه نسخهای بوده است، ثبت نمیکند. تگهای نسخه تغییرناپذیر هستند، پس یکی از آنها را پین کنید. جدیدترین نسخهٔ پایدار تا تاریخ 1 November 2026 نسخهٔ 0.11.1 است که در 31 October 2026 منتشر شده و یک hot patch برای یکپارچگی حافظه و اصلاحات KAS در 0.11.0 است. نمونهٔ 0.8.0 در زیر از Kiro CLI استفاده میکند. تگهای insider و nightly نیز وجود دارند؛ nightly بیلدها را از main دنبال میکند.
فایل /opt/kirocrew/compose.yaml را بنویسید:
services:
kirocrew:
image: ghcr.io/kirodotdev/kirocrew:0.8.0
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/healthdocker compose ps باید ظرف یک دقیقه یا کمتر، وضعیت کانتینر را به عنوان 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.targetsudo systemctl daemon-reload
sudo systemctl enable --now kirocrew
systemctl status kirocrewsystemctl 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 پیشفرض Kiro CLI در ایمیج pinned 0.8.0 همچنان به احراز هویت نیاز دارد. داخل کانتینر وارد شوید یا برای استفاده خودکار، KIRO_API_KEY را از طریق محیط کانتینر ارسال کنید:
docker exec -it kirocrew kiro-cli loginاین دستور یک کد دستگاه و یک URL چاپ میکند که باید آن را در مرورگر خود باز کنید. سپس یک توکن داشبورد ایجاد (mint) کنید:
docker exec kirocrew kirocrew token --ttl 2hURL داشبورد http://localhost:5476/?token=<the token> است. توکنها منقضی میشوند: لینک چاپشده باید ظرف پنج دقیقه پس از ایجاد باز شود و این دستور یک کوکی دسترسی دو ساعته درخواست میکند، در حالی که حداکثر زمان مستندشده 20 ساعت است. مرورگر همچنین یک کوکی refresh با بازه زمانی 30 روزه دریافت میکند، بنابراین یک نشست فعال بدون نیاز به لینک مجدد تمدید میشود. داشبوردی که خالی بارگذاری میشود یا شما را بلافاصله به بیرون هدایت میکند، معمولاً به دلیل انقضای توکن است؛ بنابراین یک توکن جدید ایجاد کرده و بلافاصله آن را باز کنید. هرگز توکن را در تیکت یا پیام چت کپی نکنید، زیرا هر کسی که آن را در اختیار داشته باشد، به agent شما دسترسی خواهد داشت.
دسترسی به داشبورد از طریق SSH و عدم انتشار پورت 5476
به آدرس bind در مثال پروژه یعنی -p 127.0.0.1:5476:5476 دوباره نگاه کنید. داخل کانتینر، گیتوی روی 0.0.0.0 گوش میدهد، زیرا باید از طریق نگاشت پورت (port mapping) در دسترس باشد، اما خودِ نگاشت فقط روی loopback میزبان منتشر میشود. اگر پیشوند 127.0.0.1: را حذف کنید، گیتوی برای هر کسی که آن پورت را اسکن کند در اینترنت عمومی در دسترس خواهد بود. یک قانون ufw نیز شما را نجات نخواهد داد: Docker پورتها را با نوشتن قوانین DNAT منتشر میکند که ترافیک را پیش از اعمال قوانین ufw هدایت میکنند، بنابراین ufw deny 5476 هیچ تأثیری بر پورت منتشرشده ندارد. با backend پیشفرض iptables در Docker، پاسخ خودِ Docker قرار دادن قوانین فیلترینگ در زنجیره DOCKER-USER است. این روش کار میکند، اما آن قوانین آدرس و پورت داخلی کانتینر را میبینند مگر اینکه با افزونه conntrack مطابقت دهید؛ بنابراین bind کردن روی loopback سادهترین روش کنترلی است که احتمال اشتباه در آن کمتر است. در مقابل، backend مبتنی بر nftables در Docker از جداول و زنجیرههای پایه مجزا برای فیلترینگ سفارشی استفاده میکند. دور زدن 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=... بروید. نیازی به تنظیم اضافی loopback-port یا بازسازی کانتینر نیست: مبدأ (Origin) در loopback با Host درخواست مطابقت دارد، بنابراین بررسی CSRF آن را میپذیرد. بهمحض اینکه عامل دوم (agent) از همان سرور استفاده کند، شما شروع به انباشتن فورواردها به این شکل خواهید کرد، زیرا میزبانی شخصی open-kritt برای اسکن امنیتی یک داشبورد دیگر با محدودیت loopback را روی همان سرور و روی پورت 5173 قرار میدهد.
دو رفتار مستندشده تعیین میکنند که کدام تنظیمات را میتوانید از داشبورد تغییر دهید. نخست، گیتوی هر درخواستی که دارای هدرهای فورواردینگ (Forwarded، X-Forwarded-* یا X-Real-IP) باشد را بهعنوان درخواست از راه دور تلقی میکند و نقاط پایانی (endpoints) مربوط به نوشتن تنظیمات و نمایش اسرار، این درخواستها را رد میکنند. یک reverse proxy این هدرها را اضافه میکند؛ یک فوروارد ساده ssh -L هیچ هدر اضافهای ندارد، بنابراین محلی به نظر میرسد و از این بابت رد نمیشود. دوم، در image کانتینر، صفحات اعتبارنامه کانال (channel-credential) و نماهای نمایش اسرار برای هر مرورگری که مستقیماً محلی (direct-local) نباشد، فقطخواندنی هستند و image هیچ ویرایشگر متنی به همراه ندارد. اعتبارنامه کانالی که از داشبورد ذخیره نمیشود، به این دلیل است و باگ نیست. در عوض، فایل تنظیمات را روی میزبان ویرایش کنید:
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 عمومی ترجیح دهید. توکن در URL جابهجا میشود و URL در تمام لاگهای دسترسی در مسیر خود ثبت میگردد. این قانون درباره چیزی است که پشت پورت قرار دارد، نه خودِ پورت: چیزی مانند Halcyon که کتابخانه Jellyfin را به یک فروشگاه ویدیوی دهه نودی قابل مرور تبدیل میکند برای باز شدن توسط دیگران وجود دارد و کاندیدای مناسبی برای reverse proxy است، در حالی که گیتویای که میتواند دستورات را روی سرور شما اجرا کند، چنین نیست.
کمترین شعاع انفجار ممکن را برای agent در نظر بگیرید
این کانتینر در اولین اجرا، پشتیبانی از sandbox را بررسی میکند و نتیجهٔ آن تعیین میکند که آیا agentها اجازهٔ اجرای هیچ دستوری را دارند یا خیر. اگر ایزولهسازی namespace در دسترس باشد، زیرفرآیندهای agent بهصورت ایزوله اجرا میشوند. اگر این قابلیت در دسترس نباشد و KIROCREW_ALLOW_UNSANDBOXED=1 تنظیم نشده باشد، اجرا بهجای آنکه بدون محدودیت (unconfined) انجام شود، رد میشود؛ بنابراین اگر gateway سالم به نظر میرسد اما تمام taskها متوقف شدهاند، معمولاً مشکل همین است. تصمیم نهایی در 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روی میزبانی که AppArmor در آن فعال است، راهنمای Docker این پروژه میگوید پروفایل seccomp تنها نیمی از تغییرات است، زیرا Docker پروفایل docker-default AppArmor خود را نیز ضمیمه میکند و آن را با apparmor=unconfined جفت میکند. این گزینه فقط قوانین AppArmor برای هر کانتینر را برمیدارد؛ پروفایل seccomp، قابلیتهای حذفشده (dropped capabilities) و کاربر غیر-root همچنان اعمال میشوند.
اگر KIROCREW_ALLOW_UNSANDBOXED=1 را تنظیم کردید، دقیقاً بدانید چه چیزی تغییر کرده است: کانتینر اکنون تنها مرز بین agent و سرور شماست. هشدار پروژه ارزش تکرار کامل دارد. مسیرهای میزبان (host paths) را که مستقیماً به agent نمیسپارید، mount نکنید. در عمل، این موضوع استفاده از Docker socket، هرگونه bind mount از / و هر دایرکتوری که دادههای سرویس دیگری را نگه میدارد، منتفی میکند.
باقی موارد، چارچوبی است که برای هر agent که اجازه اجرای دستور دارد، اعمال میشود. دسترسیهای (credentials) آن را به یک مخزن یا یک bucket خاص که نیاز دارد محدود کنید و هرگز از یک توکن شخصی با دسترسیهای کل حساب استفاده نکنید. آن را بهعنوان یک کاربر اختصاصی اجرا کنید که دایرکتوری home او حاوی هیچ چیز دیگری نیست؛ این همان چیزی است که کاربران با حداقل دسترسی روی VPS برای آن طراحی شده است. وقتی agent کد مینویسد و سپس آن کد را اجرا میکند، ماشینی را در اختیارش بگذارید که اجازه دارد آن را خراب کند: یک VM یکبارمصرف برای agentهای برنامهنویس مرز قویتری نسبت به هر flag در این فایل compose است، زیرا بهجای پاکسازی، آن را حذف میکنید. همین استدلال، اجرای امن OpenClaw روی VPS و میزبانی شخصی agent Hermes روی VPS را شکل میدهد. ابزارها نیز بخشی از شعاع انفجار محسوب میشوند: دادن دسترسی جستجوی وب به agent، هر صفحهای که fetch میکند را به ورودی غیرقابلاعتماد تبدیل میکند، بنابراین هدایت آن به سمت نمونه SearXNG خودتان، هم یک تصمیم برای جلوگیری از prompt injection است و هم یک تصمیم زیرساختی. کارهای زمانبندیشده (Scheduled work) در حالی که خواب هستید هزینه ایجاد میکنند، زیرا استنتاج (inference) در backendsهای Kiro از طرح Kiro شما استفاده میکند؛ بنابراین پیش از افزودن یک job شبانه، محدودیتهای توصیفشده در کنترل هزینههای یک AI agent روی 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 را دوباره در میزبان جدید وارد نمایید.
چگونه یک ارتقای ناموفق را بازگردانی کنیم
فرآیند ارتقا کوتاه است و تنها به این دلیل ایمن است که شما یک نسخه خاص را ثابت (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/healthdocker compose up -d اگر ایمیج از قبل روی سیستم نباشد، آن را دانلود میکند، بنابراین ویرایش تگ تمام کاری است که برای ارتقا انجام میدهید. بازگردانی (rollback) نیز دقیقاً با همان توالی و با استفاده از شماره نسخه قدیمی انجام میشود و دقیقاً همان ایمیجی را که قبلاً داشتید به شما میدهد، زیرا تگهای نسخه تغییرناپذیر هستند.
فایل باینری بهتمیزی بازگردانی میشود. وضعیت (state) بخشی است که ممکن است اینطور نباشد. یک gateway جدیدتر میتواند config.json را بازنویسی کند یا دیتابیسهای حافظه را به شکلی مهاجرت دهد که gateway قدیمیتر قادر به خواندن آن نباشد، و تا تاریخ 12 October 2026 هیچ مسیر دانگریدی برای وضعیت (state) مستند نشده است. راهنمای نصب در یک مورد صریح است: دادههایی که از مسیر قدیمی ~/.kirocrew منتقل شدهاند، قابلیت بازگردانی ندارند و نسخهای که قدیمیتر از ~/.kiro/crew باشد، خالی شروع به کار میکند. بنابراین اگر ایمیج قدیمی اجرا شد و رفتار عجیبی داشت، آن را عیبیابی نکنید. آن را متوقف کنید، نسخه پشتیبانی که پیش از ارتقا تهیه کرده بودید را بازیابی کنید و دوباره شروع کنید. این دقیقاً همان دلیلی است که تهیه نسخه پشتیبان باید در اولویت باشد و به همین دلیل است که عادتِ «ابتدا ارتقا، سپس پشتیبانگیری» در پروژهای به این جوانی شکست میخورد.
آنچه در اینجا اثبات نشده است
در مورد قدمت این نرمافزار صادق باشید. نسخه 0.1.3 در تاریخ 5 August 2026 منتشر شد و تا 12 October 2026، شاخه پایدار به نسخه 0.8.0 رسید. بیشتر یادداشتهای انتشار هنوز changelogهای خودکار هستند؛ یادداشتهای 0.8.0 بهصورت دستی نوشته شدهاند اما فاقد بخش مهاجرت (migration) هستند و تاریخچه انتشار عمومی حدود سه ماه است. هیچچیز در این راهنما نتیجه بلندمدت نیست، بنابراین رشد حافظه، حجم دیتابیس و پایداری زمانبند (scheduler) را بهجای فرض کردن، روی سرور خودتان اندازهگیری کنید.
دو رفتار ارزش آن را دارند که پیش از تکیه بر آنها، خودتان تست کنید. نخست، اینکه آیا دانگرید (downgrade) میتواند وضعیت نوشتهشده توسط نسخه جدیدتر را بخواند یا خیر: این کار را روی نسخهای کپیشده از volume در زمانی که اهمیتی ندارد انجام دهید، نه در حین قطعی سرویس. دوم، اینکه وقتی ورود به سیستم Kiro منقضی میشود و همزمان یک job زمانبندیشده باید اجرا شود، gateway چه واکنشی نشان میدهد. هر دو مورد از آن دست لبههای تیز پروژههای نوپا هستند که معمولاً در نسخههای بعدی بهآرامی اصلاح میشوند و بررسی هر دو در حال حاضر کمهزینه است.
FAQ
چرا داشبورد KiroCrew روی IP عمومی سرور من باز نمیشود؟
زیرا نمونهٔ منتشرشده، پورت را به loopback متصل میکند. -p 127.0.0.1:5476:5476 پورت کانتینر را فقط به آدرس loopback میزبان نگاشت میکند که این یک اقدام عمدی است. برای دسترسی به آن، پورت را با ssh -N -L 5476:127.0.0.1:5476 you@your-server از طریق SSH فوروارد کنید و سپس http://localhost:5476/?token=<token> را در لپتاپ خود باز کنید. حذف پیشوند 127.0.0.1: برای در دسترس قرار دادن آن، دروازه (gateway) را در معرض اینترنت عمومی قرار میدهد و ufw آن را کنترل نخواهد کرد، زیرا قوانین DNAT مربوط به پورتهای منتشرشدهٔ Docker، ترافیک را پیش از اعمال قوانین ufw هدایت میکنند. برای فیلتر کردن پورتهای منتشرشده، از زنجیرهٔ DOCKER-USER در Docker با backend مربوط به iptables، یا از زنجیرههای پایهٔ مجزای nftables با backend مربوط به nftables استفاده کنید؛ حفظ اتصال به loopback سادهتر است.
KiroCrew دادههای خود را کجا ذخیره میکند و از چه چیزی باید نسخه پشتیبان تهیه کنم؟
همه چیز در ~/.kiro/crew قرار دارد که در داخل ایمیج کانتینر به صورت /home/kirocrew/.kiro/crew است و KIROCREW_HOME آن را جابهجا میکند. در حالی که دروازه متوقف است، از کل دایرکتوری یا کل volume مربوط به Docker نسخه پشتیبان تهیه کنید. memory.db و memory_index.db پایگاهدادههای SQLite هستند، بنابراین کپیبرداری در زمانی که دروازه در حال نوشتن است، ممکن است باعث ناسازگاری دادهها شود. هنگام انتقال به یک میزبان جدید، workspace/memory/، دو فایل پایگاهداده و config.json منتقل میشوند، در حالی که فایلهای PID، لاگ رویدادهای امنیتی و .env متعلق به میزبان قدیمی هستند.
آیا باید از تگ stable استفاده کنم یا یک تگ نسخه؟
از تگ نسخه استفاده کنید. stable با هر بار انتشار نسخهٔ جدید تغییر میکند، بنابراین نسخهای که اجرا میکنید ممکن است در pull بعدی تغییر کند و خودِ تگ هیچ اطلاعاتی دربارهٔ آنچه در حال اجراست به شما نمیدهد. تگهای نسخه مانند 0.8.0 تغییرناپذیر هستند و دقیقاً همین ویژگی باعث میشود rollback کار کند: شما شمارهٔ قدیمی را برمیگردانید و دقیقاً همان ایمیج را دریافت میکنید. از تاریخ 1 November 2026، جدیدترین نسخهٔ پایدار 0.11.1 است.
چرا ایجنت من از اجرای دستورات خودداری میکند؟
کانتینر در اولین اجرا، پشتیبانی از sandbox را بررسی میکند. اگر نتواند زیرفرآیندهای ایجنت را ایزوله کند و KIROCREW_ALLOW_UNSANDBOXED=1 تنظیم نشده باشد، بهجای اجرای آنها بدون محدودیت، از اجرایشان خودداری میکند؛ بنابراین دروازه سالم به نظر میرسد اما تمام وظایف متوقف میمانند. docker logs kirocrew تصمیم مربوط به sandbox را از همان اجرای اول نشان میدهد. تنظیم این متغیر باعث میشود کانتینر تنها مرز بین ایجنت و میزبان باشد، بنابراین اگر آن را تنظیم کردید، هیچ چیزی را که نمیخواهید مستقیماً به ایجنت بدهید، mount نکنید.
آیا برای self-host کردن KiroCrew به حساب کاربری Kiro نیاز دارم؟
از تاریخ 1 November 2026، برای backendهای Kiro بله. KiroCrew یک نرمافزار آزاد تحت مجوز Apache 2.0 است، اما استنتاج (inference) در آن backendها از طرح اشتراک Kiro شما استفاده میکند. کانتینر پینشدهٔ 0.8.0 از Kiro CLI استفاده میکند: docker exec -it kirocrew kiro-cli login را اجرا کنید و کد دستگاه را در مرورگر خود تأیید کنید، یا برای استفادهٔ خودکار، KIRO_API_KEY را از طریق محیط کانتینر ارسال کنید. تا زمانی که احراز هویت پیکربندی نشود، آن دروازه بالا میآید و داشبورد بارگذاری میشود، اما harness پیشفرض آن مدلی برای ارتباط ندارد. از زمان 0.10.0، یک موتور KAS داخلی نیز وجود دارد که نیازی به نصب kiro-cli ندارد؛ 0.11.0 باعث شد KAS برای نصبهای جدید بدون انتخاب harness ذخیرهشده، به گزینهٔ پیشفرض تبدیل شود، در حالی که انتخابهای صریح Kiro CLI حفظ میشوند. KAS بهجای kiro-cli login از ورود به سیستم اختصاصی Crew استفاده میکند. راهنمای backend سفارشی پروژه به یک harness از نوع claude اجازه میدهد تا درخواستهای مدل اصلی را به یک endpoint سازگار با Anthropic که شما انتخاب میکنید بفرستد، اما ورود به سیستم kiro-cli همچنان برای ویژگیهای خاص Kiro باقی میماند.