Multi-instance

Run Crew on several remote hosts — dev boxes, EC2 instances, home servers — and drive them all from one hub gateway. Multi-instance opens SSH tunnels to each remote, mints short-lived dashboard tokens, and embeds each remote dashboard in a tab strip. The most-recently-used instances stay warm; the rest reconnect on demand.

Opt-in. Off by default.

kirocrew config set instances.enabled true
kirocrew restart

When enabled, the gateway:

1. Creates the instances registry + SshTunnelManager
2. Scopes a CSP frame-src relaxation to the active loopback tunnel ports (so embedded remote dashboards can render — they're otherwise blocked by the strict frame-src 'self' blob:)

With the flag off, /api/instances/* returns 403 and the /instances page shows an opt-in hint.

 ┌── 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>      │
 └──────────────────────────────┘

Each instance you add produces a supervised ssh -N -L child. The tunnel forwards 127.0.0.1:<local> → remote 127.0.0.1:<remote>. The hub mints a dashboard token on the remote over SSH and embeds the remote dashboard in an iframe at the loopback URL.

1. Connect — POST /api/instances/{id}/connect allocates a loopback port, mints a token on the remote over SSH, starts ssh -N -L, waits until the local forward accepts a connection, then returns the live status
2. Warm set — up to warm_set_cap (default 5) most-recently-used instances stay warm with a live tunnel + WebSocket. Connecting beyond the cap lazily evicts the least-recently-used
3. Health probe — while connected, a probe polls the loopback forward every 30 s; after 3 consecutive failures it tears the child down so recovery fires
4. 2-tier self-heal — on unexpected exit: tier 1 rebuilds the tunnel reusing the existing token; tier 2 re-mints the token then rebuilds. Capped at 8 attempts with capped-exponential backoff (~2 min window)
5. Proactive token refresh — a per-instance loop re-mints the token at 0.8 of its TTL, ahead of the ~20h cap
6. Diagnose / restart — ?diagnose=1 runs a failure-probe ladder on demand; POST .../restart restarts the remote gateway over SSH

Open Instances in the dashboard, click Add, fill in:

The ssh_host field accepts:

• A hostname or FQDN (dev-1.example.com)
• A user + host (ec2-user@10.0.1.5)
• An SSH config alias (my-ec2)

Any option starting with - is rejected (injection guard).

The only per-remote knob is ssh_host. Anything ssh can reach non-interactively works.

Use your SSH config alias or user@hostname. As long as a key in your ssh-agent covers auth, BatchMode succeeds without prompting.

Configure an SSH alias in ~/.ssh/config on the hub, then reference the 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"

Then add an instance with my-ec2 as the SSH host.

Prerequisites on the hub:

• A passphrase-less key or an ssh-agent holding it (BatchMode won't prompt)
• kirocrew installed and a gateway running on the EC2 instance's loopback port

The Manage panel gives you these per-instance actions:

• Connect — open a tunnel + iframe
• Disconnect — tear down the tunnel
• Diagnose — run the failure-probe ladder and report the first broken link
• Restart — restart the remote gateway over SSH (service-aware)
• Edit — change name / host / port / TTL
• Remove — disconnect then delete

Every route in /api/instances/* is gated by _guard():

• Deny-by-default — reject Slack-origin requests (403)
• Owner-only — require request["user"] (authenticated dashboard session)
• Feature-gated — require instances.enabled: true
• SEL-audited — every call (success and denial) emits an audit event

Beyond the guard:

• Loopback-only forwards — ssh -N -L 127.0.0.1:<local>:127.0.0.1:<remote>
• No local shell — ssh is always invoked with an argv list; ssh_host cannot inject local shell syntax
• Charset-validated inputs — ssh_host and remote_bin rejected if they contain shell metacharacters or lead with -
• Short-lived tokens — ≤20 h, returned only in-memory to the caller, never logged, never in list/status payloads
• postMessage origin check — the parent validates every embedded-frame event.origin against the exact http://127.0.0.1:<port> of a currently-warm tunnel before trusting an unread-count message

Under instances.*: