Auto-héberger KiroCrew sur un VPS, toujours disponible

Pourquoi auto-héberger KiroCrew sur un VPS plutôt que sur un laptop

L’auto-hébergement de KiroCrew n’est utile que sur une machine qui ne se met jamais en veille. Un VPS est donc adapté, contrairement à un laptop. KiroCrew conserve sur disque l’historique des sessions, la mémoire sémantique, les tâches planifiées et la file d’approbation. Il recharge ces données lorsque le processus redémarre. Elles ne servent à rien si le processus ne s’exécute pas à 03:00, au moment où une tâche planifiée doit démarrer. Un laptop fermé ne peut pas exécuter le processus.

KiroCrew est un workspace d’agent open source de l’équipe Kiro, sous licence Apache 2.0. Ses premières versions publiques sont sorties début août 2026. Un processus appelé gateway gère l’état et fournit un dashboard web sur le port 5476. Vous accédez à ce gateway depuis le dashboard, depuis la kirocrew CLI ou depuis un canal de discussion comme Slack. Le gateway est le seul composant que vous auto-hébergez. Ce guide explique donc comment le maintenir en fonctionnement, le garder hors de l’Internet public et le restaurer après une mise à niveau défectueuse.

Vous devez connaître deux points avant de commencer. KiroCrew utilise kiro-cli, qui nécessite une connexion initiale avec un compte Kiro. L’inférence de l’agent est facturée selon un forfait Kiro. En août 2026, il ne s’agit donc pas d’une configuration hors ligne. Le projet n’a également que quelques semaines. Partez du principe que vous devrez effectuer un rollback à un moment donné. Installez-le de façon à pouvoir le faire. Si vous n’avez jamais exécuté d’agent sur un serveur, la page exécuter un agent de programmation sur un VPS présente les règles de base utilisées par ce guide. Si le fonctionnement des agents vous est moins familier que l’administration des serveurs, commencez par comprendre ce que sont réellement une boucle d’agent, ses outils et sa mémoire. Les choix présentés ici vous sembleront alors fondés sur des décisions plutôt que sur des incantations.

Ce dont KiroCrew a besoin et où se trouve son état

Une installation native nécessite Python 3.10 ou une version ultérieure (le projet recommande 3.12), Node.js 18 ou une version ultérieure si vous compilez le dashboard depuis les sources, ainsi que kiro-cli, que le premier lancement installe et configure pour vous. L’installation en conteneur ne nécessite rien de tout cela sur l’hôte. Elle nécessite Docker. C’est la principale raison de la préférer.

L’état se trouve dans ~/.kiro/crew, et la variable d’environnement KIROCREW_HOME permet de le déplacer ailleurs. Ce répertoire contient notamment :

• config.json : les paramètres de la gateway et les identifiants des canaux de discussion.
• .env : les secrets.
• workspace/memory/ : les préférences, les notes de projet et l’historique des discussions.
• memory.db et memory_index.db : les index sémantique et full-text.
• models/ : le modèle d’embeddings, téléchargé au premier démarrage.
• gateway.log et security_events.jsonl : le journal d’exécution et le journal des événements de sécurité.

Ce répertoire est l’installation. Copiez-le vers un nouveau VPS pour déplacer votre agent. C’est pourquoi la section consacrée aux sauvegardes ci-dessous est plus importante que celle consacrée à l’installation.

Prévoyez de l’espace disque plutôt que de la RAM. La gateway est un processus Python ; ce qui charge réellement la machine, ce sont les tâches exécutées par l’agent, comme une compilation ou une suite de tests. Le répertoire d’état augmente avec l’historique des discussions, et le modèle d’embeddings est téléchargé au premier démarrage. Mesurez donc sa taille sur votre propre machine avec du -sh ~/.kiro/crew après quelques semaines, au lieu de vous fier à une valeur publiée durant le premier mois d’un projet. À l’inverse, dans un runtime qui fournit à chaque worker son propre conteneur et son propre navigateur, l’auto-hébergement des collègues IA d’OpenBot fait de la RAM une contrainte avant l’espace disque.

Quel chemin d’installation choisir parmi les trois

Le projet en publie trois. L’installateur en une ligne récupère un wheel et place kirocrew dans votre PATH :

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

