Jak hostować KiroCrew na VPS: instrukcja konfiguracji

Dlaczego warto hostować KiroCrew na VPS zamiast na laptopie

Samodzielne hostowanie KiroCrew ma sens tylko na maszynie, która nigdy nie przechodzi w stan uśpienia, dlatego VPS jest odpowiednim ś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. Mechanizmy te nie zadziałają, jeśli proces nie będzie uruchomiony o godzinie 03:00, gdy przypada termin wykonania zadania, a zamknięty laptop nie zapewnia ciągłości działania.

KiroCrew to otwartoźródłowe środowisko pracy dla agentów od zespołu Kiro, udostępnione na licencji Apache 2.0, którego pierwsze publiczne wydania pojawiły się na początku sierpnia 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, za pomocą kirocrew CLI lub poprzez kanał komunikacyjny, taki jak Slack. Gateway jest jedynym komponentem hostowanym samodzielnie, dlatego niniejszy przewodnik skupia się na zapewnieniu jego ciągłej dostępności, izolacji od publicznego internetu oraz możliwości przywrócenia systemu po nieudanej aktualizacji.

Przed rozpoczęciem należy zwrócić uwagę na dwie kwestie. KiroCrew obsługuje kiro-cli, co wymaga jednorazowego zalogowania się na konto Kiro, a wnioskowanie agenta jest rozliczane zgodnie z planem Kiro, więc według stanu na sierpień 2026 roku nie jest to konfiguracja działająca w trybie offline. Projekt jest również na bardzo wczesnym etapie rozwoju. Należy założyć konieczność przywrócenia poprzedniej wersji w przyszłości i przeprowadzić instalację w sposób to umożliwiający. Jeśli użytkownik nie uruchamiał wcześniej agenta na serwerze, uruchamianie agenta programistycznego na VPS zawiera podstawowe zasady, na których opiera się ten przewodnik.

Czego wymaga KiroCrew i gdzie przechowywany jest jego stan

Instalacja natywna wymaga środowiska Python 3.10 lub nowszego (projekt zaleca 3.12), Node.js 18 lub nowszego w przypadku budowania panelu sterowania ze źródeł oraz kiro-cli, który jest instalowany i konfigurowany automatycznie przy pierwszym uruchomieniu. Instalacja kontenerowa nie wymaga żadnego z powyższych na hoście. Wymagany jest jedynie Docker. Jest to główny powód, dla którego warto wybrać tę metodę.

Stan przechowywany jest w ~/.kiro/crew, a zmienna środowiskowa KIROCREW_HOME pozwala na zmianę tej lokalizacji. Zawartość katalogu:

• config.json: ustawienia bramy oraz dane uwierzytelniające kanałów czatu.
• .env: sekrety.
• workspace/memory/: preferencje, notatki projektowe oraz historia czatu.
• memory.db oraz memory_index.db: indeksy semantyczne oraz pełnotekstowe.
• models/: model osadzeń (embedding model), pobierany przy pierwszym uruchomieniu.
• gateway.log oraz security_events.jsonl: dziennik uruchomieniowy oraz dziennik zdarzeń bezpieczeństwa.

Ten katalog stanowi całą instalację. Skopiowanie go na nowy serwer VPS przenosi agenta, dlatego sekcja dotycząca kopii zapasowych jest ważniejsza niż sekcja instalacji.

Należy planować zasoby dyskowe, a nie pamięć RAM. Brama jest procesem języka Python; obciążenie serwera zależy od tego, co uruchamia agent, na przykład procesu budowania lub zestawu testów. Katalog stanu powiększa się wraz z historią czatu, a model osadzeń jest pobierany przy pierwszym uruchomieniu, dlatego po kilku tygodniach warto sprawdzić zajętość za pomocą du -sh ~/.kiro/crew na własnej maszynie, zamiast polegać na danych publikowanych w pierwszym miesiącu istnienia projektu.

Którą z trzech ścieżek instalacji wybrać

Projekt udostępnia trzy warianty. Instalator jednowierszowy pobiera wheel i umieszcza kirocrew w zmiennej PATH:

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

