SSH support

This page describes how to use the gcloud CLI to connect to your workstation from a local machine using SSH (or any other TCP protocol).

Cloud Workstations uses a tunnel to forward TCP traffic between a port on your local machine and a port on your workstation without openly exposing your workstation to the internet. Connections are authenticated using credentials from the gcloud CLI and authorized according to the target workstation's IAM policies.

Once the TCP tunnel is established between your local port and the workstation, you can use it to forward traffic from an SSH client, curl, or any other application that uses TCP.

For convenience, Cloud Workstations provides the gcloud workstations ssh command, which establishes the TCP tunnel and runs an SSH client with a single gcloud CLI command.

For all other use cases, use the gcloud workstations start-tcp-tunnel command to establish the TCP tunnel and run the application that will use the tunnel (for example, curl) in a separate terminal.

Before you begin

  1. If you don't already have a workstation to connect to, set up a workstation.

  2. Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command: 

    gcloud init

    If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  3. Make sure that you have the Cloud Workstations User IAM role on the workstation you will connect to.

    Go to IAM

Connect to your workstation using SSH

To establish a secure SSH connection to your workstation, use the gcloud workstations ssh command, which starts a TCP tunnel and runs an SSH client.

Run the following command in a local terminal window:

gcloud workstations ssh \
    --project=PROJECT_ID \
    --region=REGION \
    --cluster=CLUSTER_NAME \
    --config=CONFIG_NAME  \
    --port=WORKSTATION_PORT  \
    --local-host-port=localhost:LOCAL_PORT  \