GCP SSH + OS Login from Windows

Overview

Connect to a Google Cloud Compute Engine Linux VM from Windows using OS Login. This guide covers SSH key creation, Google Cloud CLI install, adding your public key, enabling OS Login on the VM, IAM roles, and connecting — including the common project number vs project ID mistake.

Follow the sections in order the first time. Later use the cheat sheet when something breaks.

What you need

A GCP project (example: testing-purpose-503607)
A Linux VM (example: instance-20260811-081515 in zone asia-south2-a)
The Google account you use with gcloud
Windows Command Prompt and PowerShell (Admin)

1. Create an SSH key pair

Open Command Prompt and run ssh-keygen with -C for the username comment:

ssh-keygen -t rsa -f C:\Users\WINDOWS_USER\.ssh\KEY_FILENAME -C USERNAME

Or with ed25519 (recommended) and your profile path:

ssh-keygen -t ed25519 -f %USERPROFILE%\.ssh\KEY_FILENAME -C USERNAME

Replace:

WINDOWS_USER — your Windows username (or use %USERPROFILE%)
KEY_FILENAME — key file name (example: gcMachine or id_ed25519). This creates KEY_FILENAME (private) and KEY_FILENAME.pub (public)
USERNAME — VM username comment. For OS Login this is often like calcbase_official_gmail_com

Files are saved under:

Private: C:\Users\WINDOWS_USER\.ssh\KEY_FILENAME
Public: C:\Users\WINDOWS_USER\.ssh\KEY_FILENAME.pub

A public key looks like:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDAu5kKQCPF... cloudysanfrancisco

or:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... your-comment

Never share the private key. Only upload the .pub file.

Notes:

On Linux VMs, do not use root unless you explicitly allow root login
For Windows AD VMs, use DOMAIN\username (this guide focuses on Linux + OS Login)

2. Install the Google Cloud CLI

Open PowerShell as Administrator and run:

(New-Object Net.WebClient).DownloadFile(
  "https://dl.google.com/dl/cloudsdk/channels/rapid/GoogleCloudSDKInstaller.exe",
  "$env:Temp\GoogleCloudSDKInstaller.exe"
)
& "$env:Temp\GoogleCloudSDKInstaller.exe"

In the installer:

Accept defaults (Next → Next → Install)
The installer is signed by Google LLC
If you use a screen reader, enable Turn on screen reader mode
When finished, untick all options (Start Menu / Desktop shortcuts and “start the Google Cloud CLI shell”). You will configure gcloud next yourself

Open a new Command Prompt and initialize:

gcloud init

3. List projects (use PROJECT ID, not number)

gcloud projects list

Example output:

PROJECT_ID: testing-purpose-503607
NAME: Testing purpose
PROJECT_NUMBER: 88909271654

OS Login commands need PROJECT_ID (testing-purpose-503607), not the project number.

4. Add your public key with OS Login

gcloud compute os-login ssh-keys add ^
  --key-file=KEY_FILE_PATH ^
  --project=PROJECT ^
  --ttl=EXPIRE_TIME

Real example:

gcloud compute os-login ssh-keys add --key-file="%USERPROFILE%\.ssh\id_ed25519.pub" --project=testing-purpose-503607

Mistake: project number instead of project ID

gcloud compute os-login ssh-keys add --key-file="%USERPROFILE%\.ssh\id_ed25519.pub" --project=88909271654

Error:

ERROR: (gcloud.compute.os-login.ssh-keys.add) The value of `--project` flag was set to Project number.
To use this command, set it to PROJECT ID instead.

Fix: use --project=testing-purpose-503607.

Successful response

On success you get a login profile. Important fields:

username — SSH as this user (example: calcbase_official_gmail_com)
homeDirectory — example: /home/calcbase_official_gmail_com
sshPublicKeys — confirms your public key is registered

Copy the username. You need it for plain ssh.

5. Enable OS Login on the VM

Recommended: enable OS Login only on this instance.

gcloud compute instances add-metadata instance-20260811-081515 --zone=asia-south2-a --metadata=enable-oslogin=TRUE

Replace the instance name and zone with yours if different.

6. Grant OS Login IAM roles

Basic SSH (no sudo):

gcloud projects add-iam-policy-binding testing-purpose-503607 --member="user:YOUR_GOOGLE_EMAIL" --role="roles/compute.osLogin"

SSH + sudo / admin on the VM:

gcloud projects add-iam-policy-binding testing-purpose-503607 --member="user:YOUR_GOOGLE_EMAIL" --role="roles/compute.osAdminLogin"

Replace YOUR_GOOGLE_EMAIL with the Google account used for gcloud.

Google requires roles/compute.osLogin or roles/compute.osAdminLogin for OS Login SSH access. If you already own the project, you may already have enough access — add the role explicitly if SSH still fails with a permission error.

7. Connect to the VM

Option A — preferred: gcloud SSH

gcloud compute ssh handles OS Login for you:

gcloud compute ssh instance-20260811-081515 --zone=asia-south2-a

Option B — plain ssh

ssh -i "%USERPROFILE%\.ssh\gcMachine" calcbase_official_gmail_com@34.126.216.66

Use:

The private key that matches the .pub you registered
The OS Login username from step 4
Your VM external IP

Quick checklist

SSH key exists under %USERPROFILE%\.ssh\
Google Cloud CLI installed and gcloud init done
Public key added with os-login ssh-keys add using project ID
VM metadata has enable-oslogin=TRUE
IAM role osLogin or osAdminLogin granted
Connect with gcloud compute ssh or ssh -i ... username@ip

Command cheat sheet

REM List projects
gcloud projects list

REM Add public key (OS Login) — use PROJECT ID
gcloud compute os-login ssh-keys add --key-file=%USERPROFILE%\.ssh\id_ed25519.pub --project=PROJECT_ID

REM Enable OS Login on one VM
gcloud compute instances add-metadata INSTANCE_NAME --zone=ZONE --metadata=enable-oslogin=TRUE

REM Grant roles
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:EMAIL" --role="roles/compute.osLogin"
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:EMAIL" --role="roles/compute.osAdminLogin"

REM Connect
gcloud compute ssh INSTANCE_NAME --zone=ZONE
ssh -i %USERPROFILE%\.ssh\KEY_FILENAME OS_LOGIN_USERNAME@EXTERNAL_IP

What’s next

Once you are inside the VM, continue with deploy work: update packages, install Docker / Node / pnpm, clone your repo, run Postgres, configure .env, and start backend + frontend (optionally behind Nginx).

GCP Compute Engine SSH from Windows: OS Login Step-by-Step