A Remote Crew is another machine running its own Kiro Crew gateway — a dev box, an EC2 instance, the server in your closet — that this dashboard can reach. One dashboard becomes the hub: you switch between your own machine and each remote one from a strip in the top header, start a session that runs over there, and search every connected machine's history from one box.
A gateway binds its dashboard to loopback only, so nothing here opens a port on the remote. The hub tunnels to the remote's loopback port over SSH or AWS Systems Manager, mints a short-lived dashboard token on the remote, and embeds that dashboard in the pane. The remote keeps running whether or not you are looking at it; the hub only adds a way in.
The word crew means four different things in this product, and three of them turn up on this page. The four things called "crew" sorts them out.
Remote Crew is off by default and is read only at gateway startup, so it takes a restart:
kirocrew config set instances.enabled true
kirocrew restartSettings → Remote Crew has the same toggle and then tells you a restart
is still pending. With the flag off, that page shows an opt-in card and the
instances API answers 403. If the page says the feature is enabled but not
active, the flag was set after the gateway started — restart.
Each instance records a connection method. Both of the two you would pick by hand end at the same place — the remote's loopback gateway — but they get there differently.
| SSH (default) | AWS SSM | |
|---|---|---|
| Inbound port on the remote | needs SSH reachable, directly or through a bastion | none |
| What authorizes you | an SSH key your agent holds | IAM — ssm:StartSession on that instance, plus ssm:SendCommand and ssm:GetCommandInvocation, which the token mint runs over. Granting only the first brings the tunnel up and then fails the mint |
| Needed on the hub | ssh |
AWS CLI plus session-manager-plugin |
| Needed on the remote | sshd |
the SSM agent and an instance role for SSM |
| Revoking access | rotate or remove the key | edit the IAM policy |
Choose SSH for a machine you already ssh into — a dev host, a home server,
anything with an ~/.ssh/config entry. It is the shorter path: if
ssh <host> works without a password prompt, so does this.
Choose SSM for anything in AWS you would rather not expose port 22 on, or where you want reachability to be a policy decision rather than a key someone holds. The EC2 guide walks both ends of it, and SSM vs SSH covers why a cloud-launched machine is registered with SSM.
A third method, Fargate, is set for you when a crew container is launched as an ECS task. It forwards to the task's chat API rather than a dashboard, so its card shows a URL to copy and opens no pane.
Two prerequisites hold for the two methods you pick yourself: you can reach the remote non-interactively (no password prompt), and the remote already has Kiro Crew installed with its gateway running. Neither applies to Fargate — the launcher registers that record for you, and the task runs no gateway to reach.
Settings → Remote Crew is the control plane. It does not embed anything — that is the switcher's job.
-
Open the panel and add an instance.
-
Fill in the fields:
Field What to put in it Name Any label. It is what the switcher, the pane and every badge call this machine. SSH host / alias Exactly what you would type after ssh— a hostname, an FQDN,user@host, or an~/.ssh/configalias. Per-host details likeUser,IdentityFile,Port,ProxyJumpstay in your SSH config.Remote port The port the remote gateway listens on, 5476by default. Several instances may share it; the hub allocates each one its own local port.Token TTL How long a minted dashboard token lives, 20hby default.Remote kirocrew path Only when kirocrewlives somewhere unusual on the remote.An SSM instance takes its target id (
i-…ormi-…) and, optionally, an AWS profile name, a region, and the remote POSIX user commands should run as (ec2-userby default — an Ubuntu image usually needsubuntuhere). Only the profile name is stored; credentials come from the AWS CLI's own chain. -
Click Connect. The hub opens the tunnel and mints the token.
The registry file (~/.kiro/crew/instances.json) holds connection coordinates
only. No key, password or token is ever written there.
Editing and removing live in each row's overflow menu. Changing anything the tunnel is built from — the host, the port, the transport — drops the live tunnel first, so the row comes back offering Connect rather than quietly forwarding the old port under a new label. Renaming or changing the TTL leaves a working pane alone. If you started typing an edit and navigated away, the draft is still there when you come back, and Kiro Crew refuses to open a second row's editor while it is unsaved rather than throwing your typing away.
The top header carries the switcher. Local returns to your own dashboard; every other entry is one of your machines, each naming its tunnel state in words beside its status dot. In the desktop app, Cmd/Ctrl plus a digit jumps between panes in switcher order.
Entries live in a dropdown because the number of machines is unbounded. Any entry — Local included — can be pinned from the pin icon on its own row, which lifts it out of the menu into an always-visible chip beside the trigger. Nothing is pinned until you pin it, so a one-machine install sees no chip row at all. The dropdown keeps an aggregate unread badge for every machine not on screen.
The hub keeps the most recently used panes warm — tunnel up, dashboard loaded — and reconnects the rest on demand. A pane that dropped out of the warm set still has its tunnel; selecting it re-warms it, which looks like a reconnect because the token is re-minted and the remote dashboard boots again.
Each row also carries badges read off its record: SSM or SSH for the transport, and EC2 when the instance was provisioned by the cloud launcher.
Each crew in Settings → Remote Crew has a switch beside its status that reads Connections: On or Connections: Off. Off closes that crew's tunnel and keeps it closed: no click, auto-connect or gateway restart opens it again. Its sidebar group reads Off with an Enable button, and an open pane for it shows offline. A crew reached through it stays closed too, and connecting one names the crew that is off. Turning it back on reconnects it. The crew's settings are kept the whole time. Only the owner can flip the switch.
A remote pane is a full dashboard, so it can list remote crews of its own. When you connect one of those inside the pane, your dashboard adopts it as a top-level entry in your own switcher. You do not add it twice. The connection rides the crew that reaches it; your dashboard never dials that machine itself.
A chain is at most two hops deep (you → B → C), and one crew can carry at most
eight crews behind it. In Settings → Remote Crew such a row shows its host as
<host> (reported): it is the address that crew reports, not one you can
reach. When a crew in the middle of a chain is down, the entries behind it read
unreachable — <name> is down, naming the hop to fix.
Removing a crew also removes every crew reached through it.
New chat on crew creates a session ON a connected machine and opens it here in a crew window. It is a feature preview: turn on Settings → Developer → Feature Previews → Chat on a crew, then pick it from the new-chat menu and choose one of your connected machines. Only connected ones are offered, and creating one fails outright when the machine runs a Kiro Crew version too far from yours.
The window shows the remote's own transcript, running state and pending approval. Send, stop, approve, continue, regenerate and rewind call the remote's own routes, so its prompts, tools and model all run over there, against its agents and workspace. Nothing is stored on this machine, and every reply is redacted before it renders.
Two things follow from the split:
- The remote's roster wins. The session uses the remote machine's agents, models and workspaces, not this machine's. Your local default agent is not sent over; a name from your roster would mean nothing, or something else, over there. Your default memory mode is sent, so a new session does not quietly run in a different one.
- The remote owns the turn. A turn already in flight keeps running on the remote if you close the window or your browser goes away.
A chat an older version ran on a crew through the retired turn relay stays in your
list as a read-only archive. You can read it, but every action that would run
it answers relay_archive_read_only; open the crew's own session to keep going.
The opposite direction: sessions a connected machine owns are listed in this dashboard's Sessions list. The same switch holds both: Settings → Developer → Feature Previews → Chat on a crew. With it off, nothing is fetched at all.
With it on, the list is grouped per machine: Local first, then one collapsible group per crew, its header badged online, reconnecting, error or offline from the tunnel's state. A crew's group holds the sessions it owns and any read-only relay archive that ran on it. Inside the group the crew's own folders nest its rows, with unfiled rows last — a read-only mirror of the crew's folder tree, edited on the crew, each space keeping its own collapse state. A crew that disconnects keeps its last listed rows, dimmed and without live status, until you reload; nothing asks it again while it is down. Collapsing a group never changes which session is open. With no crew to group, the list has no group headers and looks as it always did. The board view groups nothing: it leaves peer rows out and says how many it left out.
Clicking a crew's session opens it in a crew window, the same window New chat on crew opens: the remote machine's own transcript, running state and any pending approval, driven over the connection. Nothing is copied to this machine.
A peer row deliberately does less than a local one, because the other machine — not this one — owns the session:
| Not on a peer row | Why |
|---|---|
| Rename, close, pin | They change the session, which lives on the other machine. |
| Folders and drag | Filing is local bookkeeping about local rows. |
The ⋯ group actions |
Same reason: they act on sessions this machine owns. |
| The board view | It stays local, and reports how many rows it filtered out. |
Only live sessions appear here. The other machine's closed ones are reachable through search.
With at least one machine connected, both search surfaces — the ⌘K palette's Sessions tab and the sidebar's Older Sessions search — answer from your own gateway and every connected one. With none connected they stay local, so a single-machine install pays nothing for the feature.
Results interleave by rank: position one is your best local hit, position two is the best hit from the next machine, and so on. Scores are never compared across machines, so no machine's results can crowd out another's. A machine that does not answer in time is reported as not searched rather than silently dropped.
A remote result is badged with its machine's name, and:
- Clicking it switches to that machine's pane, reconnecting first if needed. The transcript lives over there, so this is how you get to it.
- Delete is hidden. It would target a local session file, which is not this one.
- ⌘Enter (open in the local split grid) does nothing on a remote row.
If the federated search fails for any reason — including the feature being off — search falls back to your local sessions, which is always the floor.
The product's own name is in three of these, which is exactly why they get confused. They are unrelated.
| What you see | What it is | Where it lives |
|---|---|---|
| Kiro Crew | The product. | Everywhere |
Remote Crew — spelled instance in config, routes and code (instances.json, /api/instances) |
Another machine running its own gateway, reached over a tunnel. This page. | Settings → Remote Crew, the header switcher |
| Crew Member, or mate | A named assistant you keep: its own workspace, memory, agent template and model, with a standing thread. Not a machine. | The Crew Members page — see crew-members.md |
| Issue Radar crew | An automation worker configured on a repository that claims an issue and moves it through the triage phases. Not a machine and not an assistant you chat with. | The Issue Radar Pipeline tab — see issue-radar-pipeline.md |
The short test: a Remote Crew is a host, a mate is an assistant, an Issue Radar crew is a worker on a repo.
Everything below is optional. The defaults are sized for a handful of machines over a normal link.
| Setting | Default | What it does |
|---|---|---|
instances.enabled |
false |
The opt-in. Read at startup, so changing it needs a restart. |
instances.warm_set_cap |
0 |
How many panes stay warm at once. 0 tracks how many machines you have registered, so up to an internal ceiling nothing is evicted. A number you set is honoured exactly. |
instances.default_destination |
"" |
The crew Send a copy to lists first, marked as the default. Empty means no default. A folder's own Default destination crew (Folder settings) overrides it for sessions in that folder. Nothing is sent until you click. |
instances.tunnel_base_port |
7778 |
The first local loopback port handed out for a tunnel. |
instances.ssh_compression |
true |
Compresses the tunnel. The whole remote dashboard travels over it, so this usually wins; turn it off on a fast local link. |
instances.connect_timeout_secs |
SSH 15s, SSM 25s | How long to wait for a tunnel to start accepting connections. Raise it for a host behind a jump host or ProxyCommand. |
instances.mint_timeout_secs |
SSH 30s, SSM 90s | How long to wait for the remote to mint a token. |
instances.max_recovery_attempts |
8 |
How many times a dropped tunnel retries itself before it gives up. |
instances.recover_backoff_max_secs |
30.0 |
Cap on the wait between those retries. |
instances.probe_failure_threshold |
3 |
How many failed health probes tear down a tunnel that has stopped forwarding. |
kirocrew config set instances.warm_set_cap 3
kirocrew config set instances.connect_timeout_secs 45instances.enabled and instances.tunnel_base_port both need a restart: the
first is read once at startup, and the second only reaches tunnels built after
it changes, since the live ones already hold ports from the old base. The rest
apply to the running gateway.
Each row has a Diagnose button. It walks the path from the outside in and reports the first broken link, which is usually the whole answer.
| What you see | What it means |
|---|---|
ssh_unreachable / ssm_unreachable |
The hub cannot reach the machine at all. Check the host alias and your key, or that the SSM agent is online. |
remote_down |
The machine is reachable but no gateway is listening on the port you configured. |
not_connected |
Everything is fine; this instance just has no tunnel yet. Click Connect. |
tunnel_down |
The forward died. Reconnect. |
| An SSH auth error on connect | Re-add your key to ssh-agent. Kiro Crew never prompts for a password, so a missing credential fails immediately — and the tunnel heals itself once the key is back. |
| A blank or black pane | The embedded dashboard never announced itself. Use Retry on the error panel. |
| "local port N was taken while connecting" | Something grabbed the port first. Retry, or move instances.tunnel_base_port somewhere quieter. |
| A machine that keeps dropping | The tunnel already healed itself before giving up and running a diagnosis: about two minutes when the tunnel cannot be rebuilt, or roughly attempts × (probe window + backoff), about 6 minutes at the default 8 instances.max_recovery_attempts, when the forward re-binds but the far end stays dead. Check the remote gateway and the link itself. |
| "the SSM session … was closed by AWS after a period with no activity" (or "AWS ended the SSM session") | AWS closed the SSM or Fargate forward. Open a new one with Connect on the crew's card in Settings. To allow longer idle periods, raise the Session Manager idle-timeout preference for that account and region. |
unreachable — <name> is down on a chained crew |
The crew it is reached through is down. Fix that crew's row first; the chained one comes back with it. |
| Every token mint fails on one machine, whose gateway is healthy | The remote's kirocrew on PATH probably points at an install that is not the one running. Reinstall it there. |
- Setting up Remote Crew on an EC2 instance — both transports end to end, plus the EC2 gotchas.
- Native SSM vs legacy SSH — how a cloud-launched machine is reached.
- Remote and mobile access — installing and running a gateway on the far machine in the first place.
- dashboard.md — the dashboard the switcher sits in.
- crew-members.md — mates, which are not machines.