connect-linux-vm

name	connect-linux-vm
description	Use when the user wants to SSH into a Linux GCE VM through IAP — install their key on the VM if needed, start a tunnel, and either return the ssh command or open Terminal. Triggers on "ssh into <vm>", "give me a shell on", "open Linux VM".

SSH to a Linux GCE VM via IAP

Preconditions

1. auth_check → if false, auth_login.

Existing saved connection (linux platform)

1. connections_list → confirm the chosen one has platform: "linux".
2. If username is empty, ask the user, then connections_set_username { connectionId, username }.
3. If sshIdentityPath is empty, install a key:
   • Preferred: ssh_generate_keypair { connectionId, linuxUsername } — generates Ed25519 locally, installs the public key on the VM, and stores the private key path on the connection.
   • Or ssh_install_key { connectionId, linuxUsername, publicKey } if the user already has a key they want to push.
4. tunnels_start_for_connection { connectionId } (skip if tunnels_active already lists it).
5. Either:
   • Hands-off: ssh_launch_terminal { connectionId } opens a new Terminal window and runs ssh.
   • Show command: ssh_command { connectionId } returns the literal ssh -p <port> ... user@127.0.0.1 so the user can paste it into their own shell.

No saved connection

1. projects_list / vms_list → confirm the VM is Linux (isWindows: false).
2. connections_add { platform: "linux", remotePort: 22, username }. Use displayName like "web-01 (eu-west2-c)".
3. Continue from step 3 above.

Pitfalls

• OS Login enabled? ssh_install_key will succeed on ssh-keys metadata even when OS Login is enabled, but the key won't take effect — the VM uses the IAM-managed key set instead. If the user reports "permission denied", check the VM in the GCP console for the enable-oslogin metadata flag and tell them to either disable it or use OS Login directly.
• Generated private keys land under ~/Library/Application Support/IAP Tunnel Manager/ssh/ with mode 0600 — mention the path so the user can back it up.
• accept-new host key policy is on by default; the first connection prints a fingerprint — that's expected.