KiroCrew zelf hosten op een VPS: handleiding

Waarom KiroCrew zelf hosten op een VPS in plaats van op een laptop

Het zelf hosten van KiroCrew is alleen zinvol op een machine die nooit in de slaapstand gaat; een VPS is daarom de juiste plek en een laptop niet. KiroCrew slaat sessiegeschiedenis, semantisch geheugen, geplande taken en de goedkeuringswachtrij op schijf op en laadt dit alles opnieuw wanneer het proces herstart. Dit heeft geen nut als het proces niet draait om 03:00 uur wanneer een geplande taak moet worden uitgevoerd, en een gesloten laptop voert dit niet uit.

KiroCrew is een open-source agent-werkruimte van het Kiro-team, gelicentieerd onder Apache 2.0, waarvan de eerste publieke releases begin augustus 2026 verschenen. Eén proces, de gateway genaamd, beheert de status en serveert een webdashboard op poort 5476. U bereikt die gateway via het dashboard, via de kirocrew CLI, of via een chatkanaal zoals Slack. De gateway is het enige onderdeel dat u zelf host, dus deze handleiding gaat over het in de lucht houden ervan, het afschermen van het openbare internet en het kunnen herstellen na een mislukte upgrade.

Twee zaken om te weten voordat u begint. KiroCrew stuurt kiro-cli aan, waarvoor een eenmalige aanmelding met een Kiro-account vereist is, en agent-inference wordt gefactureerd via een Kiro-abonnement; per augustus 2026 is dit dus geen offline opstelling. Het project is bovendien pas enkele weken oud. Ga ervan uit dat u op enig moment een rollback moet uitvoeren en installeer het op een manier die dit toelaat. Als u nog niet eerder een agent op een server heeft gedraaid, behandelt het draaien van een coding agent op een VPS de basisregels waarop deze handleiding voortbouwt.

Wat KiroCrew nodig heeft en waar de status wordt opgeslagen

Een native installatie vereist Python 3.10 of nieuwer (het project adviseert 3.12), Node.js 18 of nieuwer als u het dashboard vanuit de broncode bouwt, en kiro-cli, dat bij de eerste opstart automatisch wordt geïnstalleerd en geconfigureerd. De container-installatie vereist niets van dit alles op de host. Het heeft enkel Docker nodig. Dat is de voornaamste reden om voor deze methode te kiezen.

De status wordt opgeslagen in ~/.kiro/crew, en de omgevingsvariabele KIROCREW_HOME verplaatst deze locatie indien gewenst. De inhoud bestaat uit:

• config.json: gateway-instellingen en inloggegevens voor chatkanalen.
• .env: geheimen (secrets).
• workspace/memory/: voorkeuren, projectnotities en chatgeschiedenis.
• memory.db en memory_index.db: de semantische en full-text indexen.
• models/: het embedding-model, dat bij de eerste uitvoering wordt gedownload.
• gateway.log en security_events.jsonl: het runtime-logboek en het beveiligingslogboek.

Die map is de installatie. Kopieer deze naar een nieuwe VPS en u heeft uw agent verplaatst; daarom is de sectie over back-ups hieronder belangrijker dan de sectie over de installatie.

Houd rekening met schijfruimte in plaats van RAM. De gateway is een Python-proces; wat de server daadwerkelijk belast, is wat de agent uitvoert, zoals een build of een testsuite. De statusmap groeit naarmate de chatgeschiedenis toeneemt en het embedding-model wordt bij de eerste start binnengehaald. Meet het verbruik daarom na enkele weken op uw eigen systeem met du -sh ~/.kiro/crew, in plaats van te vertrouwen op cijfers die in de eerste maand van een project worden gepubliceerd.

Welk van de drie installatiepaden moet u gebruiken

Het project publiceert er drie. Het one-line installatiescript haalt een wheel op en plaatst kirocrew op uw PATH:

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

