Auto-héberger KiroCrew sur un VPS en continu

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

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 ordinateur portable. KiroCrew conserve l’historique des sessions, la mémoire sémantique, les tâches planifiées et la file d’approbation sur le disque. Il recharge toutes ces données lorsque le processus redémarre. Rien de tout cela ne sert si le processus n’est pas en cours d’exécution à 03:00, au moment où une tâche planifiée doit s’exécuter. Or un ordinateur portable fermé ne fait pas fonctionner le processus.

KiroCrew est un workspace d’agent open source développé par l’équipe Kiro et distribué sous licence Apache 2.0. Ses premières versions publiques sont sorties début août 2026. Un seul processus, appelé gateway, gère l’état et fournit un dashboard web sur le port 5476. Vous accédez à cette gateway depuis le dashboard, depuis l’interface en ligne de commande kirocrew ou depuis un canal de discussion tel que Slack. La gateway est le seul composant que vous auto-hébergez. Ce guide explique donc comment la maintenir en fonctionnement, la garder hors de l’Internet public et la 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 authentification unique avec un compte Kiro. L’inférence de l’agent est facturée sur un forfait Kiro. En août 2026, cette configuration ne fonctionne donc pas hors ligne. Le projet n’a également que quelques semaines. Partez du principe que vous devrez effectuer un rollback à un moment donné et installez-le de manière à le permettre. 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 sur lesquelles s’appuie ce guide.

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 démarrage installe et configure automatiquement avec une session ouverte. 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 privilégier.

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

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

Cette arborescence est l’installation. Copiez-la sur un nouveau VPS pour déplacer votre agent. C’est pourquoi la section sur les sauvegardes ci-dessous est plus importante que celle consacrée à l’installation.

Prévoyez suffisamment d’espace disque plutôt que de RAM. La gateway est un processus Python. Ce qui charge réellement la machine, c’est ce que l’agent exécute : un build ou une suite de tests. Le répertoire d’état grossit avec l’historique des discussions. 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 au cours du premier mois d’un projet.

Quelle méthode d’installation devez-vous utiliser

Le projet en publie trois. L’installateur en une ligne récupère un wheel et ajoute kirocrew à 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 sur ghcr.io/kirodotdev/kirocrew, pour linux/amd64 et linux/arm64 avec 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 cet environnement en état manuellement. Le conteneur conserve le runtime dans une image et l’état dans un volume. Pour revenir en arrière, il suffit donc de changer le tag et de redémarrer.

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

L’exemple du projet utilise lui-même 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 release stable la plus récente. Le prochain pull peut donc modifier la version exécutée sans que vous l’ayez choisi. Le tag n’indique alors pas la version utilisée. Les tags de version sont immuables : utilisez-en un. La release la plus récente 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 conteneur, 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’environ une minute. /api/health répond sans token, tout comme /api/live et /api/ready. C’est 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 rallonge donc le premier démarrage.

Gardez le service actif avec systemd

restart: unless-stopped relance le conteneur après un crash et après un redémarrage, à condition que Docker soit lui-même lancé au démarrage. Un fichier d’unité rend cette dépendance explicite et fournit une commande unique pour arrêter toute la stack avant une sauvegarde. Lancer une stack Docker Compose au démarrage présente le schéma général. Voici la configuration utilisée par 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. 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 l’état de la stack, et non celui d’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 version plus générale de ce sujet est présentée dans Services et timers systemd sur un VPS.

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

Le conteneur démarre la gateway, mais le runtime de l’agent n’est pas encore connecté. Connectez-vous depuis 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 jeton de dashboard :

docker exec kirocrew kirocrew token --ttl 2h

L’URL du dashboard est http://localhost:5476/?token=<the token>. Les jetons 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 directement vers la page de connexion, le jeton a généralement expiré. Générez-en un nouveau. Ne collez jamais un jeton dans un ticket ou un message de chat : toute personne qui le détient contrôle votre agent.

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

Consultez à 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 port, mais ce mapping ne publie le port que 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 firewall 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 ne fait rien pour un port publié. Les ports Docker contournent ufw décrit ce mécanisme.

Transférez le port via SSH depuis votre laptop :

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

