This page describes how to use thegcloud CLI to connect to yourworkstation from a local machine using SSH (or any other TCP protocol).

Cloud Workstations uses a tunnel to forward TCP traffic between a port on yourlocal machine and a port on your workstation without openly exposingyour workstation to the internet. Connections are authenticated usingcredentials from thegcloud CLI and authorized according to thetarget 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 otherapplication that uses TCP.

For convenience, Cloud Workstations provides thegcloud workstations sshcommand, which establishes the TCP tunnel and runs an SSH client with asinglegcloud CLI command.

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

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:

   gcloudinit

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

3. Make sure that you have theCloud Workstations UserIAM 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 thegcloud workstations sshcommand, which starts a TCP tunnel and runs an SSH client.

To copy the command to the copy-paste buffer, clickcontent_copyCopy code sample and then paste the command into a local terminal window:

gcloudworkstationsssh\--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 theproject containing the workstation. If omitted, the current project isused.

• REGION: the region where the workstation's cluster islocated—for example,us-central1.

• CLUSTER_NAME: the name of the workstation clustercontaining the workstation.

• CONFIG_NAME: the name of the workstation configurationcontaining this workstations.

• WORKSTATION_PORT (Optional): the port on the workstationto which traffic should be sent. If omitted, traffic will be sent to port22. All preconfigured Cloud Workstations images include an SSH server that runson workstation port22.

• LOCAL_PORT (Optional): the localhost port from whichtraffic will be sent. Valid port numbers are1024 to65535. If you omitthe--local-host-port flag or specify a port of0 an unused port isselected automatically.

• WORKSTATION_NAME: the name of the workstation.

Optional: To pass flags and positionals to the underlyingsshimplementation, append them to the command after a double-dash (--).

Use a TCP tunnel to forward arbitrary TCP traffic to your workstation

To connect to a workstation using a TCP application other thanssh, use thegcloud workstations start-tcp-tunnelcommand:

1. Run the followinggcloud CLI command to create an authenticatedTCP tunnel.

   To copy the command to the copy-paste buffer, clickcontent_copyCopy code sample and then paste the command into a local terminal window:

   gcloudworkstationsstart-tcp-tunnel\--project=PROJECT_ID\--region=REGION\--cluster=CLUSTER_NAME\--config=CONFIG_NAME\--local-host-port=localhost:LOCAL_PORT\WORKSTATION_NAME\WORKSTATION_PORT

   Replace the following values:

   • PROJECT_ID: the Google Cloud project ID for theproject containing the workstation. If omitted, the current project isused.

   • REGION: the region where the workstation's cluster islocated—for example,us-central1.

   • CLUSTER_NAME: the name of the workstation clustercontaining the workstation.

   • CONFIG_NAME: the name of the workstationconfiguration containing this workstations.

   • LOCAL_PORT (Optional): the localhost port from whichtraffic will be sent. Valid port numbers are1024 to65535. If youomit the--local-host-port flag or specify a port of0 an unusedport is selected automatically.

   • WORKSTATION_NAME: the name of the workstation.

   • WORKSTATION_PORT: the workstation port to whichtraffic should be sent.Preconfigured Cloud Workstations images include an SSH server that runs on workstation port22.

2. Thegcloud CLI command performs a connectivity test with theworkstation, opens a tunnel, and then displays a port number:

   Listening on port [LOCAL_PORT].

   All traffic sent tolocalhost:LOCAL_PORT is forwarded tothe workstation. The port is only accessible by applications running on yourlocal computer.

3. Leave thegcloud CLI running and open another terminal to run theapplication that connects to your workstation.

   For example, if you are running a server on your workstation that servesportWORKSTATION_PORT, and in the previous step youcreated a TCP tunnel that forwards traffic between your local portLOCAL_PORT and the workstation portWORKSTATION_PORT, you could runcurl on your localmachine to connect to the server on your workstation:

   curl localhost:LOCAL_PORTHello, world!

4. When you are finished, return to the terminal where you started the TCPtunnel and interrupt thegcloud CLI by pressingControl+C.

Use SSH servers on different ports

Custom container images can also use SSH servers on any port. To support connections from thegcloud CLI tunnel, you must configure custom SSH servers to allowpassword authentication and set the target user with an empty password.Cloud Workstations usesCloud IAM to help ensure that only authorized traffic is sent to the SSH server.

What's next

• Set container environment variables in SSH sessions for custom container images
• Enable X11 forwarding for custom container images