Het script accepteert een channel-vlag en een version-vlag:

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

De container-image wordt gepubliceerd op ghcr.io/kirodotdev/kirocrew, voor linux/amd64 en linux/arm64 onder elke tag. De source build is git clone plus make build, en deze is bedoeld voor mensen die de code aanpassen, niet voor gebruikers die de software draaien.

Gebruik de container. Een native installatie plaatst Python-pakketten, Node en kiro-cli op dezelfde host die uw andere services draait, waardoor u bij een mislukte upgrade handmatig moet ingrijpen. De container houdt de runtime in één image en de status in één volume, waardoor een rollback neerkomt op een wijziging van de tag en een herstart.

Pin de image aan een release-tag, niet aan stable

Het voorbeeld van het project zelf gebruikt de stable-tag:

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

stable is een bewegende tag. Deze wijst naar de meest recente stabiele release op dat moment. Hierdoor kan de volgende pull de versie die u draait wijzigen zonder dat u daarvoor kiest, en de tag legt niet vast welke versie dat was. Versie-tags zijn onveranderlijk, dus pin er een vast. De nieuwste release op 6 augustus 2026 is 0.1.3, gepubliceerd op 5 augustus 2026. Er is ook een nightly-tag; bij een project van deze leeftijd betekent dit dat de code vanochtend is gewijzigd.

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

Start de container en controleer vervolgens het health-endpoint dat de image ook gebruikt voor zijn eigen HEALTHCHECK:

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

docker compose ps hoort de container binnen ongeveer een minuut als healthy te rapporteren, en /api/health antwoordt zonder token (net als /api/live en /api/ready, wat ze bruikbaar maakt als probes). Als de status op starting blijft staan, lees dan docker logs kirocrew voordat u iets wijzigt. De eerste run downloadt het embedding-model, waardoor een trage verbinding de eerste start lang kan laten duren.

Houd het draaiende met systemd

restart: unless-stopped zorgt ervoor dat de container na een crash en na een reboot weer opstart, mits Docker zelf bij het opstarten wordt geladen. Een unit-bestand maakt die afhankelijkheid expliciet en biedt één commando om de volledige stack te stoppen vóór een back-up. Een Docker Compose-stack starten bij het opstarten behandelt het algemene patroon. Dit is de KiroCrew-vorm ervan, in /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 hoort active (exited) te lezen, wat het gezonde resultaat is voor deze unit. Type=oneshot met RemainAfterExit=yes is hier correct omdat docker compose up -d direct terugkeert zodra de container is gestart: systemd houdt bij of de stack actief is, niet een proces op de voorgrond. Gebruik in plaats daarvan Type=simple; systemd ziet dan dat het commando direct afsluit, markeert de service als gestopt en geeft het op of blijft herstarten, afhankelijk van uw Restart=-instelling. Voor een native installatie levert het project een eigen equivalent, kirocrew service install, dat /etc/systemd/system/kirocrew.service schrijft en de gateway uitvoert als uw gebruiker. Draai niet beide units tegelijk. De uitgebreidere versie van dit onderwerp staat in systemd-services en timers op een VPS.

Eerste uitvoering: inloggen en een dashboard-token ophalen

De container start de gateway, maar de agent runtime is nog niet ingelogd. Log in binnen de container:

docker exec -it kirocrew kiro-cli login

Dit toont een device code en een URL die u in uw eigen browser opent. Genereer vervolgens een dashboard-token:

docker exec kirocrew kirocrew token --ttl 2h

De dashboard-URL is http://localhost:5476/?token=<the token>. Tokens verlopen: sessies duren standaard één uur en het gedocumenteerde maximum is twintig uur. Een dashboard dat leeg laadt of u direct terugstuurt, heeft meestal een verlopen token; genereer in dat geval een nieuwe. Plak een token nooit in een ticket of een chatbericht, omdat iedereen die het token bezit, ook uw agent beheert.

