Using SDE VMs

Using SDE VMs#

Virtual machines (VMs) are the computing environment where you do your work inside the SDE. Each VM runs Ubuntu and has Google Cloud tools pre-installed and pre-authenticated. You do not need to install or configure anything on the VM itself.

This page covers how to start, connect to, and stop your VM. Use the table below to find the section relevant to what you need to do.

Task	Where you do it	Section
Start a VM	Google Cloud Console (browser)	Start a VM
Open a terminal on the VM	Browser (SSH-in-browser)	Access the VM through the SSH-in-Browser
Connect to the VM desktop with a GUI	Browser + your local machine	Connect to VM Desktop
Stop a VM	Google Cloud Console (browser) + local machine	Stop a VM

Important

Where do I run commands?

There are two distinct places you will run commands in the SDE. Running a command in the wrong place will not work.

Name	What it is	Used for
SSH-in-browser	A terminal on the VM, opened as a tab in your web browser	Running commands on the VM: data work, file transfers, scripts
Terminal (Mac) or Google Cloud SDK Shell (Windows)	A terminal on your own laptop or workstation	Setting up the secure tunnel to connect to the VM desktop

Commands on the VM always run in SSH-in-browser.

Commands to connect to the VM run on your local machine.

Start a VM#

VMs do not run continuously. You start them at the beginning of a session and stop them when you are done. This keeps costs down and is required by SDE policy.

In this step, you will start your assigned VM and confirm that it is running and ready to use. Once the VM is running, you can connect to it using SSH-in-browser or the VM desktop.

Google Cloud Console

Open the VM Instances page

Log in to the Google Cloud Console in your web browser.
Go to Compute Engine > VM Instances .
Confirm the correct project is selected in the project dropdown at the top of the page.

Check the VM status and start it

Find your VM in the list. Check the status icon:
- Gray square icon: the VM is stopped. Proceed to start it.
- Green check mark: the VM is already running. Skip to the next section.
If the VM is stopped, click the three-dot icon on the right side of its row to open the More Actions menu.
Select Start/Resume. A confirmation dialog will appear warning about charges. Click Start.

Verify the VM is running

Wait approximately one minute. When the VM is ready, the status icon will turn green and you will see a notification in the Console.

Common errors

Error	Plain-English meaning	What to do
“You need additional access”	Your account cannot reach this project	Check you are connected to the Northwestern VPN and that the correct project is selected
VM does not appear in the list	You may be in the wrong project	Check the project dropdown at the top of the page

Remember to stop your VMs

Always stop your VM after each session. VMs are charged by the hour while running, even if you are not actively using them. Follow the Stop a VM instructions at the end of every session.

Next step: Connect to your VM via SSH-in-browser or the VM desktop.

SSH-in-browser Connection to a VM#

Make sure you’ve started the VM. From the VM Instances Page , with the relevant project selected at the top of page:

Note

Everything you type in SSH-in-browser runs on the VM, not on your local computer.

Google Cloud Console

Open SSH-in-browser

Start your VM before following these steps.
Go to Compute Engine > VM Instances and confirm the correct project is selected.
In the row for your VM, click the SSH button in the Connect column.

Note

The SSH button is grayed out when the VM is stopped. If you cannot click it, start the VM first.
A new browser tab will open.
Click Authorize to allow SSH-in-browser to connect to the VM.
Sign in with your Northwestern Google account.
When prompted to grant Google Cloud Shell access to your account, click Continue.
You will be redirected to a terminal prompt. Commands you type here run on the VM.

Set a password (first time only)

If this is your first time connecting to this VM, you will be prompted: “Please enter a remote desktop password.”

This password protects your VM desktop session. It prevents anyone else who may have access to the VM from connecting to your screen sharing session.

Choose a password and enter it.

Note

Remember VNC Password Record this password somewhere, ideally in a password manager . You will need it every time you connect to the VM desktop.
When asked “Would you like to enter a view-only password? (y/n)”, type n and press Enter.

Verify

Your SSH-in-browser terminal is ready when you see a command prompt similar to:

john_doe_northwestern@vm-name:~$

You can now run commands on the VM. If you only need a command line, you are done. To connect to the VM desktop with a graphical interface, proceed to VM Desktop.

Connect to VM Desktop#

The VM desktop gives you a full graphical interface. You can open applications, use a file manager, and work visually.

Overview

Connecting requires steps in your browser and steps on your endpoint.

Where	What
Browser	Open SSH-in-browser and gather connection details
Your local machine (Terminal or Google Cloud SDK Shell)	Run the tunnel command to create a secure connection
Your local machine (Screen Sharing or RealVNC)	Open the VM desktop

Prerequisite steps#

Before you begin, confirm:

The Google Cloud CLI is installed on your local machine.
Your VM is started.

Gather connection details#

Complete these steps in your web browser before touching your local machine.