Przyjmuje on 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.1.3

Obraz 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żywać kontenera. Instalacja natywna umieszcza pakiety Python, Node oraz kiro-cli na tym samym hoście, na którym działają inne usługi, więc nieudana aktualizacja wymusza ręczne usuwanie skutków awarii. Kontener utrzymuje ś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:stable

stable to tag zmienny. Wskazuje on zawsze na najnowsze stabilne wydanie, więc kolejne pobranie może zmienić uruchomioną wersję bez Twojej decyzji, a tag nie rejestruje informacji o tym, która to była wersja. Tagi wersji są niezmienne, więc przypnij konkretny z nich. Najnowszym wydaniem na dzień 6 sierpnia 2026 jest 0.1.3, opublikowane 5 sierpnia 2026. Istnieje również tag nightly, co w przypadku tak młodego projektu oznacza, że kod zmienił się dziś rano.

Zapisz /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:

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/health

docker 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 dokonaniem jakichkolwiek zmian. Pierwsze uruchomienie pobiera model osadzeń (embedding model), więc wolne łącze wydłuża czas pierwszego startu.

Utrzymanie ciągłości działania za pomocą systemd

restart: unless-stopped przywraca kontener po awarii oraz po restarcie systemu, o ile sam Docker uruchamia się podczas startu. Plik jednostki (unit file) czyni tę zależność jawną i zapewnia jedno polecenie zatrzymujące cały stos przed wykonaniem kopii zapasowej. Uruchamianie stosu Docker Compose podczas startu systemu omawia ogólny schemat. Oto postać tego rozwiązania według KiroCrew 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.target

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

systemctl status kirocrew powinno wskazywać active (exited), co jest prawidłowym stanem dla tej jednostki. Type=oneshot wraz z RemainAfterExit=yes znajduje się tutaj, 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. Zastosowanie Type=simple spowoduje, że systemd odnotuje natychmiastowe zakończenie polecenia, oznaczy usługę jako nieaktywną, a następnie albo zrezygnuje, albo 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ę (gateway) na prawach 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.

Pierwsze uruchomienie: logowanie i uzyskanie tokena panelu

Kontener uruchamia bramę, ale środowisko uruchomieniowe agenta nie jest jeszcze zalogowane. Należy zalogować się wewnątrz kontenera:

docker exec -it kirocrew kiro-cli login

Polecenie to wyświetli kod urządzenia oraz adres URL, który należy otworzyć w przeglądarce. Następnie należy wygenerować token panelu:

docker exec kirocrew kirocrew token --ttl 2h

Adres URL panelu to http://localhost:5476/?token=<the token>. Tokeny wygasają: sesje domyślnie trwają jedną godzinę, a udokumentowane maksimum wynosi dwadzieścia godzin. Jeśli panel ładuje się jako pusty lub następuje natychmiastowe wylogowanie, zazwyczaj oznacza to wygaśnięcie tokena; należy wówczas wygenerować nowy. Nigdy nie należy wklejać tokena do zgłoszeń serwisowych ani wiadomości na czacie, ponieważ osoba posiadająca token przejmuje kontrolę nad agentem.

Dostęp do panelu przez SSH i unikanie publikacji 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 hosta. Usunięcie prefiksu 127.0.0.1: sprawi, że brama stanie się dostępna z publicznego Internetu dla każdego, kto przeskanuje ten port. Reguła zapory sieciowej również nie zapewni ochrony: Docker publikuje porty poprzez tworzenie reguł DNAT, które są przetwarzane przed filtrowaniem ufw, dlatego ufw deny 5476 nie ma wpływu na opublikowany port. Artykuł Docker ports bypassing ufw szczegółowo opisuje ten mechanizm.

Zamiast tego należy przekierować port przez SSH z poziomu laptopa:

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

Proces 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 do ~/.ssh/config:

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

Jeśli port 5476 jest już zajęty na laptopie, należy zmienić wyłącznie 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=....