Bereik het dashboard via SSH en stel poort 5476 nooit open

Bekijk het bind-adres in het voorbeeld van het project opnieuw: -p 127.0.0.1:5476:5476. Binnen de container luistert de gateway op 0.0.0.0, omdat deze bereikbaar moet zijn via de poort-mapping, maar de mapping zelf publiceert alleen naar de loopback-interface op de host. Verwijder het 127.0.0.1:-voorvoegsel en de gateway staat op het openbare internet voor iedereen die die poort scant. Een firewallregel zal u ook niet redden: Docker publiceert poorten door DNAT-regels te schrijven die worden geëvalueerd vóór de filtering van ufw, dus ufw deny 5476 doet niets bij een gepubliceerde poort. Docker-poorten die ufw omzeilen legt dit mechanisme uit.

Stuur de poort in plaats daarvan door via SSH vanaf uw laptop:

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

Laat dit draaien en open http://localhost:5476/?token=<the token> lokaal. Om de doorsturing automatisch te laten verlopen bij elke verbinding, plaatst u deze in ~/.ssh/config:

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

Als poort 5476 al in gebruik is op uw laptop, wijzigt u alleen het getal aan de linkerzijde: ssh -N -L 45476:127.0.0.1:5476 you@your-server.example.com, en navigeert u vervolgens naar http://localhost:45476/?token=....

Eén gedocumenteerd gedrag dat u kunt verwachten via een tunnel: de gateway leest doorgestuurde verzoeken als extern, waardoor endpoints voor configuratiewijzigingen en het tonen van geheimen in het dashboard deze weigeren. Een instellingswijziging die niet wordt opgeslagen via SSH is een beveiligingsfunctie, geen bug. Bewerk de configuratie in plaats daarvan op de host:

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

Voor toegang via een telefoon verwijst het project naar tailscale serve van Tailscale, waarmee het dashboard binnen uw eigen tailnet blijft in plaats van op een openbare hostnaam. Geef de voorkeur aan deze methode boven een openbare reverse proxy. Het token reist mee in de URL, en een URL wordt in elk toegangslogboek op het pad geschreven.

Geef de agent de kleinst mogelijke blast radius

De container controleert bij de eerste start op ondersteuning voor sandboxing; het resultaat bepaalt of agents opdrachten kunnen uitvoeren. Als namespace-isolatie beschikbaar is, draaien agent-subprocessen in isolatie. Als dit niet beschikbaar is en KIROCREW_ALLOW_UNSANDBOXED=1 niet is ingesteld, wordt uitvoering geweigerd in plaats van onbeperkt uitgevoerd. Een gateway die gezond lijkt terwijl elke taak blijft hangen, wijst meestal hierop. De beslissing staat in docker logs kirocrew vanaf die eerste run. Het project publiceert ook een seccomp (secure computing mode) profiel dat u kunt toepassen:

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

Als u KIROCREW_ALLOW_UNSANDBOXED=1 wel instelt, wees u dan bewust van de wijziging: de container is nu de enige grens tussen de agent en uw server. De waarschuwing van het project is het volledig herhalen waard. Mount geen host-paden die u niet direct aan de agent zou toevertrouwen. In de praktijk sluit dit de Docker socket, elke bind mount van / en elke map met gegevens van een andere service uit.

