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; daarom is een VPS de juiste plek en een laptop niet. KiroCrew slaat sessiegeschiedenis, semantisch geheugen, geplande taken en de wachtrij voor goedkeuringen op de schijf op en laadt deze gegevens opnieuw wanneer het proces herstart. Dit heeft geen nut als het proces niet actief is 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 deze 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 richt zich op het operationeel houden ervan, het afschermen van het openbare internet en het vermogen om een herstel uit te voeren 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-inferentie 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. Als de kant van de agent nieuw voor u is in vergelijking met de serverkant, zal het eerst leren wat een agent-loop, de bijbehorende tools en het geheugen daadwerkelijk zijn ervoor zorgen dat de onderstaande keuzes als weloverwogen beslissingen worden gelezen in plaats van als onbegrijpelijke commando's.

Wat KiroCrew vereist 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 start 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 hiervoor te kiezen.

De status bevindt zich in ~/.kiro/crew, en de omgevingsvariabele KIROCREW_HOME verplaatst deze naar een andere locatie. De inhoud bestaat uit:

• config.json: gateway-instellingen en inloggegevens voor chatkanalen.
• .env: 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 installatiesectie.

Plan voor 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 op uw eigen systeem met du -sh ~/.kiro/crew na enkele weken, in plaats van te vertrouwen op cijfers die in de eerste maand van een project worden gepubliceerd. Dit in tegenstelling tot een runtime die elke worker een eigen container en browser geeft, waarbij het zelf hosten van OpenBot's AI-collega's ervoor zorgt dat dimensionering eerder een kwestie van RAM is dan van schijfruimte.

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 als uw andere services, waardoor een mislukte upgrade handmatig herstel vereist. De container houdt de runtime in één image en de status in één volume, waardoor een rollback neerkomt op het wijzigen van een tag en een herstart.

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

Het voorbeeld van het project zelf gebruikt de tag stable:

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 altijd naar de meest recente stabiele release, waardoor de volgende pull de versie die u draait kan wijzigen zonder dat u daarvoor kiest. De tag legt bovendien niet vast om welke versie het ging. Versie-tags zijn onveranderlijk, dus gebruik een specifieke versie. 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 nog 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 zou de container binnen ongeveer een minuut als healthy moeten 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 wijzigingen aanbrengt. Bij de eerste keer opstarten wordt het embedding-model gedownload, waardoor een trage verbinding de eerste startduur kan verlengen.

Houd het draaiende met systemd

restart: unless-stopped zorgt ervoor dat de container na een crash en na een herstart weer opkomt, zolang Docker zelf bij het opstarten wordt geladen. Een unit-bestand maakt die afhankelijkheid expliciet en geeft u één commando om de volledige stack te stoppen voor 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 staat hier omdat docker compose up -d direct terugkeert zodra de container is gestart: systemd houdt bij dat de stack actief is, niet een proces op de voorgrond. Schrijf in plaats daarvan Type=simple en systemd ziet het commando direct afsluiten, markeert de service als dood en geeft het op of komt in een herstart-loop terecht, afhankelijk van uw Restart=-instelling. Voor een native installatie levert het project zijn eigen equivalent, kirocrew service install, dat /etc/systemd/system/kirocrew.service schrijft en de gateway als uw gebruiker uitvoert. Voer niet beide units tegelijk uit. De uitgebreidere versie van dit onderwerp vindt u in systemd-services en timers op een VPS. Een unit die niet terugkeert blijft stil tenzij u deze laat spreken, dus voeg een OnFailure=-handler toe die een melding naar uw eigen ntfy-server pusht en u hoort vanaf uw telefoon dat de gateway offline is, in plaats van dat u erachter komt via een geplande taak die nooit is uitgevoerd.

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 apparaatcode 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 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:-prefix en de gateway staat op het publieke internet voor iedereen die die poort scant. Een firewall-regel 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.

Forward de poort in plaats daarvan vanaf uw laptop via SSH:

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 forward automatisch te maken 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, wijzig dan alleen het getal aan de linkerkant: ssh -N -L 45476:127.0.0.1:5476 you@your-server.example.com, en navigeer vervolgens naar http://localhost:45476/?token=.... U zult forwards op deze manier stapelen zodra een tweede agent de server deelt, omdat self-hosting open-kritt voor security scanning een ander dashboard dat alleen via loopback bereikbaar is op dezelfde server plaatst, op poort 5173.

