Visual Studio Code SSH

Introduction

Visual Studio Code, or "VS Code", is a popular code editor. It is very customizable and allows the user to install many extensions.

Correct Usage of VS Code and other IDEs on the Sapelo2 Cluster

Please keep in mind that if you log in to the Sapelo2 Cluster via VS Code, you will be placed on a login node. This is acceptable only to edit code/files and other low-level tasks, but please do not run code there. It will likely overload our login nodes and cause disruptions to the performance of the login nodes. If you want to run tests in VS Code, please do one of the following first:

Running Code/Tests in VS Code on the Cluster

Start an interactive job within VS Code after logging in to the Sapelo2 Cluster
Use VS Code through On Demand (https://wiki.gacrc.uga.edu/wiki/OnDemand)

Note: Some VS Code extensions run in the background even if you are only editing code when you log in via your own VS Code installation on your computer (not through OnDemand). This can still overload our login nodes and cause significant slowness for users logged in to the same login nodes. To remedy this, you can disable these extensions for remote hosts using the instructions below.

Disabling Heavy-Hitting Extensions

Disabling extensions using "Disable (remote)" is simple and re-enabling them is also very quick and easy and does not require re-installation. "Disable (remote)" disables your VS Code extensions when on a remote host (like the Sapelo2 Cluster), but still allows you to use them locally.

If you log in to the Sapelo2 Cluster via VS Code (not through OnDemand), your enabled extensions may run in the background even if you are only editing code, which will still contribute to the load on the login node. High load on login nodes causes major disruptions in the performance of those nodes for all users logged in to those nodes.

The following VS Code extensions are some that commonly run in the background even when you are not running code. Please consider disabling them for remote hosts with "Disable (remote)" if you plan to log in to the Sapelo2 Cluster via the VS Code IDE. You can easily and quickly enable the extension when you are ready to run your code on the Sapelo2 Cluster within an interactive job in your VS Code session.

Extensions:

C/C++ (ms-vscode.cpptools)
Python (ms-python.python)
Pylance (ms-python.vscode-pylance)
Jupyter (ms-toolsai.jupyter)

GitHub Copilot (github.copilot)

GitHub Copilot Chat (github.copilot-chat)
Codeium (codeium.codeium)
Claude-related extensions
Docker (ms-azuretools.vscode-docker)

Steps to disable extensions for remote hosts using "Disable (remote)":

In VS Code, click on the extension panel to view your extensions
Click on the gear icon next to the extension that you want to disable
Click on 'Disable (remote)'

You can then re-enable your extensions if you need to run tests on the Sapelo2 Cluster by starting an interactive job in your VS Code session and clicking "Enable" on your desired extension

Downloading VS Code

If you haven't already, you can download VS Code here. If you're using Windows, you'll almost certainly want to download the 64 bit User Installer.

Installing the SSH extension

Here we will go over how to set up its SSH extension. This will allow you to have VS Code connect to Sapelo2 so that you can edit files on the cluster with your local instance of VS Code.

Open the Extensions Interface

When you open VS Code, you'll see on the left the Activity Bar, with several buttons displayed vertically.

Search for the SSH Extension

Clicking the button with the four squares opens up the extensions interface in the sidebar. Below you can see some of extensions I already have installed. Some of these are just simply color theme packages, to change syntax highlighting colors. Others provide features relevant to a particular programming language, such as the Python extension providing IntelliSense for Python.

At the top of the extensions interface is a search bar, where you can search for official or community-provided extensions. This is where you could search for the SSH extension, for example. Typically you'll want to install extensions provided by a known source, such as Microsoft in this case (the first option), and/or an extension that has many downloads and a high rating, as shown in this search output.

Install the SSH Extension

Once you find the extension you want, all you have to do is click the small "Install" button in the search output, and a tab will open in your editor with more information and instructions on how to use the extension that you have installed.

Using the SSH Extension

Click the SSH Button

You can hide the sidebar if you wish with cmd + b on Mac and ctrl + b on Windows. Once the SSH extension is installed you will see this small greater than & less than button in the bottom left corner of VS Code.

Add a new SSH Host Connection

Upon clicking that small SSH button in the bottom left, a prompt window will appear in the top middle of VS Code, asking how you want to connect to whatever it is you're going to SSH. Select the first option, "Connect Current Window to Host...".

Next, click the "Add New SSH Host..." option, and type your MyID@sapelo2.gacrc.uga.edu in the prompt, and then press enter.

If it asks you what SSH config file to update, you can just choose the first option.

Connect to Sapelo2

The prompt will then disappear, but now you can click the small SSH button in the bottom left of VS Code and see that your connection has been saved, you don't have to type it every time. Click the Sapelo2 connection to then be presented with a password prompt. This just wants your MyID password, as if you were normally connecting to Sapelo2 via PuTTY or your terminal. Then you will get an ArchPass DUO prompt. You can respond to this with a 1 for a push notification to your phone, or however you normally authenticate with ArchPass DUO.

Open Directories on Sapelo2

Once you approve the connection request via DUO, you're connected to Sapelo2! To open up a particular directory on Sapelo2, click the button on the side part that looks like two pieces of paper, which will open the explorer interface within the sidebar.

Click the "Open Folder" button to then be presented with a prompt where you can enter any path on Sapelo2 to which you have permission to access.

In this example, I've opened my home directory in the side bar. It presents it as a file tree that I can navigate graphically. Directories can be expanded by clicking them. Files can be opened in VS Code by double clicking them, as you can see here, with this file.txt in my home directory.

You can open multiple directories on Sapelo2 in the sidebar of VS Code by clicking the "Add Folder to Workspace" option in the File menu.

Open the Terminal in VS Code

I highly recommend toggling the Terminal in VS Code, which will allow you to interact with Sapelo2 as you normally would from within VS Code. To do this, click "Terminal" under the View menu. This will open up a terminal in the bottom half of the editor. You can enter any command as you normally would on Sapelo2.

VSCode Tunnel Workflow on Sapelo2 (GPU Nodes)

Overview

This guide describes how to run VSCode on Sapelo2 compute nodes using a tunnel-based workflow.

Motivation

Using VSCode Remote SSH directly from a local machine often:

Launches backend services on login nodes
Causes CPU and memory contention on login nodes
Leads to degraded performance for all users

This workflow ensures:

All VSCode processes run inside a Slurm interactive or batch job
Proper resource allocation (CPU / memory / GPU)
No persistent processes on login nodes

Workflow architecture

Local Browser (vscode.dev)

↓

VSCode Tunnel (cloud relay)

↓

Compute Node (Slurm job on gpu_p)

↓

VSCode Server + Extensions + User Workload

Advantages of This Workflow

Prevents login node overload
Enables GPU-based development
Supports AI/LLM workflows
Works entirely in browser

Step-by-Step Workflow in an Interactive GPU Job

1. Allocate a GPU Interactive Job

interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2

Note: Computing resources (CPU, memory, GPU) allocated here will be available within your VSCode tunnel working environment.

2. Clean Previous VSCode State (Recommended. Note that all VSCode extensions you downloaded will be removed)

rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel

3. Prepare Working Directory

cd /scratch/$USER/VSCode_tunnel/

4. Load VSCode Module

ml VSCode/1.88.1

Note: You can load additional compatible central modules at this step. Any modules loaded here will be configured and available within your VSCode tunnel working environment.

5. Authenticate VSCode Tunnel (You need a GitHub personal account to complete this step)

code-tunnel tunnel user login --provider github

Follow the instructions in your local browser:

Open https://github.com/login/device , choose to use your personal GitHub account.
Enter the code, for example, 15C1-6D7C
Authorize access

Open https://github.com/login/device

Enter the code

Authorize access

Authorization successful

6. Start the Tunnel

code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms

For example:

code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms

You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.

How would you like to log in to claud VSCode

7. Open VSCode in your Local Browser

To grant access to the server, following instructions, you will repeat what you did in Step 5:

Open https://github.com/login/device , choose to use your personal GitHub account.
Enter the code generated at this step, for example, E1F9-D7E8
Authorize access

Important Notes:

If another authorization prompt appears, it means the previous login in Step 5 was not fully completed.
Complete authorization using the latest code provided (for example: E1F9-D7E8).
Once authorization is successful, the VSCode link will appear and can be used directly.

The VSCode tunnel is now active. Open the provided link in your browser to connect

https://vscode.dev/tunnel/<tunnel-name>/<full>/<path>/<to>/<your>/<working folder where you started tunnel>

Example:

https://vscode.dev/tunnel/vscode-tunnel-0416/scratch/zhuofei/VSCode_tunnel

8. Trust Workspace

VSCode is now connected through the tunnel (cloud relay).

VSCode is now active

Note: Initial connection may take several minutes due to VSCode server download and setup.

The first time VSCode connects, it will automatically download the VSCode server (vscode-server-linux-x64.tar.gz) and temporarily store it in /tmp.
After the server is downloaded and started, VSCode will establish the connection. This process may take several minutes to complete—please be patient.

You will also need to click to trust workspace that VSCode will use:

Trust workspace

9. What happens if you cancel the interactive job or the job reaches its time limit on the cluster?

If you cancel the interactive job, or if the job is terminated after reaching its time limit, the VSCode tunnel session will stop, and all allocated resources (CPU, memory, and GPU) will be released. You will also lose the active VSCode connection and need to start a new session.

Step-by-Step Workflow in a batch GPU Job

1. Prepare a batch job submission script for VSCode tunnel session

Within the working directory of the interactive job described above, you can use a batch job submission script (sub.sh) as shown below:

#!/bin/bash
#SBATCH --job-name=code_tunnel
#SBATCH --partition=gpu_p
#SBATCH --gres=gpu:L4:2
#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=4
#SBATCH --mem=32G
#SBATCH --time=4:00:00
#SBATCH --output=log.%j.out

ml VSCode/1.88.1

code-tunnel  tunnel user login --provider github
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms

Note:

Computing resources (CPU, memory, GPU) allocated for your batch job will be available within your VSCode tunnel working environment.
You can load additional compatible central modules in your batch job submission script. Any modules loaded for your batch job will be configured and available within your VSCode tunnel working environment.

2. Submit a batch job

You can then submit the job to the cluster using:

sbatch sub.sh

3. How to complete Steps 5–7 from the interactive workflow described above.

Once the job starts running, monitor the job’s standard output log file (e.g., log.44588780.out). You can use commands such as catto view the log contents from time to time and follow the on-screen instructions to complete Steps 5–7 from the interactive workflow described above.

4. What happens if you cancel the batch job or the job reaches its time limit on the cluster?

If you cancel the batch job, or if the job is terminated after reaching its time limit, the VSCode tunnel session will stop, and all allocated resources (CPU, memory, and GPU) will be released. You will also lose the active VSCode connection and need to start a new session.

5. Example steps

zhuofei@ss-sub4 VSCode_tunnel$ pwd
/scratch/zhuofei/VSCode_tunnel
 
zhuofei@ss-sub4 VSCode_tunnel$ ls
sub.sh
 
zhuofei@ss-sub4 VSCode_tunnel$ cat sub.sh 
#!/bin/bash
#SBATCH --job-name=code_tunnel
#SBATCH --partition=gpu_p
#SBATCH --gres=gpu:L4:1
#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=4
#SBATCH --mem=32G
#SBATCH --time=4:00:00
#SBATCH --output=log.%j.out

ml VSCode/1.88.1

code-tunnel  tunnel user login --provider github
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms

zhuofei@ss-sub4 VSCode_tunnel$ sbatch sub.sh 
Submitted batch job 44594144

zhuofei@ss-sub4 VSCode_tunnel$ sq --me
JOBID         NAME            PARTITION        USER       NODES  CPUS   MIN_MEMORY   PRIORITY   TIME            TIME_LIMIT      STATE      NODELIST(REASON)    
44594144      code_tunnel     gpu_p            zhuofei    1      4      32G          996        0:02            4:00:00         RUNNING    ra5-6               

zhuofei@ss-sub4 VSCode_tunnel$ ls
log.44594144.out  sub.sh

# --- Next Steps ---
# --- 1. Run `cat log` ---
# --- 2. Follow the instructions shown in a browser ---
# --- 3. Return and run `cat log` again to see new instructions at the bottom of the log ---
# --- 4. Repeat until tunnel is fully ready ---

# Open the log file first time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44594144.out 

# --- VS Code tunnel requests GitHub device authentication ---
# --- ACTION: Open a browser and complete authorization using the code shown below ---
To grant access to the server, please log into https://github.com/login/device and use code D9D8-6303

# --- After completing the step above, return and continue ---


# Open the log file second time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44594144.out 

# --- Previous step has been completed ---
# --- Continue following instructions from the log ---
To grant access to the server, please log into https://github.com/login/device and use code D9D8-6303

# --- ACTION ---
# --- If this authorization message appears again and you have NOT completed login, complete it in a browser using the latest code shown ---
# --- If you have already completed authorization, ignore this message and continue ---

*
* Visual Studio Code Server
*
* By using the software, you agree to
* the Visual Studio Code Server License Terms (https://aka.ms/vscode-server-license) and
* the Microsoft Privacy Statement (https://privacy.microsoft.com/en-US/privacystatement).
*

# --- Tunnel provides browser access link ---
# --- ACTION: Open this link in your browser ---
Open this link in your browser https://vscode.dev/tunnel/vscode-tunnel-0416/scratch/zhuofei/VSCode_tunnel

# --- After opening the link, return and continue ---


# Open the log file third time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44594144.out 

# --- Authentication message may still appear ---
# --- No action needed if authorization is already completed ---
To grant access to the server, please log into https://github.com/login/device and use code D9D8-6303

*
* Visual Studio Code Server
*
* License and privacy information
*

# --- Tunnel link remains active ---
# --- ACTION: Ensure your browser is connected using the link above ---
Open this link in your browser https://vscode.dev/tunnel/vscode-tunnel-0416/scratch/zhuofei/VSCode_tunnel

# --- After confirming connection, continue ---


# Open the log file fourth time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44594144.out 

# --- Final stage: client connects to tunnel ---
To grant access to the server, please log into https://github.com/login/device and use code D9D8-6303

*
* Visual Studio Code Server
*
* License and privacy information
*

Open this link in your browser https://vscode.dev/tunnel/vscode-tunnel-0416/scratch/zhuofei/VSCode_tunnel

# --- A client (your browser) connected to the tunnel ---
[2026-04-20 11:06:45] info [tunnels::connections::relay_tunnel_host] Opened new client on channel 2

# --- Internal SSH handshake ---
[2026-04-20 11:06:45] info [russh::server] wrote id
[2026-04-20 11:06:45] info [russh::server] read other id

# --- Tunnel session is active ---
[2026-04-20 11:06:45] info [russh::server] session is running

# --- VS Code checks for existing server ---
[2026-04-20 11:06:45] info [rpc.0] Checking /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/log.txt and /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/pid.txt for a running server...

# --- Starts new server if none exists ---
[2026-04-20 11:06:45] info [rpc.0] Starting server...

# --- VS Code Server successfully started ---
[2026-04-20 11:06:46] info [rpc.0] Server started

# --- DONE: Tunnel is fully ready ---
# --- You can now use VS Code in your browser ---

What Happens Under the Hood When Using VSCode

We would like VSCode users to understand what happens behind the scenes. When VSCode starts (via tunnel or SSH remote connection), it launches multiple backend processes, including:

code-tunnel
code-server
node (server-main.js)
extensionHost
fileWatcher
ptyHost

These components work together to provide remote editing, extension support, terminal access, and file system monitoring.

As a result, VSCode behaves much like a multi-process application server, rather than a simple lightweight editor or a simple SSH tool as many users might expect.

Because of this architecture:

Multiple background processes are always running
CPU and memory are continuously consumed
Resource usage persists even when idle

For this reason, VSCode must be run on compute nodes, not login nodes. Running VSCode directly on login nodes can result in increased CPU load and memory usage, leading to degraded responsiveness for all users.

Please keep the following in mind:

Always treat VSCode as a compute workload
Always run it inside a Slurm allocation, either via an interactive job (as shown above), a batch job, or an Open OnDemand (OOD) VSCode session
Avoid launching it directly on login nodes, especially when using the SSH Remote extension.

Compute Node and Login Node Behavior (Observed)

When your VSCode tunnel (interactive or batch job) is running on a compute node, you can check the related VS Code processes with:

ssh <node> "pgrep -u $USER -af 'code|vscode|node'"

To compare, run the same command on the login node where you started the interactive job or submitted the batch job:

pgrep -u $USER -af "code|vscode|node"