De rest is het kader dat geldt voor elke agent die opdrachten mag uitvoeren. Beperk de credentials tot de ene repository of de ene bucket die nodig is; gebruik nooit een persoonlijk token met rechten voor het gehele account. Laat de agent draaien als een toegewezen gebruiker wiens home-map niets anders bevat, waarvoor least privilege users on a VPS is bedoeld. Wanneer de agent code schrijft en deze vervolgens uitvoert, geef hem dan een machine die hij mag beschadigen: a disposable VM for coding agents vormt een sterkere grens dan welke vlag in dit compose-bestand dan ook, omdat u de machine verwijdert in plaats van deze op te schonen. Dezelfde redenering vormt de basis voor running OpenClaw safely on a VPS en self-hosting the Hermes agent on a VPS. Tools tellen ook mee als blast radius: het geven van webzoekfunctionaliteit aan de agent maakt van elke pagina die hij ophaalt onbetrouwbare input. Daarom is pointing it at your own SearXNG instance net zozeer een beslissing over prompt injection als over de technische infrastructuur. Geplande taken kosten ook geld terwijl u slaapt, aangezien inferentie wordt gefactureerd via uw Kiro-abonnement. Stel daarom de limieten in die worden beschreven in controlling what an AI agent costs on a VPS voordat u een nachtelijke taak toevoegt.

Maak voor elke upgrade een back-up van het state-volume

Zoek eerst de werkelijke volumenaam op. Compose voorziet volumes van een voorvoegsel op basis van de projectnaam, die standaard de mapnaam is. Het volume dat als kirocrew-home in /opt/kirocrew/compose.yaml is gedeclareerd, wordt daarom aangemaakt als kirocrew_kirocrew-home:

docker volume ls

Stop de gateway voordat u bestanden kopieert. memory.db en memory_index.db zijn SQLite-databases. Het kopiëren van een database terwijl er naar geschreven wordt, kan resulteren in een onvolledige transactie, wat bij herstel leidt tot een corrupt bestand. De migratie-instructies van het project zelf vermelden hetzelfde: verplaats gegevens alleen terwijl de gateways zijn gestopt.

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

Kopieer het archief van de server af. Herstellen gebeurt met hetzelfde commando, terwijl de container is gestopt en tar xzf in plaats van tar czf wordt gebruikt:

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

Verhuizen naar een nieuwe host is een andere taak dan lokaal herstellen, en het project is hier specifiek over. De chatgeschiedenis en projectnotities onder workspace/memory/ worden overgezet, evenals de twee databasebestanden en config.json. PID-bestanden, het beveiligingslogboek en .env zijn gekoppeld aan de oude host; laat deze achter en voer de secrets opnieuw in op de nieuwe server.

Hoe voert u een rollback uit na een mislukte upgrade

Upgraden is kortstondig en alleen veilig omdat u een versie heeft vastgezet. Maak eerst de back-up en wijzig daarna de 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 haalt de image op als deze nog niet op de server staat, dus het bewerken van de tag is de volledige upgrade. Een rollback volgt dezelfde reeks met het oude nummer; dit geeft u exact de image die u daarvoor had, omdat versietags onveranderlijk zijn.

De binary rolt probleemloos terug. De status is het onderdeel dat dit mogelijk niet doet. Een nieuwere gateway kan config.json herschrijven of memory databases migreren naar een vorm die een oudere gateway niet kan lezen, en er is per augustus 2026 geen downgrade-pad gedocumenteerd. Als de oudere image dus opstart en zich vervolgens vreemd gedraagt, probeer dit dan niet te debuggen. Stop de service, herstel de back-up die u vóór de upgrade heeft gemaakt en begin opnieuw. Dat is de enige reden waarom de back-up eerst komt, en waarom de gewoonte om nu te upgraden en later een back-up te maken bij een project van deze leeftijd faalt.

Wat hier niet is bewezen

Wees eerlijk over de ouderdom van deze software. Versie 0.1.3 is ten tijde van het schrijven enkele dagen oud; de release notes zijn geautomatiseerde changelog-links in plaats van migratienotities en er is nog geen staat van dienst wat betreft upgrades. Niets in deze handleiding is gebaseerd op langetermijnresultaten. Beschouw geheugengebruik, databasegrootte en de betrouwbaarheid van de scheduler daarom als zaken die u op uw eigen systeem moet meten in plaats van als aannames.