Eén gedocumenteerd gedrag dat u kunt verwachten via een tunnel: de gateway leest geforwarde verzoeken als extern, waardoor config-write en secret-reveal endpoints in het dashboard deze weigeren. Een instellingswijziging die niet opslaat via SSH is dit, 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 vanaf een telefoon verwijst het project naar Tailscale's tailscale serve. Daarmee blijft het dashboard binnen uw eigen tailnet en wordt het niet via een openbare hostnaam beschikbaar gemaakt. Geef hier de voorkeur aan boven een openbare reverse proxy. Het token staat in de URL. Die URL wordt vastgelegd in elk toegangslogboek dat het verzoek onderweg verwerkt.

Deze regel gaat over wat zich achter de poort bevindt, niet over de poort zelf. Iets zoals Halcyon, dat een Jellyfin-bibliotheek opnieuw opbouwt als een doorzoekbare videotheek in de stijl van de jaren 90 is bedoeld om door andere mensen te worden geopend en is daarom een geschikte kandidaat voor een reverse proxy. Een gateway waarmee opdrachten op uw server kunnen worden uitgevoerd, is dat niet.

Beperk de blast radius van de agent tot het minimum

De container controleert bij de eerste start op ondersteuning voor sandboxing; het resultaat hiervan 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 op dit probleem. De beslissing wordt vastgelegd 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 instelt, wees u dan bewust van de gevolgen: de container is nu de enige grens tussen de agent en uw server. De waarschuwing van het project is het volledig herhalen waard. Koppel geen host-paden die u niet rechtstreeks 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 elke vlag in dit compose-bestand, 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 niet-vertrouwde input. Daarom is pointing it at your own SearXNG instance zowel een beslissing over prompt injection als over de technische inrichting. Geplande taken kosten ook geld terwijl u slaapt, aangezien inferentie wordt gefactureerd op uw Kiro-plan. 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

Bepaal eerst de werkelijke volumenaam. Compose voegt de projectnaam toe als voorvoegsel aan volumes; de projectnaam is standaard de mapnaam. Een 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 eigen migratie-instructies van het project vermelden hetzelfde: verplaats gegevens alleen terwijl de gateways zijn gestopt. Deze regel geldt niet alleen voor KiroCrew; als er ook een fotoserver op de machine draait, biedt de vergelijking tussen PhotoPrism en Immich de exacte back-upcommando's die voor beide nodig zijn.

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. 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 machine.

Hoe voert u een rollback uit na een mislukte upgrade

Een upgrade is kort en is alleen veilig omdat u een versie heeft vastgezet (pinned). 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 version tags onveranderlijk zijn.

De binary voert een schone rollback uit. De status is het onderdeel dat dit mogelijk niet doet. Een nieuwere gateway kan config.json herschrijven of de 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 als eerste 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 bewezen is

Wees eerlijk over de ouderdom van deze software. Versie 0.1.3 is ten tijde van het schrijven enkele dagen oud; de release notes bestaan uit geautomatiseerde changelog-links in plaats van migratie-instructies en er is nog geen ervaring met 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 dit geen gevolgen heeft, 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 onvolkomenheden die bij een jong project stilletjes tussen releases door worden weggewerkt, 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 door te sturen via SSH 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 met KIROCREW_HOME kunt u dit verplaatsen. Maak een back-up van de volledige map of het gehele 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 telkens wanneer een nieuwe versie wordt uitgebracht. Hierdoor kan de versie die u draait ongemerkt veranderen bij de volgende pull, en de tag zelf geeft geen informatie over de actieve versie. Versietags zoals 0.1.3 zijn onveranderlijk, en dat is precies wat een rollback mogelijk maakt: u plaatst het oude versienummer terug en krijgt exact dezelfde image. 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 hij deze uit te voeren in plaats van ze zonder beperkingen 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, waarvoor een eenmalige aanmelding vereist is. 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.