Il accepte un flag de canal et un flag de version :

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

L’image de conteneur est publiée à l’emplacement ghcr.io/kirodotdev/kirocrew, pour linux/amd64 et linux/arm64 sous chaque tag. La compilation depuis les sources nécessite git clone et make build. Elle s’adresse aux personnes qui modifient le code, pas à celles qui l’exécutent.

Utilisez le conteneur. Une installation native place les paquets Python, Node et kiro-cli sur le même hôte que vos autres services. Une mise à niveau qui échoue vous oblige alors à remettre manuellement cet environnement en état. Le conteneur conserve le runtime dans une seule image et l’état dans un seul volume. Un rollback se résume ainsi à changer le tag et à redémarrer.

Épinglez l’image sur un tag de release, pas sur stable

L’exemple fourni par le projet utilise le 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 est un tag mobile. Il pointe vers la dernière release stable disponible. Le prochain pull peut donc modifier la version exécutée sans que vous l’ayez choisi, et le tag ne permet pas de savoir quelle version était utilisée. Les tags de version sont immuables : utilisez-en un. La dernière release au 6 August 2026 est 0.1.3, publiée le 5 August 2026. Il existe également un tag nightly. Pour un projet aussi récent, cela signifie que le code a changé ce matin.

Écrivez /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:

Démarrez-le, puis vérifiez l’endpoint de health check que l’image utilise également pour son propre HEALTHCHECK :

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

docker compose ps doit indiquer que le conteneur est healthy au bout d’une minute environ. /api/health répond sans token, tout comme /api/live et /api/ready, ce qui permet de les utiliser comme probes. Si l’état reste à starting, consultez docker logs kirocrew avant de modifier quoi que ce soit. Le premier démarrage télécharge le modèle d’embedding. Une connexion lente peut donc allonger ce premier démarrage.

Le maintenir en fonctionnement avec systemd

restart: unless-stopped relance le conteneur après un crash et après un redémarrage, à condition que Docker démarre lui-même au boot. Un fichier d’unité rend cette dépendance explicite et fournit une commande unique pour arrêter toute la stack avant une sauvegarde. Démarrer une stack Docker Compose au boot présente le schéma général. Voici la structure utilisée pour KiroCrew, dans /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 doit afficher active (exited), ce qui indique que cette unité fonctionne correctement. Utiliser Type=oneshot avec RemainAfterExit=yes est approprié ici, car docker compose up -d se termine dès que le conteneur est démarré : systemd suit le fait que la stack est active, et non un processus exécuté au premier plan. Si vous écrivez plutôt Type=simple, systemd voit la commande se terminer immédiatement, marque le service comme arrêté, puis abandonne ou entre dans une boucle de redémarrage selon le paramètre Restart=. Pour une installation native, le projet fournit son propre équivalent, kirocrew service install, qui écrit /etc/systemd/system/kirocrew.service et exécute la gateway avec votre compte utilisateur. N’exécutez pas les deux unités. La présentation plus générale de ce sujet se trouve dans Les services et timers systemd sur un VPS. Une unité qui ne redémarre pas reste silencieuse tant que vous ne lui ajoutez pas de mécanisme de notification. Ajoutez donc un gestionnaire OnFailure= qui envoie une alerte à votre propre serveur ntfy : vous saurez ainsi depuis votre téléphone que la gateway est arrêtée, au lieu de le découvrir via une tâche planifiée qui ne s’est jamais exécutée.

Première exécution : connectez-vous et obtenez un token de dashboard

Le conteneur démarre la gateway, mais le runtime de l’agent n’est pas encore connecté. Connectez-vous dans le conteneur :

docker exec -it kirocrew kiro-cli login

Cette commande affiche un code d’appareil et une URL à ouvrir dans votre propre navigateur. Générez ensuite un token de dashboard :

docker exec kirocrew kirocrew token --ttl 2h

L’URL du dashboard est http://localhost:5476/?token=<the token>. Les tokens expirent : la durée des sessions est d’une heure par défaut et la durée maximale documentée est de vingt heures. Si le dashboard s’affiche vide ou vous renvoie immédiatement vers la page de connexion, le token a généralement expiré. Générez-en un nouveau. Ne collez jamais un token dans un ticket ou un message de chat, car toute personne qui le possède contrôle votre agent.