Twee gedragingen zijn het waard om zelf te testen voordat u ervan afhankelijk wordt. Ten eerste of een downgrade de status kan lezen die door een nieuwere versie is geschreven: test dit op een kopie van de volume wanneer het niet uitmaakt, niet tijdens een storing. Ten tweede wat de gateway doet wanneer de Kiro-aanmelding verloopt terwijl er een geplande taak moet worden uitgevoerd. Beide zijn typische ruwe randjes die bij een jong project stilletjes worden weggewerkt tussen releases, en beide zijn nu eenvoudig te controleren.

FAQ

Waarom opent het KiroCrew-dashboard niet op het publieke IP-adres van mijn server?

Omdat het gepubliceerde voorbeeld de poort bindt aan de loopback-interface. -p 127.0.0.1:5476:5476 koppelt de poort van de container uitsluitend aan het loopback-adres van de host; dit is een bewuste keuze. U bereikt de interface door de poort via SSH door te sturen met ssh -N -L 5476:127.0.0.1:5476 you@your-server en vervolgens http://localhost:5476/?token=<token> op uw laptop te openen. Het verwijderen van het 127.0.0.1:-voorvoegsel om de service bereikbaar te maken, stelt de gateway bloot aan het publieke internet. Een firewallregel zal dit niet tegenhouden, omdat de DNAT-regels voor gepubliceerde Docker-poorten worden geëvalueerd voordat ufw het verkeer filtert.

Waar slaat KiroCrew zijn gegevens op en wat moet ik back-uppen?

Alles bevindt zich onder ~/.kiro/crew, wat in de container-image overeenkomt met /home/kirocrew/.kiro/crew, en KIROCREW_HOME verplaatst deze locatie. Maak een back-up van de volledige map of het volledige Docker-volume terwijl de gateway is gestopt. memory.db en memory_index.db zijn SQLite-databases; een kopie die wordt gemaakt terwijl de gateway schrijft, kan inconsistent zijn. Bij het verhuizen naar een nieuwe host verplaatst u workspace/memory/, de twee databasebestanden en config.json. PID-bestanden, het beveiligingslogboek en .env horen bij de oude host.

Moet ik de stable-tag of een versietag gebruiken?

Gebruik een versietag. stable wijzigt bij elke nieuwe release. De versie die u draait kan daardoor ongemerkt veranderen bij de volgende pull, en de tag zelf geeft geen informatie over de actieve versie. Versietags zoals 0.1.3 zijn onveranderlijk. Dit is precies wat een rollback mogelijk maakt: u voert het oude nummer in en krijgt exact dezelfde image terug. Sinds 6 augustus 2026 is de nieuwste release 0.1.3.

Waarom weigert mijn agent om opdrachten uit te voeren?

De container controleert bij de eerste start of sandbox-ondersteuning beschikbaar is. Als de container agent-subprocessen niet kan isoleren en KIROCREW_ALLOW_UNSANDBOXED=1 niet is ingesteld, weigert de container deze uit te voeren in plaats van ze zonder isolatie te draaien. Hierdoor lijkt de gateway in orde, terwijl elke taak blijft hangen. docker logs kirocrew toont de beslissing over de sandbox van die eerste run. Door de variabele in te stellen, vormt de container de enige grens tussen de agent en de host. Als u deze instelt, mount dan niets wat u niet direct aan de agent zou toevertrouwen.

Heb ik een Kiro-account nodig om KiroCrew zelf te hosten?

Ja, sinds augustus 2026. KiroCrew is vrije software onder de Apache 2.0-licentie, maar het maakt gebruik van kiro-cli. Hiervoor is een eenmalige aanmelding vereist en agent-inferentie wordt gefactureerd via een Kiro-abonnement. Voer in de container docker exec -it kirocrew kiro-cli login uit en keur de apparaatcode goed in uw browser. Totdat deze aanmelding is voltooid, start de gateway en laadt het dashboard, maar heeft de agent geen model om mee te communiceren.