Google Cloud Console

Open SSH-in-browser and find the port number

The port number changes every session. You must look it up each time before running the tunnel.

Open an SSH-in-browser connection to your VM. Complete the password setup if prompted.
Look for a line in the terminal output similar to:
```
Connect to the remote desktop on port 1234
```
Your port number may be different. Note this number as you will need it in the later steps.

Important

Do not close this SSH-in-browser tab. It must stay open for the entire session. Closing it will drop your connection to the VM.

Find your Project ID and VM name

You will also need your Project ID and VM name to run the tunnel command.

Project ID:

Click the project menu in the top bar of the Cloud Console.

VM name:

Visible in the Name column on the VM Instances page .

Record your connection details

Enter your values below. They will be automatically inserted into the commands below so you can copy and paste without editing.

Port number:
Project ID:
VM Name:

Warning

If any field above is left blank, the placeholder text will appear in the command instead of your value. Fill in all three fields before copying the commands below.

Open the secure tunnel#

These steps run on your own laptop or workstation, not in SSH-in-browser. Open the correct application for your operating system before continuing:

Mac: open the Terminal application (Applications > Utilities > Terminal).
Windows: open the Google Cloud SDK Shell (search for it in the Start menu).

Warning

Do not run these commands in SSH-in-browser. The tunnel must be created from your local machine, not from the VM.

macOS

1. Authenticate with Google Cloud

Run the following command in your Terminal:

gcloud auth login

This opens a browser window. Sign in with your Northwestern Google account. Return to Terminal when complete.

2. Set your project

gcloud config set project projectid

If you filled in the values above in the Record your connection details section, the value is already substituted above.

Expected output:

Updated property [core/project].

Step 3 — Verify your configuration

gcloud config list

Expected output:

[core]
account = yourname@northwestern.edu
disable_usage_reporting = True
project = projectid

Confirm that account shows your Northwestern email and project shows the correct Project ID before continuing.

4. Start the tunnel

gcloud compute start-iap-tunnel vm_id portnumber --local-host-port=localhost:portnumber --zone us-central1-b

Placeholder	What to substitute
`vm_id`	The VM name from Step 1b
`portnumber`	The port number from Step 1a

Command breakdown:

Part	What it does
`gcloud compute start-iap-tunnel`	Creates a secure encrypted tunnel through Google’s Identity-Aware Proxy to your VM
`vm_id`	The name of the VM you are connecting to
`portnumber`	The remote desktop port on the VM
`--local-host-port=localhost:portnumber`	Maps that VM port to the same port number on your local machine
`--zone us-central1-b`	The Google Cloud zone where your VM lives

5. Verify the tunnel is open

If the tunnel connected successfully, you will see:

Testing if tunnel connection works.
Listening on port [portnumber].

Important

Do not close this Terminal window. The tunnel stays open only while this window is running. Closing it will disconnect you from the VM desktop.

Common errors

Error	Plain-English meaning	What to do
`ERROR: (gcloud.compute...) Could not fetch resource`	Wrong project ID or VM name	Re-run `gcloud config list` to check the project, then verify the VM name
`Connection refused`	VM is not running or wrong port	Confirm the VM is started and re-check the port number in SSH-in-browser
`PERMISSION_DENIED`	Your account is not authorized for this VM	Contact your SDE administrator
No output / hangs	Tunnel failed silently	Press `Ctrl+C`, check your project and VM name, and try again

Windows

Note

On Windows, tunnel commands must be run in the Google Cloud SDK Shell, not in Command Prompt or PowerShell. The Google Cloud SDK Shell is installed with the Google Cloud CLI.

Open the Google Cloud SDK Shell from the Start menu before running any of the commands below.

1. Authenticate with Google Cloud

gcloud auth login

This opens a browser window. Sign in with your Northwestern Google account. Return to the Google Cloud SDK Shell when complete.

2. Set your project

gcloud config set project projectid

Placeholder	What to substitute
`projectid`	The Project ID you found in Step 1b

If you filled in the values above in the Record your connection details section, the value is already substituted above.

Expected output:

Updated property [core/project].

3. Verify your configuration

gcloud config list

Expected output:

[core]
account = yourname@northwestern.edu
disable_usage_reporting = True
project = projectid

Confirm that account shows your Northwestern email and project shows the correct Project ID before continuing.

4. Start the tunnel

gcloud compute start-iap-tunnel vm_id portnumber --local-host-port=localhost:portnumber --zone us-central1-b

5. Handle the Windows Firewall prompt

Windows Defender may display a firewall warning. Because gcloud is a Python application, the message may reference Python rather than gcloud. This is expected.

Windows Firewall prompt for gcloud tunnel

Click Allow Access to permit the tunnel. You will return to the Google Cloud SDK Shell.

6. Verify the tunnel is open

If the tunnel connected successfully, you will see:

Testing if tunnel connection works.
Listening on port [portnumber].

Important

Do not close the Google Cloud SDK Shell window. The tunnel stays open only while this window is running. Closing it will disconnect you from the VM desktop.

Open the VM desktop#

With the tunnel running, open your screen sharing application on your local machine.

macOS

Open Screen Sharing

Open the Screen Sharing application (Applications > Utilities > Screen Sharing).
If this is your first time connecting to this VM, click New Connection.

Enter the connection address

In the address field, enter:
```
vnc://localhost:portnumber
```
If you filled in the values above in the Record your connection details section, the value is already substituted above.
Click Connect.

If you have connected to this VM before, you can select it from the list instead of entering the address again.

Enter your password

Enter the remote desktop password you created when you first connected via SSH-in-browser.
You can choose to save the password to speed up future logins.
Click Sign in.

Verify A window opens showing the VM desktop. The VM runs Ubuntu Linux. You now have full access to the graphical interface.

Windows

Install and open RealVNC Viewer

If you do not have it installed, download RealVNC Viewer and install it.
Open the RealVNC Viewer application.

Enter the connection address

In the address bar at the top of RealVNC Viewer, enter:
```
localhost:portnumber
```
If you filled in the values above in the Record your connection details section, the value is already substituted above.
Press Enter.

Accept the encryption warning

An Encryption dialog will appear.
You may choose to suppress this warning in future sessions. Click Continue.

Enter your password

Enter the remote desktop password you created when you first connected via SSH-in-browser.
You can choose to save the password to speed up future logins. Click OK.

Verify A window opens showing the VM desktop. The VM runs Ubuntu Linux. You now have full access to the graphical interface.

Common errors#

Error	Plain-English meaning	What to do
`ERROR: (gcloud.compute...) Could not fetch resource`	Wrong project ID or VM name	Re-run `gcloud config list` to check the project, then verify the VM name
`Connection refused`	VM is not running or wrong port	Confirm the VM is started and re-check the port number in SSH-in-browser
`PERMISSION_DENIED`	Your account is not authorized for this VM	Contact your SDE administrator
`Firewall prompt loops or blocks`	Windows is blocking the connection	Make sure you clicked Allow Access and try again

Stop a VM#

Stop your VM at the end of every session. Stopping shuts the VM down safely while preserving all your data and configuration. You can start it again later without losing anything. It is not the same as deleting it.

Warning

VMs are billed by the hour while running, even if you are not actively using them. Always stop your VM when you are finished.

Before stopping, save your work:

Copy any data you want to keep to a storage bucket.
Save any scripts or code to a bucket as well. The VM filesystem is not a permanent backup.

Depending on how you connected, you may have up to four things running that need to be closed in a specific order:

#	What	Where
1	Screen Sharing or RealVNC Viewer	Your local machine
2	Tunnel window	Your local machine (Terminal or Google Cloud SDK Shell)
3	SSH-in-browser tab	Your browser
4	The VM itself	Google Cloud Console

Close them in this order. Stopping the VM before closing the tunnel and screen sharing can cause errors.

Stop the tunnel#

If you did not open a VM desktop session, skip this step.

macOS

Go to the Terminal window where the tunnel is running. You will see:

Testing if tunnel connection works.
Listening on port [portnumber].

Press Control+C to stop the tunnel.
You should see the prompt return and the message:
```
Server shutdown complete.
```

Windows

Go to the Google Cloud SDK Shell window where the tunnel is running. You will see:
```
Testing if tunnel connection works.
Listening on port [portnumber].
```
Press Control+C to stop the tunnel.
If prompted “Terminate batch job (Y/N)?”, type n and press Enter.
You should see the prompt return and the message:
```
Server shutdown complete.
```
Close the Google Cloud SDK Shell window.

Close the SSH-in-browser tab#

Google Cloud Console

Go to the browser tab where SSH-in-browser is open.
Close the tab.

Stop the VM in the Console#

Google Cloud Console

Go to Compute Engine > VM Instances and confirm the correct project is selected.
Check the checkbox next to your VM in the list.
Click Stop in the toolbar.
In the confirmation dialog, click Stop.
The shutdown takes a minute or two. You can track progress in the notifications panel.

Verify When complete, the VM status icon will return to a gray square. Your VM is stopped and no longer incurring charges.

Note

Stopping is not deleting. All your data, configuration, and installed software remain intact. Start the VM again at the beginning of your next session.

Using SDE VMs

Contents

Using SDE VMs#

Start a VM#

SSH-in-browser Connection to a VM#

Connect to VM Desktop#

Prerequisite steps#

Gather connection details#

Open the secure tunnel#

Open the VM desktop#

Common errors#

Stop a VM#

Close the screen sharing window#

Stop the tunnel#

Close the SSH-in-browser tab#

Stop the VM in the Console#