Multi-instance

Exécutez Crew sur plusieurs hôtes distants — postes de développement, instances EC2, serveurs personnels — et pilotez-les tous depuis une seule passerelle hub. Multi-instance ouvre des tunnels SSH vers chaque instance distante, émet des jetons de tableau de bord de courte durée et intègre chaque tableau de bord distant dans une bande d'onglets. Les instances utilisées le plus récemment restent actives; les autres se reconnectent à la demande.

Activation volontaire. Désactivé par défaut.

kirocrew config set instances.enabled true
kirocrew restart

Une fois activée, la passerelle :

1. Crée le registre des instances + SshTunnelManager
2. Applique un assouplissement de la CSP frame-src aux ports de tunnel loopback actifs (afin que les tableaux de bord distants intégrés puissent s'afficher — ils sont sinon bloqués par le strict frame-src 'self' blob:)

Lorsque l'indicateur est désactivé, /api/instances/* renvoie 403 et la page /instances affiche une invitation à l'activation.

 ┌── Hub gateway (this host) ──┐
 │  /instances page (React)     │
 │  ├─ tab strip: Home · A · B  │
 │  ├─ warm <iframe>s per tab   │  http://127.0.0.1:<local_port>/?token=…
 │  └─ Manage panel             │  add / connect / diagnose / restart / remove
 │                              │
 │  instances/ package          │
 │  ├─ registry                 │  ~/.kiro/crew/instances.json
 │  ├─ port_allocator           │  loopback ports from base 7778
 │  ├─ token_mint               │  ssh <host> kirocrew token → JWT (never logged)
 │  ├─ ssh_tunnel_manager       │  supervised ssh -N -L, probe, self-heal, refresh
 │  └─ diagnostics              │  ssh → remote-dashboard → local-forward ladder
 └──────────────────────────────┘
         │ ssh -N -L 127.0.0.1:<local>:127.0.0.1:<remote>
         ▼
 ┌── Remote gateway ────────────┐
 │  kirocrew gateway bound to    │
 │  127.0.0.1:<remote_port>      │
 └──────────────────────────────┘

Chaque instance que vous ajoutez produit un processus enfant supervisé ssh -N -L. Le tunnel transfère 127.0.0.1:<local> → distant 127.0.0.1:<remote>. Le hub émet un jeton de tableau de bord sur l'instance distante via SSH et intègre le tableau de bord distant dans un iframe à l'URL loopback.

1. Connexion — POST /api/instances/{id}/connect alloue un port loopback, émet un jeton sur l'instance distante via SSH, démarre ssh -N -L, attend que le transfert local accepte une connexion, puis renvoie l'état en direct
2. Ensemble actif — jusqu'à warm_set_cap (5 par défaut) instances les plus récemment utilisées restent actives avec un tunnel + WebSocket en direct. Se connecter au-delà de la limite évince paresseusement la moins récemment utilisée
3. Sonde de santé — pendant la connexion, une sonde interroge le transfert loopback toutes les 30 s; après 3 échecs consécutifs, elle arrête le processus enfant pour déclencher la récupération
4. Autoréparation à 2 niveaux — en cas d'arrêt inattendu : le niveau 1 reconstruit le tunnel en réutilisant le jeton existant; le niveau 2 réémet le jeton puis reconstruit. Limité à 8 tentatives avec un délai exponentiel plafonné (fenêtre d'environ 2 min)
5. Renouvellement proactif du jeton — une boucle par instance réémet le jeton à 0,8 de sa durée de vie (TTL), avant le plafond d'environ 20 h
6. Diagnostic / redémarrage — ?diagnose=1 exécute une série de sondes de défaillance à la demande; POST .../restart redémarre la passerelle distante via SSH

Ouvrez Instances dans le tableau de bord, cliquez sur Add, puis remplissez :

Le champ ssh_host accepte :

• Un nom d'hôte ou un FQDN (dev-1.example.com)
• Un utilisateur + hôte (ec2-user@10.0.1.5)
• Un alias de configuration SSH (my-ec2)

Toute option commençant par - est rejetée (protection contre l'injection).

Le seul paramètre propre à chaque instance distante est ssh_host. Tout ce que ssh peut atteindre de manière non interactive fonctionne.

Utilisez votre alias de configuration SSH ou user@hostname. Tant qu'une clé de votre ssh-agent couvre l'authentification, BatchMode réussit sans invite.

Configurez un alias SSH dans ~/.ssh/config sur le hub, puis référencez l'alias :

Host my-ec2
  HostName ec2-1-2-3-4.compute-1.amazonaws.com
  User ec2-user
  IdentityFile ~/.ssh/my-key.pem
  # Optional: reach a private instance through a bastion
  ProxyJump bastion-host
  # Or via SSM Session Manager:
  # ProxyCommand sh -c "aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters portNumber=%p"

Ajoutez ensuite une instance avec my-ec2 comme hôte SSH.

Prérequis sur le hub :

• Une clé sans phrase de passe ou un ssh-agent la détenant (BatchMode ne demandera pas d'invite)
• kirocrew installé et une passerelle en cours d'exécution sur le port loopback de l'instance EC2

Le panneau Manage vous offre les actions suivantes par instance :

• Connect — ouvrir un tunnel + iframe
• Disconnect — fermer le tunnel
• Diagnose — exécuter la série de sondes de défaillance et signaler le premier lien rompu
• Restart — redémarrer la passerelle distante via SSH (avec prise en compte du service)
• Edit — modifier le nom / l'hôte / le port / le TTL
• Remove — déconnecter puis supprimer

Chaque route de /api/instances/* est protégée par _guard() :

• Refus par défaut — rejette les requêtes provenant de Slack (403)
• Réservé au propriétaire — exige request["user"] (session de tableau de bord authentifiée)
• Contrôlé par fonctionnalité — exige instances.enabled: true
• Audité par SEL — chaque appel (réussite et refus) émet un événement d'audit

Au-delà de la protection :

• Transferts loopback uniquement — ssh -N -L 127.0.0.1:<local>:127.0.0.1:<remote>
• Aucun shell local — ssh est toujours invoqué avec une liste argv; ssh_host ne peut pas injecter de syntaxe shell locale
• Entrées validées par jeu de caractères — ssh_host et remote_bin sont rejetés s'ils contiennent des métacaractères shell ou commencent par -
• Jetons de courte durée — ≤20 h, renvoyés uniquement en mémoire à l'appelant, jamais journalisés, jamais dans les charges utiles de liste/état
• Vérification de l'origine postMessage — le parent valide chaque event.origin de trame intégrée par rapport à l'exact http://127.0.0.1:<port> d'un tunnel actuellement actif avant de faire confiance à un message de compte de non-lus

Sous instances.* :