VS Code Remote-SSH to a GCP VM through IAP, on a Mac

An SSH host that goes through IAP

The VM needs what any IAP SSH connection needs: a firewall rule from 35.235.240.0/20 on tcp:22, roles/iap.tunnelResourceAccessor, and your key accepted through OS Login or metadata (see SSH without an external IP). Run gcloud compute ssh once so it creates ~/.ssh/google_compute_engine, then add a host to ~/.ssh/config:

Host example-vm
    User dana_acme_example
    IdentityFile ~/.ssh/google_compute_engine
    ProxyCommand /opt/homebrew/bin/gcloud compute start-iap-tunnel example-vm 22 --listen-on-stdin --zone=europe-west1-b --project=acme-prod

Check it in Terminal with ssh example-vm. Then in VS Code, run Remote-SSH: Connect to Host… from the Command Palette and pick example-vm.

gcloud not found when VS Code starts from the Dock

An app opened from the Dock or Spotlight does not read your shell's PATH, so a ProxyCommand that says only gcloud fails there while working in Terminal. VS Code then reports a timeout, often "Connection timed out during banner exchange", because the proxy exited before SSH could start. Use the full path, as above. Find it with:

which gcloud

On Apple Silicon with Homebrew it is usually /opt/homebrew/bin/gcloud; with Google's installer, the bin folder of wherever you unpacked the SDK.

The connect timeout

Remote-SSH gives up if the connection is not up within its connect timeout. Opening an IAP tunnel, signing in and, on the first visit, starting a stopped VM can take longer than you expect. Raise it in VS Code's settings:

"remote.SSH.connectTimeout": 60

A VM that cannot reach the internet

On the first connection, VS Code installs its server on the VM. By default it tries to download it on the VM first and falls back to downloading it on your Mac and copying it over. On a VM with no external IP and no Cloud NAT, that first attempt can hang for a long time at "Downloading VS Code Server" before the fallback. Skip it:

"remote.SSH.localServerDownload": "always"

Extensions you install on the remote side have the same problem. Install them from a VSIX file, or give the subnet Cloud NAT.

With Ostgate instead of gcloud

Ostgate is a native macOS app that opens IAP tunnels itself. In Settings › SSH Integration, click Install: Ostgate adds one managed block to ~/.ssh/config for every instance of your signed-in accounts, and its ProxyCommand calls Ostgate by its full path, so the Dock PATH problem does not arise and no gcloud is needed. In VS Code, connect to a host named after the instance:

web-1.europe-west1-b.acme-prod.gcp

ssh still signs in with your own keys from ~/.ssh, so your public key must be accepted by the VM: in your OS Login profile, or in the instance's or project's SSH keys. The optional OS Login username field in the same settings adds a User line, so you do not have to type it. It works with Ostgate's window closed.

When it does not connect

Questions

Why does VS Code say "Connection timed out during banner exchange"?

The ProxyCommand failed before SSH could start, and VS Code only sees silence. On a Mac the usual reason is that VS Code, opened from the Dock, cannot find gcloud on its PATH. Put the full path to gcloud in the ProxyCommand.

Why does "Downloading VS Code Server" hang?

The VM has no external IP and no Cloud NAT, so it cannot download the server itself, and VS Code's fallback to a download on your Mac can take a long time to start. Set remote.SSH.localServerDownload to always, and VS Code downloads it on your Mac and copies it over the SSH connection straight away.

Does this work for Cursor or other VS Code based editors?

Editors that connect with the system ssh and read ~/.ssh/config work the same way. Check that the editor's remote extension uses your SSH config rather than its own SSH client.

Do I need gcloud on the Mac?

With the gcloud ProxyCommand, yes. With Ostgate's SSH integration, no: the ProxyCommand calls Ostgate, which opens the IAP tunnel with your signed-in account.