Należy uwzględnić udokumentowane zachowanie podczas korzystania z tunelu: brama interpretuje przekierowane żądania jako zdalne, przez co punkty końcowe służące do zapisu konfiguracji oraz ujawniania sekretów w panelu odrzucają je. Brak możliwości zapisania ustawień przez SSH jest zamierzonym działaniem, a nie błędem. 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 kirocrew

W 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 pod publiczną nazwą hosta. Jest to rozwiązanie preferowane względem publicznego reverse proxy. Token jest przesyłany w adresie URL, a adres URL jest zapisywany w każdym dzienniku dostępu na ścieżce żądania.

Zapewnienie agentowi najmniejszego możliwego obszaru rażenia

Kontener sprawdza obsługę piaskownicy (sandbox) przy pierwszym uruchomieniu, a wynik decyduje o tym, czy agenci mogą cokolwiek wykonać. Jeśli izolacja przestrzeni nazw (namespace isolation) jest dostępna, podprocesy agenta działają w izolacji. Jeśli nie jest ona dostępna, a zmienna KIROCREW_ALLOW_UNSANDBOXED=1 nie została ustawiona, wykonanie jest odrzucane zamiast uruchamiania bez ograniczeń. Z tego powodu brama, która wygląda na sprawną, podczas gdy każde zadanie zawiesza się, zazwyczaj wskazuje na ten problem. Decyzja jest zapisana w docker logs kirocrew od czasu tego pierwszego uruchomienia. Projekt publikuje 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.json

Jeśli ustawisz KIROCREW_ALLOW_UNSANDBOXED=1, miej świadomość tego, co się zmieniło: kontener jest teraz jedyną barierą między agentem a serwerem. Ostrzeżenie projektu warto powtórzyć w całości. Nie montuj ścieżek hosta, których nie przekazałbyś bezpośrednio agentowi. W praktyce wyklucza to gniazdo Docker, dowolne montowanie typu bind dla / oraz każdy katalog przechowujący dane innej usługi.

Reszta to ramy, które dotyczą każdego agenta uprawnionego do uruchamiania poleceń. Ogranicz jego poświadczenia do jednego repozytorium lub jednego zasobnika (bucket), którego potrzebuje; nigdy nie używaj osobistego tokena z uprawnieniami do całego konta. Uruchamiaj go jako dedykowanego użytkownika, którego katalog domowy nie zawiera niczego innego, do czego służy użytkownik z minimalnymi uprawnieniami na VPS. Gdy agent pisze kod, a następnie go uruchamia, daj mu maszynę, którą może zepsuć: jednorazowa maszyna wirtualna dla agentów programistycznych stanowi silniejszą barierę niż jakakolwiek flaga w tym pliku compose, ponieważ usuwasz ją zamiast czyścić. To samo rozumowanie kształtuje bezpieczne uruchamianie OpenClaw na VPS oraz samodzielne hostowanie agenta Hermes na VPS. Narzędzia również liczą się jako obszar rażenia: umożliwienie agentowi wyszukiwania w sieci sprawia, że każda pobrana przez niego strona staje się niezaufanym danymi wejściowymi, więc skierowanie go na własną instancję SearXNG jest decyzją dotyczącą zarówno bezpieczeństwa (prompt injection), jak i infrastruktury. Zaplanowana praca generuje również koszty podczas snu, ponieważ wnioskowanie (inference) jest rozliczane w ramach planu Kiro, więc ustaw limity opisane w kontrolowanie kosztów agenta AI na VPS przed dodaniem nocnego zadania.

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 przyjmując nazwę katalogu, więc wolumen zadeklarowany jako kirocrew-home w /opt/kirocrew/compose.yaml jest tworzony jako kirocrew_kirocrew-home:

docker volume ls

Przed kopiowaniem 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 zawierają to samo zalecenie: przenosić dane należy wyłącznie przy zatrzymanych bramach.

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

Skopiuj archiwum poza serwer. Przywracanie odbywa się za pomocą tego samego polecenia przy zatrzymanym kontenerze i z zamienionymi miejscami tar xzf oraz 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

Przenoszenie na nowy host to zadanie inne niż przywracanie w tym samym miejscu, 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/health