Accédez au tableau de bord via SSH et ne publiez jamais le port 5476

Examinez à nouveau l’adresse d’écoute dans l’exemple du projet : -p 127.0.0.1:5476:5476. Dans le conteneur, la gateway écoute sur 0.0.0.0, car elle doit être accessible via le mapping de ports. En revanche, le mapping publie uniquement le port sur l’interface loopback de l’hôte. Supprimez le préfixe 127.0.0.1: et la gateway devient accessible depuis Internet à toute personne qui scanne ce port. Une règle de pare-feu ne vous protégera pas non plus : Docker publie les ports en écrivant des règles DNAT évaluées avant le filtrage d’ufw. Par conséquent, ufw deny 5476 n’a aucun effet sur un port publié. Les ports Docker contournent ufw décrit ce mécanisme.

Transférez le port via SSH depuis votre ordinateur portable :

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

Laissez cette commande s’exécuter et ouvrez http://localhost:5476/?token=<the token> en local. Pour activer automatiquement le forwarding à chaque connexion, ajoutez-le dans ~/.ssh/config :

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

Si le port 5476 est déjà utilisé sur votre ordinateur portable, modifiez uniquement le nombre à gauche : ssh -N -L 45476:127.0.0.1:5476 you@your-server.example.com, puis ouvrez http://localhost:45476/?token=... dans votre navigateur. Vous empilerez des forwardings de ce type dès qu’un deuxième agent partagera le serveur, car auto-héberger open-kritt pour l’analyse de sécurité ajoute un autre tableau de bord limité à loopback sur le même serveur, sur le port 5173.

Un comportement documenté est à prévoir avec un tunnel : la gateway considère les requêtes transférées comme distantes. Les endpoints de modification de configuration et de révélation des secrets du tableau de bord les refusent donc. Si une modification des paramètres ne peut pas être enregistrée via SSH, c’est le comportement attendu, pas un bug. Modifiez plutôt la configuration directement sur l’hôte :

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

Pour l’accès depuis un téléphone, le projet recommande tailscale serve de Tailscale, qui maintient le tableau de bord dans votre propre tailnet plutôt que sur un hostname public. Préférez cette solution à un reverse proxy public. Le token figure dans l’URL, et une URL est inscrite dans chaque journal d’accès traversé. Cette règle concerne ce qui se trouve derrière le port, et non le port lui-même : un service comme Halcyon, qui reconstruit une bibliothèque Jellyfin sous la forme d’un vidéoclub des années 90 consultable est destiné à être ouvert par d’autres personnes et constitue un bon candidat pour un reverse proxy, tandis qu’une passerelle capable d’exécuter des commandes sur votre serveur ne l’est pas.

Donnez à l’agent le périmètre d’impact le plus réduit possible

Le conteneur vérifie la prise en charge du sandbox lors du premier démarrage. Le résultat détermine si les agents peuvent exécuter des commandes. Si l’isolation des namespaces est disponible, les sous-processus de l’agent s’exécutent de manière isolée. Si elle ne l’est pas et que KIROCREW_ALLOW_UNSANDBOXED=1 n’est pas défini, l’exécution est refusée au lieu de s’effectuer sans confinement. C’est généralement la cause d’une gateway qui semble saine alors que toutes les tâches restent bloquées. La décision est enregistrée dans docker logs kirocrew lors de cette première exécution. Le projet publie également un profil seccomp (secure computing mode) que vous pouvez appliquer :

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

Si vous définissez KIROCREW_ALLOW_UNSANDBOXED=1, indiquez clairement ce qui change : le conteneur devient désormais la seule limite entre l’agent et votre serveur. L’avertissement du projet mérite d’être repris intégralement. Ne montez pas de chemins de l’hôte que vous ne remettriez pas directement à l’agent. En pratique, cela exclut le socket Docker, tout bind mount de / et tout répertoire contenant les données d’un autre service.

