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

If you don't already have a workstation to connect to, set up a workstation.
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.
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  \
    WORKSTATION_NAME

Replace the following values:

PROJECT_ID: the Google Cloud project ID for the project containing the workstation. If omitted, the current project is used.
REGION: the region where the workstation's cluster is located—for example, us-central1.
CLUSTER_NAME: the name of the workstation cluster containing the workstation.
CONFIG_NAME: the name of the workstation configuration containing this workstations.
WORKSTATION_PORT (Optional): the port on the workstation to which traffic should be sent. If omitted, traffic will be sent to port 22. All preconfigured Cloud Workstations images include an SSH server that runs on workstation port 22.
LOCAL_PORT (Optional): the localhost port from which traffic will be sent. Valid port numbers are 1024 to 65535. If you omit the --local-host-port flag or specify a port of 0 an unused port is selected automatically.
WORKSTATION_NAME: the name of the workstation.

SSH configuration and the `.ssh/config` file

When you use gcloud workstations ssh, the command routes your connection through localhost. As a result, it doesn't automatically apply Host entries from your ~/.ssh/config file that use the workstation's name.

To apply custom SSH configurations, choose one of the following options:

Option 1: Pass flags on the command line

You can pass SSH options directly to the underlying SSH client by appending them after a double-dash (--):

gcloud workstations ssh \
    --project=PROJECT_ID \
    --region=REGION \
    --cluster=CLUSTER_NAME \
    --config=CONFIG_NAME \
    WORKSTATION_NAME \
    -- -o SSH_OPTION=VALUE

Option 2: Use a persistent TCP tunnel and `.ssh/config`

If you prefer to use your ~/.ssh/config file:

Start a persistent TCP tunnel in a separate terminal window and specify a local port:

gcloud workstations start-tcp-tunnel \
    --project=PROJECT_ID \
    --region=REGION \
    --cluster=CLUSTER_NAME \
    --config=