docker compose up -d pobiera obraz, jeśli nie znajduje się on jeszcze na serwerze, więc edycja tagu stanowi całą procedurę aktualizacji. Wycofanie zmian przebiega w tej samej kolejności przy użyciu starego numeru wersji, co 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 może jednak sprawiać trudności. Nowsza wersja gateway może nadpisać config.json lub zmigrować bazy danych w pamięci do formatu, którego starsza wersja nie odczyta, a na sierpień 2026 r. nie udokumentowano żadnej ścieżki downgrade'u. Jeśli więc starszy obraz uruchamia się, ale działa nieprawidłowo, nie należy przeprowadzać debugowania. Należy go zatrzymać, przywrócić kopię zapasową wykonaną przed aktualizacją i rozpocząć proces od nowa. To właśnie dlatego kopia zapasowa jest priorytetem i dlatego nawyk aktualizowania przed wykonaniem kopii zapasowej zawodzi w tak wczesnym projekcie.

Czego niniejszy przewodnik nie gwarantuje

Należy zachować ostrożność w ocenie dojrzałości tego oprogramowania. Wersja 0.1.3 w momencie pisania tekstu ma zaledwie kilka dni, jej informacje o wydaniu to automatycznie generowane listy zmian, a nie instrukcje migracji, i nie ma jeszcze żadnych danych dotyczących długoterminowych aktualizacji. Żaden z elementów tego przewodnika nie opiera się na długofalowych obserwacjach, dlatego kwestie takie jak zużycie pamięci, rozmiar bazy danych czy niezawodność harmonogramu zadań należy monitorować we własnym zakresie, zamiast zakładać ich stabilność.

Warto samodzielnie przetestować dwa zachowania przed uzależnieniem od nich działania systemu. Po pierwsze, należy sprawdzić, czy downgrade pozwala na odczyt stanu zapisanego przez nowszą wersję: należy to wykonać na kopii wolumenu w bezpiecznych warunkach, a nie podczas awarii. Po drugie, należy zweryfikować, jak gateway reaguje na wygaśnięcie sesji Kiro w momencie, gdy przypada termin zaplanowanego zadania. Obie te kwestie to 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 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 komputerze lokalnym. Usunięcie prefiksu 127.0.0.1: w celu udostępnienia usługi sprawi, że bramka znajdzie się w publicznym Internecie, a reguła zapory sieciowej jej nie zabezpieczy, ponieważ reguły DNAT dla opublikowanych portów Docker są przetwarzane przed filtrowaniem ruchu przez ufw.

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 bramce. memory.db oraz memory_index.db to bazy danych SQLite, więc kopia wykonana w trakcie zapisu przez bramkę może być niespójna. Przy przenoszeniu na nowy host należy przenieść workspace/memory/, oba pliki baz danych oraz config.json, natomiast pliki PID, dziennik zdarzeń bezpieczeństwa oraz .env są przypisane do starego hosta.

Czy należy 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 pobraniu, a sam tag nie informuje o tym, co jest aktualnie uruchomione. Tagi wersji, takie jak 0.1.3, są niezmienne i właśnie to umożliwia przywrócenie poprzedniej wersji: wystarczy przywrócić stary numer, aby uzyskać identyczny obraz. Według stanu na 6 sierpnia 2026 najnowszym wydaniem jest 0.1.3.

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ń. Dzięki temu bramka wygląda na sprawną, podczas gdy każde zadanie utyka. docker logs kirocrew pokazuje decyzję dotyczącą piaskownicy podjętą podczas 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 do samodzielnego hostowania KiroCrew potrzebne jest konto Kiro?

Tak, według stanu na sierpień 2026. KiroCrew to wolne oprogramowanie na licencji Apache 2.0, ale obsługuje ono kiro-cli, co wymaga jednorazowego zalogowania, a wnioskowanie agenta jest rozliczane w ramach planu Kiro. W kontenerze należy uruchomić docker exec -it kirocrew kiro-cli login i zatwierdzić kod urządzenia w przeglądarce. Do momentu zakończenia logowania bramka uruchamia się, a pulpit nawigacyjny ładuje, jednak agent nie ma modelu, z którym mógłby się komunikować.