Jak zainstalować KiroCrew na VPS w kontenerze Docker
Instrukcja konfiguracji KiroCrew na serwerze VPS z wykorzystaniem Docker i systemd. Zapewnij ciągłość pracy agenta, poprawne zarządzanie pamięcią oraz bezpieczne kopie zapasowe.
Dlaczego warto hostować KiroCrew na VPS zamiast na laptopie
Samodzielny hosting KiroCrew ma sens tylko na maszynie, która nigdy nie przechodzi w stan uśpienia, dlatego VPS jest właściwym środowiskiem, w przeciwieństwie do laptopa. KiroCrew przechowuje historię sesji, pamięć semantyczną, zaplanowane zadania oraz kolejkę zatwierdzeń na dysku i wczytuje te dane przy każdym restarcie procesu. Nie przynosi to korzyści, jeśli proces nie działa o godzinie 03:00, gdy przypada termin wykonania zadania, a zamknięty laptop nie zapewnia ciągłości pracy.
KiroCrew to otwartoźródłowe środowisko pracy dla agentów od zespołu Kiro, udostępnione na licencji Apache 2.0, którego 0.1.0 wydano 22 lipca 2026 roku. Jeden proces, zwany gateway, zarządza stanem i udostępnia panel webowy na porcie 5476. Dostęp do gatewaya uzyskuje się z poziomu panelu, interfejsu kirocrew CLI lub kanału czatu, takiego jak Slack. Gateway jest jedynym komponentem hostowanym samodzielnie, dlatego niniejszy przewodnik skupia się na utrzymaniu jego ciągłej pracy, izolacji od publicznego Internetu oraz możliwości przywrócenia systemu po nieudanej aktualizacji.
Dwie kwestie, które należy znać przed rozpoczęciem. Od wersji 0.11.0 nowe instalacje KiroCrew bez wybranego wcześniej środowiska uruchomieniowego domyślnie korzystają z KAS bez konieczności użycia kiro-cli; istniejące, jawne wybory w Kiro CLI zostają zachowane. Inferencja na backendach Kiro wykorzystuje posiadany plan Kiro, więc według stanu na 1 listopada 2026 roku ta domyślna konfiguracja nie działa w trybie offline. Projekt jest młody i rozwija się dynamicznie: stabilne wydania zmieniały się od 0.1.3 w dniu 5 sierpnia 2026 roku do 0.10.0 w dniu 25 października 2026 roku, z wersjami 0.8.0 z 9 października oraz 0.9.0 z 16 października pomiędzy nimi, a wersja 0.11.0 kandydująca do wydania była już dostępna jako pre-release 25 października. Należy założyć konieczność wycofania zmian w pewnym momencie i przeprowadzić instalację w sposób, który to umożliwi. Jeśli użytkownik nie uruchamiał wcześniej agenta na serwerze, artykuł uruchamianie agenta programistycznego na VPS zawiera podstawowe zasady, na których opiera się ten przewodnik. Jeśli kwestie związane z agentami są mniej znane niż administracja serwerem, zapoznanie się z tematem czym w rzeczywistości jest pętla agenta, jego narzędzia i pamięć sprawi, że poniższe wybory będą świadomymi decyzjami, a nie zestawem niezrozumiałych poleceń.
Czego wymaga KiroCrew i gdzie przechowywany jest jego stan
Instalacja natywna wymaga środowiska Python 3.12 lub nowszego oraz Node.js 22.12.0 lub nowszego, jeśli dashboard jest budowany ze źródeł (projekt zaleca Node 24 LTS). Backend Kiro CLI wymaga kiro-cli, uwierzytelnionego za pomocą kiro-cli login lub klucza API w przypadku użycia automatycznego. Od wersji 0.10.0 wbudowany silnik KAS działa bez zainstalowanego kiro-cli, a 0.11.0 uczyniło go domyślnym dla nowych instalacji bez zapisanych ustawień środowiska uruchomieniowego. Instalacja kontenerowa nie wymaga żadnego z powyższych na hoście. Wymaga jedynie Docker. Jest to główny powód, dla którego warto ją preferować.
Stan przechowywany jest w ~/.kiro/crew, a zmienna środowiskowa KIROCREW_HOME pozwala na zmianę tej lokalizacji. Zawartość katalogu:
config.json: ustawienia bramy i dane uwierzytelniające kanałów czatu..env: sekrety.workspace/memory/: preferencje, notatki projektowe i historia czatu.memory.dborazmemory_index.db: indeksy semantyczne i pełnotekstowe.models/: model osadzeń (embedding model), pobierany przy pierwszym uruchomieniu.security_events.jsonl: dziennik zdarzeń bezpieczeństwa.
Ten katalog stanowi całą instalację. Skopiowanie go na nowy VPS przenosi agenta, dlatego sekcja dotycząca kopii zapasowych jest ważniejsza niż sekcja instalacji.
Należy planować zasoby dyskowe, a nie RAM. Brama jest procesem Python; to, co faktycznie obciąża serwer, zależy od zadań wykonywanych przez agenta, takich jak kompilacja czy testy. Katalog stanu powiększa się wraz z historią czatu, a model osadzeń jest pobierany przy pierwszym uruchomieniu. Z tego powodu należy zmierzyć zajętość na własnej maszynie za pomocą du -sh ~/.kiro/crew po kilku tygodniach, zamiast polegać na wartościach publikowanych w pierwszych miesiącach projektu. Warto porównać to ze środowiskiem uruchomieniowym, w którym każdy pracownik otrzymuje własny kontener i własną przeglądarkę, gdzie self-hosting OpenBot's AI coworkers sprawia, że szacowanie zasobów RAM staje się ważniejsze niż zasobów dyskowych.
Którą z czterech ścieżek instalacji wybrać
Projekt udostępnia cztery warianty: aplikację desktopową, instalator typu one-line wheel, kod źródłowy oraz obraz Docker. Instalator typu one-line pobiera pakiet wheel i tworzy program uruchamiający kirocrew; jeśli jego katalog nie znajduje się w zmiennej PATH, wyświetlane są instrukcje dotyczące jego dodania:
curl -fsSL https://download.crew.kiro.dev/cli.sh | shInstalator przyjmuje flagę kanału oraz flagę wersji:
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.0Obraz kontenera jest publikowany pod adresem ghcr.io/kirodotdev/kirocrew, dla architektur linux/amd64 oraz linux/arm64 w ramach każdego tagu. Budowanie ze źródeł wymaga git clone oraz make build i jest przeznaczone dla osób modyfikujących kod, a nie dla użytkowników końcowych.
Należy użyć kontenera. Natywna instalacja ze źródeł umieszcza pakiety Python oraz Node na tym samym hoście, na którym działają inne usługi, a dodatkowo kiro-cli w przypadku korzystania z backendu Kiro CLI. Nieudana aktualizacja wymusza w takim scenariuszu ręczne usuwanie zmian. Kontener przechowuje środowisko uruchomieniowe w jednym obrazie, a stan w jednym wolumenie, co sprawia, że wycofanie zmian sprowadza się do zmiany tagu i restartu.
Przypnij obraz do tagu wydania, a nie do stable
Własny przykład projektu używa tagu stable:
docker run -d --name kirocrew \
-p 127.0.0.1:5476:5476 \
-v kirocrew-home:/home/kirocrew \
ghcr.io/kirodotdev/kirocrew:stablestable to tag zmienny, podobnie jak latest, który wskazuje na to samo wydanie. Wskazuje on na najnowsze stabilne wydanie, więc kolejne pobranie może zmienić uruchomioną wersję bez ingerencji użytkownika, a tag nie rejestruje informacji o tym, jaka to była wersja. Tagi wersji są niezmienne, więc należy przypiąć konkretny z nich. Najnowszym stabilnym wydaniem na dzień 1 listopada 2026 jest 0.11.1, opublikowane 31 października 2026, będące poprawką krytyczną dla integralności pamięci i poprawek KAS w 0.11.0. Poniższy przykład 0.8.0 wykorzystuje Kiro CLI. Dostępne są również tagi insider oraz nightly; nightly śledzi kompilacje z main.
Zapisz /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:Uruchom go, a następnie sprawdź punkt końcowy kondycji (health endpoint), którego obraz używa również do własnego HEALTHCHECK:
cd /opt/kirocrew
docker compose up -d
docker compose ps
curl -s http://127.0.0.1:5476/api/healthdocker compose ps powinien zgłosić kontener jako zdrowy w ciągu około minuty, a /api/health odpowiada bez tokena (podobnie jak /api/live i /api/ready, co czyni je użytecznymi jako sondy). Jeśli stan pozostaje starting, przeczytaj docker logs kirocrew przed wprowadzeniem jakichkolwiek zmian. Pierwsze uruchomienie pobiera model osadzeń (embedding model) w tle; wyszukiwanie w pamięci używa dopasowywania słów kluczowych, dopóki model nie zostanie pobrany.
Utrzymywanie ciągłości działania za pomocą systemd
restart: unless-stopped przywraca kontener po awarii oraz po restarcie systemu, o ile usługa Docker uruchamia się podczas startu. Plik jednostki (unit file) czyni tę zależność jawną i udostępnia jedno polecenie zatrzymujące cały stos przed wykonaniem kopii zapasowej. Uruchamianie stosu Docker Compose przy starcie systemu omawia ogólny schemat. Oto postać tego rozwiązania w stylu KiroCrew, zawarta w /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 powinno zwracać active (exited), co jest prawidłowym stanem dla tej jednostki. Type=oneshot z RemainAfterExit=yes jest tutaj właściwe, ponieważ docker compose up -d kończy działanie natychmiast po uruchomieniu kontenera: systemd monitoruje fakt, że stos jest aktywny, a nie proces działający na pierwszym planie. Wpisanie Type=simple spowoduje, że systemd odnotuje natychmiastowe zakończenie polecenia, oznaczy usługę jako nieaktywną, a następnie zrezygnuje lub wpadnie w pętlę restartów, w zależności od ustawienia Restart=. W przypadku instalacji natywnej projekt dostarcza własny odpowiednik, kirocrew service install, który zapisuje /etc/systemd/system/kirocrew.service i uruchamia bramę z uprawnieniami użytkownika. Nie należy uruchamiać obu jednostek jednocześnie. Szersze omówienie tego tematu znajduje się w usługi i timery systemd na VPS. Jednostka, która nie uruchamia się ponownie, nie generuje powiadomień, chyba że zostanie to skonfigurowane, dlatego warto dodać procedurę obsługi OnFailure=, która wysyła alert na własny serwer ntfy. Dzięki temu informacja o awarii bramy dotrze na telefon, zamiast czekać na wynik zaplanowanego zadania, które nigdy się nie wykonało.
Pierwsze uruchomienie: logowanie i uzyskanie tokena panelu
Kontener uruchamia bramę, jednak domyślne środowisko uruchomieniowe Kiro CLI w przypiętym obrazie 0.8.0 nadal wymaga uwierzytelnienia. Zaloguj się wewnątrz kontenera lub przekaż KIRO_API_KEY przez zmienne środowiskowe kontenera w celu automatyzacji:
docker exec -it kirocrew kiro-cli loginPolecenie to wyświetli kod urządzenia oraz adres URL, który należy otworzyć w przeglądarce. Następnie wygeneruj token panelu:
docker exec kirocrew kirocrew token --ttl 2hAdres URL panelu to http://localhost:5476/?token=<the token>. Tokeny wygasają: wygenerowany link musi zostać otwarty w ciągu pięciu minut od utworzenia, a niniejsze polecenie żąda pliku cookie z dwugodzinnym dostępem, przy czym dokumentacja określa dwadzieścia godzin jako wartość maksymalną. Przeglądarka otrzymuje również plik cookie odświeżania z 30-dniowym przesuwnym oknem bezczynności, dzięki czemu aktywna sesja odnawia się bez konieczności ponownego użycia linku. Panel, który ładuje się jako pusty lub natychmiast wylogowuje użytkownika, zazwyczaj oznacza wygasły token; należy wówczas wygenerować nowy i otworzyć go niezwłocznie. Nigdy nie wklejaj tokena do zgłoszeń serwisowych ani wiadomości na czacie, ponieważ osoba posiadająca token przejmuje kontrolę nad Twoim agentem.
Dostęp do panelu przez SSH bez wystawiania portu 5476
Należy ponownie przeanalizować adres powiązania w przykładzie projektu: -p 127.0.0.1:5476:5476. Wewnątrz kontenera brama nasłuchuje na 0.0.0.0, ponieważ musi być osiągalna poprzez mapowanie portów, jednak samo mapowanie publikuje usługę wyłącznie na interfejsie pętli zwrotnej (loopback) hosta. Usunięcie prefiksu 127.0.0.1: spowoduje wystawienie bramy na publiczny dostęp dla każdego, kto przeskanuje ten port. Reguła ufw również nie zapewni ochrony: Docker publikuje porty poprzez tworzenie reguł DNAT, które kierują ruch przed zastosowaniem reguł ufw, więc ufw deny 5476 nie ma wpływu na opublikowany port. Przy domyślnym backendzie iptables, Docker stosuje własne reguły filtrowania w łańcuchu DOCKER-USER. Rozwiązanie to działa, lecz reguły te widzą wewnętrzny adres i port kontenera, chyba że użyje się rozszerzenia conntrack. Z tego względu powiązanie z interfejsem loopback pozostaje prostszą i bezpieczniejszą metodą kontroli. Backend nftables w Dockerze wykorzystuje natomiast oddzielne tabele i łańcuchy bazowe do filtrowania niestandardowego. Artykuł Docker ports bypassing ufw szczegółowo opisuje ten mechanizm.
Zamiast tego należy przekierować port przez SSH z lokalnego komputera:
ssh -N -L 5476:127.0.0.1:5476 you@your-server.example.comProces ten powinien pozostać uruchomiony, a następnie należy otworzyć http://localhost:5476/?token=<the token> w lokalnej przeglądarce. Aby zautomatyzować przekierowanie przy każdym połączeniu, należy dodać odpowiedni wpis w ~/.ssh/config:
Host your-server.example.com
LocalForward 5476 127.0.0.1:5476Jeśli port 5476 jest już zajęty na lokalnym komputerze, należy zmienić tylko pierwszą liczbę: ssh -N -L 45476:127.0.0.1:5476 you@your-server.example.com, a następnie przejść pod adres http://localhost:45476/?token=.... Nie jest wymagana zmiana ustawień portu loopback ani ponowne tworzenie kontenera: źródło (Origin) loopback zgadza się z nagłówkiem Host żądania, dzięki czemu weryfikacja CSRF przebiega pomyślnie. Takie przekierowania będą stosowane kaskadowo w momencie, gdy drugi agent zacznie współdzielić zasoby serwera, ponieważ self-hosting open-kritt for security scanning uruchamia kolejny panel dostępny tylko przez loopback na tym samym serwerze, na porcie 5173.
Dwa udokumentowane zachowania decydują o tym, które ustawienia można zmieniać z poziomu panelu. Po pierwsze, brama traktuje każde żądanie zawierające nagłówki przekierowania (Forwarded, X-Forwarded-* lub X-Real-IP) jako zdalne, przez co punkty końcowe służące do zapisu konfiguracji i ujawniania sekretów odrzucają takie żądania. Reverse proxy dodaje te nagłówki; zwykłe przekierowanie ssh -L ich nie dodaje, więc żądanie jest rozpoznawane jako lokalne i nie jest odrzucane z tego powodu. Po drugie, w obrazie kontenera strony z poświadczeniami kanałów oraz widoki ujawniające sekrety są dostępne tylko do odczytu dla przeglądarek, które nie łączą się bezpośrednio lokalnie, a obraz nie zawiera edytora tekstu. Jeśli poświadczenie kanału nie zapisuje się z poziomu panelu, jest to zamierzone działanie, a nie błąd. Konfigurację należy edytować bezpośrednio na hoście:
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 kirocrewW przypadku dostępu z telefonu projekt zaleca użycie tailscale serve od Tailscale, co pozwala utrzymać panel wewnątrz własnej sieci tailnet zamiast wystawiać go na publicznej nazwie hosta. Jest to rozwiązanie preferowane względem publicznego reverse proxy. Token jest przesyłany w adresie URL, a każdy adres URL jest zapisywany w każdym logu dostępu na swojej ścieżce. Zasada ta dotyczy tego, co znajduje się za portem, a nie samego portu: usługi takie jak Halcyon, which rebuilds a Jellyfin library as a browsable 90s video store są przeznaczone do udostępniania i stanowią odpowiednich kandydatów dla reverse proxy, podczas gdy brama zdolna do wykonywania poleceń na serwerze – nie.
Ograniczenie zasięgu działania agenta do minimum
Kontener podczas pierwszego uruchomienia sprawdza obsługę piaskownicy (sandbox), a wynik decyduje o możliwości wykonywania zadań przez agentów. Jeśli izolacja przestrzeni nazw (namespace isolation) jest dostępna, podprocesy agenta działają w izolacji. Jeśli nie jest dostępna, a zmienna KIROCREW_ALLOW_UNSANDBOXED=1 nie została ustawiona, wykonanie zadań zostaje odrzucone zamiast uruchomienia ich bez ograniczeń. Z tego powodu brama, która wydaje się poprawnie działająca, podczas gdy wszystkie zadania są wstrzymane, zazwyczaj wskazuje na ten problem. Decyzja jest zapisana w docker logs kirocrew od momentu pierwszego uruchomienia. Projekt udostępnia również profil seccomp (secure computing mode), który można zastosować:
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.jsonNa hoście z włączonym AppArmor, przewodnik Docker projektu określa profil seccomp jedynie jako połowę zmian, ponieważ Docker dołącza również swój profil AppArmor docker-default i łączy go z opcją apparmor=unconfined. Ta opcja znosi jedynie reguły AppArmor dla poszczególnych kontenerów; profil seccomp, usunięte uprawnienia (capabilities) oraz użytkownik niebędący rootem nadal obowiązują.
Jeśli ustawisz KIROCREW_ALLOW_UNSANDBOXED=1, należy mieć świadomość wprowadzonych zmian: kontener staje się wówczas jedyną barierą między agentem a serwerem. Ostrzeżenie projektu warto przytoczyć w całości. Nie należy montować ścieżek hosta, których nie przekazałoby się bezpośrednio agentowi. W praktyce wyklucza to gniazdo Docker, wszelkie montowania typu bind dla / oraz każdy katalog przechowujący dane innej usługi.
Reszta to ramy, które dotyczą każdego agenta uprawnionego do wykonywania poleceń. Należy ograniczyć jego poświadczenia do jednego repozytorium lub jednego zasobnika (bucket), którego potrzebuje, nigdy nie używając tokena osobistego z uprawnieniami do całego konta. Agent powinien działać jako dedykowany użytkownik, którego katalog domowy nie zawiera żadnych innych plików, co opisano w użytkownicy z minimalnymi uprawnieniami na VPS. Gdy agent pisze kod, a następnie go uruchamia, należy zapewnić mu maszynę, której uszkodzenie jest dopuszczalne: jednorazowa maszyna wirtualna dla agentów programistycznych stanowi silniejszą barierę niż jakakolwiek flaga w tym pliku compose, ponieważ maszynę taką można usunąć zamiast czyścić. To samo rozumowanie kształtuje bezpieczne uruchamianie OpenClaw na VPS oraz samodzielne hostowanie agenta Hermes na VPS. Narzędzia również zwiększają zasięg potencjalnej awarii: umożliwienie agentowi wyszukiwania w sieci sprawia, że każda pobrana strona staje się danymi wejściowymi niezaufanego pochodzenia, dlatego skierowanie go na własną instancję SearXNG jest decyzją dotyczącą zarówno bezpieczeństwa przed wstrzykiwaniem poleceń (prompt injection), jak i konfiguracji infrastruktury. Zaplanowane zadania generują koszty również podczas bezczynności użytkownika, ponieważ wnioskowanie (inference) w backendach Kiro korzysta z planu Kiro, dlatego przed dodaniem zadań nocnych należy ustawić limity opisane w kontrola kosztów agenta AI na VPS.
Tworzenie kopii zapasowej wolumenu stanu przed każdą aktualizacją
Najpierw należy ustalić rzeczywistą nazwę wolumenu. Compose dodaje prefiks nazwy projektu do nazwanych wolumenów; domyślnie jest to nazwa katalogu, więc wolumen zadeklarowany jako kirocrew-home w /opt/kirocrew/compose.yaml tworzony jest jako kirocrew_kirocrew-home:
docker volume lsPrzed skopiowaniem jakichkolwiek danych należy zatrzymać bramę. memory.db oraz memory_index.db to bazy danych SQLite, a kopiowanie bazy danych w trakcie zapisu może spowodować przechwycenie niepełnej transakcji, co przy przywracaniu skutkuje uszkodzeniem pliku. Instrukcje migracji projektu wskazują na to samo: przenoszenie danych z pamięci powinno odbywać się wyłącznie przy zatrzymanych bramach. Ta zasada nie dotyczy tylko KiroCrew; jeśli na serwerze działa również serwer zdjęć, porównanie PhotoPrism i Immich zawiera dokładne polecenia kopii zapasowej wymagane dla każdej z tych usług.
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 kirocrewSkopiuj archiwum poza serwer. Przywracanie danych odbywa się za pomocą tego samego polecenia przy zatrzymanym kontenerze, z użyciem tar xzf zamiast 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 kirocrewPrzenoszenie na nowy host to zadanie inne niż przywracanie danych w tej samej lokalizacji, a dokumentacja projektu precyzuje ten proces. Historia czatów i notatki projektowe w workspace/memory/ są przenoszone, podobnie jak dwa pliki baz danych oraz config.json. Pliki PID, dziennik zdarzeń bezpieczeństwa oraz .env są powiązane ze starym hostem, dlatego należy je pominąć, a na nowym serwerze ponownie wprowadzić sekrety.
Jak wycofać nieudaną aktualizację
Aktualizacja jest krótka i bezpieczna tylko dzięki przypięciu wersji. Najpierw wykonaj kopię zapasową, a następnie zmień tag:
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 pobiera obraz, jeśli nie znajduje się on jeszcze na maszynie, więc edycja tagu stanowi całą procedurę aktualizacji. Wycofanie zmian przebiega w tej samej sekwencji z użyciem starego numeru wersji i przywraca dokładnie ten sam obraz, który był używany wcześniej, ponieważ tagi wersji są niezmienne.
Plik binarny wycofuje się bez problemów. Stan aplikacji jest elementem, który może sprawiać trudności. Nowsza wersja gateway może nadpisać config.json lub zmigrować bazy danych w pamięci do formatu, którego starsza wersja gateway nie odczyta, a na dzień 12 października 2026 r. nie udokumentowano ścieżki downgrade'u dla stanu. Instrukcja instalacji jasno określa jeden przypadek: dane przeniesione z katalogu domowego legacy ~/.kirocrew nie podlegają wycofaniu, a wydanie starsze niż ~/.kiro/crew uruchomi się jako puste. Jeśli więc starszy obraz uruchomi się, ale zachowuje się w sposób nieoczekiwany, nie należy go debugować. Należy go zatrzymać, przywrócić kopię zapasową wykonaną przed aktualizacją i rozpocząć proces od nowa. To jedyny powód, dla którego kopia zapasowa jest priorytetem, i dlatego nawyk aktualizowania teraz, a tworzenia kopii później, zawodzi w tak młodym projekcie.
Czego niniejszy dokument nie gwarantuje
Należy zachować przejrzystość w kwestii wieku tego oprogramowania. Wersja 0.1.3 została wydana 5 sierpnia 2026 roku, a do 12 października 2026 roku stabilna linia osiągnęła wersję 0.8.0. Większość informacji o wydaniach to wciąż zautomatyzowane dzienniki zmian; notatki 0.8.0 są pisane ręcznie, lecz nie zawierają sekcji dotyczącej migracji, a publiczna historia wydań obejmuje zaledwie trzy miesiące. Żaden z elementów tego przewodnika nie jest wynikiem długofalowych obserwacji, dlatego kwestie takie jak przyrost zużycia pamięci, rozmiar bazy danych czy niezawodność harmonogramu zadań należy traktować jako parametry wymagające samodzielnego pomiaru na własnej infrastrukturze, a nie jako założenia.
Dwa zachowania wymagają samodzielnego przetestowania przed poleganiem na nich w środowisku produkcyjnym. Po pierwsze, należy sprawdzić, czy procedura przywrócenia starszej wersji (downgrade) poprawnie odczytuje stan zapisany przez nowszą wersję: należy to wykonać na kopii wolumenu w bezpiecznych warunkach, a nie podczas awarii. Po drugie, należy zweryfikować, jak brama (gateway) reaguje w sytuacji, gdy sesja logowania Kiro wygasa w momencie planowanego uruchomienia zadania. Oba przypadki stanowią typowe niedociągnięcia, które w młodych projektach są sukcesywnie eliminowane między wydaniami, a ich weryfikacja na obecnym etapie jest mało kosztowna.
FAQ
Dlaczego pulpit nawigacyjny KiroCrew nie otwiera się pod publicznym adresem IP mojego serwera?
Ponieważ opublikowany przykład wiąże port z interfejsem pętli zwrotnej (loopback). -p 127.0.0.1:5476:5476 mapuje port kontenera wyłącznie na adres loopback hosta, co jest działaniem celowym. Dostęp można uzyskać, przekierowując port przez SSH za pomocą ssh -N -L 5476:127.0.0.1:5476 you@your-server, a następnie otwierając http://localhost:5476/?token=<token> na laptopie. Usunięcie prefiksu 127.0.0.1: w celu uzyskania dostępu z zewnątrz wystawia bramę na publiczny Internet, a ufw nie będzie jej chronić, ponieważ reguły DNAT dla opublikowanych portów Docker kierują ruch przed zastosowaniem reguł ufw. Należy użyć łańcucha DOCKER-USER w Dockerze z backendem iptables lub oddzielnych podstawowych łańcuchów nftables z backendem nftables, aby filtrować opublikowane porty; pozostawienie powiązania z loopback jest prostszym rozwiązaniem.
Gdzie KiroCrew przechowuje dane i co należy archiwizować?
Wszystko znajduje się w ~/.kiro/crew, co wewnątrz obrazu kontenera odpowiada /home/kirocrew/.kiro/crew, a KIROCREW_HOME pozwala na zmianę tej lokalizacji. Należy archiwizować cały katalog lub cały wolumen Docker przy zatrzymanej bramie. memory.db oraz memory_index.db to bazy danych SQLite, więc kopia wykonana w trakcie zapisu przez bramę może być niespójna. Przy przenoszeniu na nowy host, workspace/memory/, dwa pliki baz danych oraz config.json są przenoszone, podczas gdy pliki PID, dziennik zdarzeń bezpieczeństwa oraz .env należą do starego hosta.
Czy powinienem używać tagu stable czy tagu wersji?
Należy używać tagu wersji. stable zmienia się przy każdym wydaniu, więc uruchomiona wersja może ulec zmianie przy kolejnym poleceniu pull, a sam tag nie informuje o tym, co jest uruchomione. Tagi wersji, takie jak 0.8.0, są niezmienne i właśnie to umożliwia wycofanie zmian: przywrócenie starego numeru pozwala uzyskać identyczny obraz. Na dzień 1 listopada 2026 najnowszym stabilnym wydaniem jest 0.11.1.
Dlaczego mój agent odmawia wykonywania jakichkolwiek poleceń?
Kontener sprawdza obsługę piaskownicy (sandbox) przy pierwszym uruchomieniu. Jeśli nie może odizolować podprocesów agenta, a KIROCREW_ALLOW_UNSANDBOXED=1 nie jest ustawione, odmawia ich wykonania zamiast uruchamiać je bez ograniczeń, przez co brama wygląda na sprawną, podczas gdy każde zadanie jest wstrzymane. docker logs kirocrew pokazuje decyzję dotyczącą piaskownicy z tego pierwszego uruchomienia. Ustawienie tej zmiennej sprawia, że kontener staje się jedyną barierą między agentem a hostem, więc w przypadku jej ustawienia nie należy montować niczego, czego nie przekazałoby się bezpośrednio agentowi.
Czy potrzebuję konta Kiro, aby samodzielnie hostować KiroCrew?
W przypadku backendów Kiro, tak, na dzień 1 listopada 2026. KiroCrew to wolne oprogramowanie na licencji Apache 2.0, ale wnioskowanie (inference) na tych backendach korzysta z posiadanego planu Kiro. Przypięty kontener 0.8.0 korzysta z Kiro CLI: należy uruchomić docker exec -it kirocrew kiro-cli login i zatwierdzić kod urządzenia w przeglądarce lub przekazać KIRO_API_KEY przez środowisko kontenera w celu automatyzacji. Do momentu skonfigurowania uwierzytelniania brama uruchamia się i pulpit nawigacyjny ładuje się, ale domyślny mechanizm nie ma modelu, z którym mógłby się połączyć. Od wersji 0.10.0 dostępny jest również wbudowany silnik KAS, który nie wymaga zainstalowanego kiro-cli; 0.11.0 uczyniło KAS domyślnym wyborem dla nowych instalacji bez zapisanego wyboru mechanizmu, przy jednoczesnym zachowaniu jawnych wyborów Kiro CLI. KAS używa własnego logowania Crew zamiast kiro-cli login. Przewodnik po niestandardowych backendach projektu pozwala mechanizmowi claude na wysyłanie głównych tur modelu do wybranego punktu końcowego zgodnego z Anthropic, ale logowanie kiro-cli nadal pozostaje wymagane dla funkcji specyficznych dla Kiro.