Laissez cette commande active et ouvrez http://localhost:5476/?token=<the token> en local. Pour établir automatiquement le forward à 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 laptop, modifiez uniquement le nombre de gauche : ssh -N -L 45476:127.0.0.1:5476 you@your-server.example.com, puis ouvrez http://localhost:45476/?token=... dans votre navigateur.

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 la 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, ce n’est 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 un accès depuis un téléphone, le projet recommande tailscale serve de Tailscale. Celui-ci maintient le tableau de bord dans votre propre tailnet au lieu de l’exposer sur un hostname public. Préférez cette solution à un reverse proxy public. Le token est inclus dans l’URL, et une URL est écrite dans chaque access log du chemin.

Réduisez autant que possible la portée d’une compromission de l’agent

Le conteneur vérifie la prise en charge du sandbox lors de son premier démarrage. Le résultat détermine si les agents peuvent exécuter quoi que ce soit. Si l’isolation par namespaces est disponible, les sous-processus des agents 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 applicable à 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 l’objectif de utilisateurs avec le principe du moindre privilège sur un VPS. Lorsque l’agent écrit du code puis l’exécute, donnez-lui une machine qu’il peut rendre inutilisable : une VM jetable pour les agents de codage 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 raisonnement s’applique à exécuter OpenClaw en toute sécurité sur un VPS et à auto-héberger l’agent Hermes sur un VPS. Les tâches planifiées consomment également de l’argent pendant votre sommeil, car l’inférence est facturée sur votre forfait Kiro. Définissez donc les limites décrites dans contrôler le 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

Commencez par trouver 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 gateway 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 gateways sont arrêtées.

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 hors du serveur. 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

La migration vers un nouvel hôte est une opération différente d’une restauration sur place, et le projet précise la procédure. L’historique des conversations et les notes du projet sous workspace/memory/ sont conservés, tout comme 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 donc pas et saisissez de nouveau les secrets sur le nouveau serveur.

Comment revenir à une version précédente après une mauvaise mise à niveau

La mise à niveau est rapide et elle n’est sûre que parce que vous avez figé une version. Commencez par créer 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 télécharge l’image si elle ne se trouve pas déjà sur le serveur. La modification du tag constitue donc toute la mise à niveau. Pour revenir à la version précédente, utilisez 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 correctement à la version précédente. L’état, lui, 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 downgrade n’est documentée. Si l’ancienne image démarre puis se comporte de manière anormale, ne cherchez pas à diagnostiquer le problème. Arrêtez-la, restaurez la sauvegarde créée avant la mise à niveau, puis recommencez. C’est précisément pour cela que la sauvegarde doit être créé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’ancienneté 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 de retour d’expérience sur les 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 comportements acquis.

Deux comportements méritent d’être testés vous-même avant que vous ne comptiez dessus. Vérifiez d’abord si un downgrade peut lire un état écrit par une version plus récente. Faites-le sur une copie du volume, tant que cela n’a pas de conséquence, et non pendant une interruption de service. Vérifiez ensuite ce que fait la gateway lorsque la session Kiro expire alors qu’un job planifié doit s’exécuter. Ce sont deux problèmes typiques qu’un projet récent corrige discrètement entre deux releases. Ils sont faciles à vérifier 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 sur l’adresse loopback de l’hôte, et ce comportement est volontaire. 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 place la gateway sur Internet, et une règle de pare-feu ne suffit pas à le contenir, car les règles DNAT des ports publiés par Docker 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 déplacer cet emplacement. Sauvegardez le répertoire entier, ou le volume Docker entier, après avoir arrêté la gateway. memory.db et memory_index.db sont des bases de données SQLite : une copie effectuée pendant que la gateway écrit peut ê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 nouvelle release, si bien que la version exécutée peut changer lors du prochain pull, sans que le tag indique ce qui est réellement 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 août 2026, la release la plus récente 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 chaque tâche reste bloquée. 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 barrière entre l’agent et l’hôte. Si vous la définissez, ne montez donc aucun élément que vous ne remettriez pas directement à l’agent.

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

Oui, en août 2026. KiroCrew est un logiciel libre sous licence Apache 2.0, mais il utilise kiro-cli, qui nécessite une authentification 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, puis validez le code de l’appareil dans votre navigateur. Tant que cette authentification n’est pas terminée, la gateway démarre et le tableau de bord se charge, mais l’agent n’a aucun modèle auquel s’adresser.