Le reste constitue le cadre à appliquer à chaque agent autorisé à exécuter des commandes. Limitez ses identifiants au seul dépôt ou au seul bucket dont il a besoin. N’utilisez jamais un token personnel doté de droits sur l’ensemble du compte. Exécutez-le avec un utilisateur dédié dont le répertoire personnel ne contient rien d’autre. C’est précisément l’objectif des utilisateurs disposant des privilèges minimaux sur un VPS. Lorsque l’agent écrit du code puis l’exécute, donnez-lui une machine que vous acceptez de voir compromettre : une VM éphémère pour les agents de programmation constitue une limite plus forte que n’importe quelle option de ce fichier compose, car vous pouvez la supprimer au lieu de la nettoyer. Le même principe s’applique à l’exécution sûre d’OpenClaw sur un VPS et à l’auto-hébergement de l’agent Hermes sur un VPS. Les outils font également partie du périmètre d’impact : donner à l’agent accès à la recherche Web transforme chaque page qu’il récupère en entrée non fiable. Ainsi, le diriger vers votre propre instance SearXNG relève autant de la gestion des prompt injections que de la configuration réseau. Les tâches planifiées peuvent aussi engager des dépenses pendant votre sommeil, puisque l’inférence est facturée sur votre forfait Kiro. Définissez donc les limites décrites dans le contrôle du coût d’un agent IA sur un VPS avant d’ajouter une tâche nocturne.

Sauvegardez le volume d’état avant chaque mise à niveau

Trouvez d’abord le nom réel du volume. Compose préfixe les volumes nommés avec le nom du projet, qui correspond par défaut au nom du répertoire. Le volume déclaré comme kirocrew-home dans /opt/kirocrew/compose.yaml est donc créé sous le nom kirocrew_kirocrew-home :

docker volume ls

Arrêtez la passerelle avant toute copie. memory.db et memory_index.db sont des bases de données SQLite. Copier une base pendant une écriture peut capturer une transaction partiellement écrite, qui sera restaurée sous la forme d’un fichier corrompu. Les instructions de migration du projet indiquent la même chose : déplacez la mémoire uniquement lorsque les passerelles sont arrêtées. Cette règle d’arrêt préalable ne concerne pas uniquement KiroCrew. Si un serveur photo utilise le même hôte, la comparaison entre PhotoPrism et Immich fournit les commandes de sauvegarde exactes requises par chacun.

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

Copiez l’archive sur une autre machine. La restauration utilise la même commande, avec le conteneur arrêté et tar xzf à la place de 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

Le transfert vers un nouvel hôte est différent d’une restauration sur place, et le projet précise la procédure. L’historique des discussions et les notes de projet sous workspace/memory/ sont conservés, de même que les deux fichiers de base de données et config.json. Les fichiers PID, le journal des événements de sécurité et .env sont liés à l’ancien hôte. Ne les transférez pas et saisissez de nouveau les secrets sur le nouvel hôte.

Comment revenir en arrière après une mise à niveau défectueuse

La mise à niveau est rapide et elle est sûre uniquement parce que vous avez figé une version. Commencez par effectuer la sauvegarde, puis modifiez le 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 récupère l’image si elle n’est pas déjà présente sur le serveur. La modification du tag constitue donc toute la mise à niveau. Pour revenir en arrière, appliquez la même procédure avec l’ancien numéro. Vous récupérez ainsi exactement l’image utilisée auparavant, car les tags de version sont immuables.

Le binaire revient proprement à la version précédente. L’état, en revanche, peut poser problème. Une passerelle plus récente peut réécrire config.json ou migrer les bases de données en mémoire vers un format qu’une passerelle plus ancienne ne sait pas lire. En août 2026, aucune procédure de rétrogradation n’est documentée. Si l’ancienne image démarre puis se comporte de manière inhabituelle, ne cherchez pas à diagnostiquer le problème. Arrêtez-la, restaurez la sauvegarde effectuée avant la mise à niveau, puis redémarrez. C’est précisément pour cela que la sauvegarde doit être effectuée en premier. C’est aussi pourquoi l’habitude consistant à mettre à niveau maintenant et à sauvegarder plus tard ne convient pas à un projet aussi récent.

Ce qui n’est pas démontré ici

Soyez conscient de l’âge de ce logiciel. La version 0.1.3 date de quelques jours au moment de la rédaction. Ses notes de version sont des liens automatisés vers le changelog, et non des notes de migration. Il n’existe pas encore d’historique des mises à niveau. Rien dans ce guide ne constitue un résultat à long terme. Considérez donc la croissance de la mémoire, la taille de la base de données et la fiabilité du scheduler comme des éléments à mesurer sur votre propre serveur, et non comme des caractéristiques acquises.

Deux comportements méritent d’être testés vous-même avant de leur faire confiance. Premièrement, vérifiez si un downgrade peut lire un état écrit par une version plus récente. Faites ce test sur une copie du volume, lorsqu’une erreur n’a pas de conséquence, et non pendant une panne. Deuxièmement, vérifiez le comportement de la gateway lorsque la session Kiro expire alors qu’un job planifié doit s’exécuter. Ce sont deux limites typiques qu’un projet récent corrige discrètement entre deux versions. Dans les deux cas, le test est rapide à effectuer dès maintenant.

FAQ

Pourquoi le tableau de bord KiroCrew ne s’ouvre-t-il pas sur l’adresse IP publique de mon serveur ?

Parce que l’exemple publié lie le port à loopback. -p 127.0.0.1:5476:5476 mappe le port du conteneur uniquement vers l’adresse loopback de l’hôte, de manière délibérée. Accédez-y en transférant le port via SSH avec ssh -N -L 5476:127.0.0.1:5476 you@your-server, puis ouvrez http://localhost:5476/?token=<token> sur votre ordinateur portable. Supprimer le préfixe 127.0.0.1: pour rendre le service accessible expose la gateway sur Internet, et une règle de pare-feu ne suffira pas à la contenir, car les règles DNAT de Docker pour les ports publiés sont évaluées avant que ufw ne filtre le trafic.

Où KiroCrew stocke-t-il ses données et que dois-je sauvegarder ?

Tout se trouve sous ~/.kiro/crew, qui correspond à /home/kirocrew/.kiro/crew dans l’image du conteneur, et KIROCREW_HOME permet de le déplacer. Sauvegardez l’ensemble du répertoire, ou l’intégralité du volume Docker, gateway arrêtée. memory.db et memory_index.db sont des bases SQLite : une copie effectuée pendant que la gateway écrit peut donc être incohérente. Lors d’une migration vers un nouvel hôte, workspace/memory/, les deux fichiers de base de données et config.json sont transférés, tandis que les fichiers PID, le journal des événements de sécurité et .env appartiennent à l’ancien hôte.

Dois-je utiliser le tag stable ou un tag de version ?

Utilisez un tag de version. stable change à chaque release, de sorte que la version exécutée peut changer au prochain pull, sans que le tag lui-même indique ce qui est en cours d’exécution. Les tags de version tels que 0.1.3 sont immuables. C’est précisément ce qui permet un rollback : vous remettez l’ancien numéro et récupérez une image identique. Au 6 August 2026, la dernière release est 0.1.3.

Pourquoi mon agent refuse-t-il d’exécuter des commandes ?

Le conteneur vérifie la prise en charge du sandbox lors de son premier démarrage. S’il ne peut pas isoler les sous-processus de l’agent et que KIROCREW_ALLOW_UNSANDBOXED=1 n’est pas défini, il refuse de les exécuter plutôt que de les lancer sans isolation. La gateway semble alors saine, tandis que toutes les tâches restent bloquées. docker logs kirocrew affiche la décision concernant le sandbox prise lors de cette première exécution. Définir cette variable fait du conteneur la seule limite entre l’agent et l’hôte. Si vous la définissez, ne montez donc rien que vous ne donneriez pas directement à l’agent.

Ai-je besoin d’un compte Kiro pour auto-héberger KiroCrew ?

Oui, en August 2026. KiroCrew est un logiciel libre sous licence Apache 2.0, mais il utilise kiro-cli, qui nécessite une connexion initiale unique, et l’inférence de l’agent est facturée sur un forfait Kiro. Dans le conteneur, exécutez docker exec -it kirocrew kiro-cli login et validez le code de l’appareil dans votre navigateur. Tant que cette connexion n’est pas terminée, la gateway démarre et le tableau de bord se charge, mais l’agent ne dispose d’aucun modèle auquel se connecter.