Research Computing Center Wiki - User contributions [en]

Training

2026-08-11T15:31:56Z

Moses:

==GACRC Training==

The GACRC regularly hosts training sessions on a number of subjects relevant to the use of our computational and storage resources. Scheduled trainings will be announced through the GACRC mailing list.

'''NOTE: New users are required to attend a Sapelo2 cluster introductory training session and information about that will be sent once an account is requested.'''

==Regular Training Announcement==

In '''September 2026''', the GACRC is hosting 9 training sessions listed below. These training workshops will be offered remotely via Zoom Meeting. Detailed instructions for joining the Zoom meeting will be sent to your UGA email account before each training session you register for.

We will offer:

1. Linux training for Linux-inexperienced cluster new users (3 sessions)

2. Sapelo2 cluster new user training (3 sessions)

3. Using Sapelo2 Cluster at the GACRC, Part II (1 session)

4. Installing Software Packages in Virtual Environments on Sapelo2 (1 session)

5. Job Parallelization with GNU Parallel and Slurm Arrays (1 session)

==Event Schedule==

This section describes the training workshops that we offer, along with the sessions that are currently scheduled.

===Sapelo2 Cluster New User Training===

This mandatory training consists of an overview of the structure of Sapelo2 as well as hands-on practice submitting a job along with guidance and best practices when using the Sapelo2 cluster.

'''Prerequisites:'''

*Linux basics. A Linux-inexperienced user must complete a prerequisite Linux training for Linux-inexperienced cluster new users.

'''Workshop Training Goals:'''

*Understand the layout of Sapelo2

*Understand the Sapelo2 file systems

*Understand the Sapelo2 partitions

*Understand the Sapelo2 software environment

*Understand how to request computing resources and submit a computational batch job following the Sapelo2 cluster general workflow

*Understand how to initiate an interactive job

*Understand how to transfer files to and from the cluster

*Understand how to get support from GACRC support team when you have any issues on cluster

'''Scheduled Sessions:'''

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
! scope="col" |Title
! scope="col" |Date/Time
|-
|Using Sapelo2 Cluster at the GACRC
|August 20th, Thursday, 2:00 PM - 4:00 PM
|-
|Using Sapelo2 Cluster at the GACRC
|September 11th, Friday, 2:00 PM - 4:00 PM
|-
|Using Sapelo2 Cluster at the GACRC
|September 16th, Wednesday, 2:00 PM - 4:00 PM
|-
|Using Sapelo2 Cluster at the GACRC
|September 24th, Thursday, 2:00 PM - 4:00 PM
|}

===Linux Training for Linux-inexperienced Cluster New Users===
The Sapelo2 High Performance Computing (HPC) cluster runs a headless Linux distribution as the operating system on each of its constituent nodes. The term headless refers to the fact that these nodes do not have a desktop graphical user interface (GUI) installed by default. Graphical desktop environments consume resources that analyses could otherwise use, so users employ a command-line interface (CLI) instead. To interact with these resources, users connect to a remote terminal via SSH and execute commands.

The Linux Training workshop provides hands-on practice of the fundamental Linux commands necessary to interact with HPC resources.

'''Prerequisite:'''

Please watch the introductory videos on Linux, basic Linux terms, and Linux Paths and Directories (total ~17 minutes) '''before attending the training workshop'''.

*[https://kaltura.uga.edu/media/t/1_81u2kfi2/176125031 Linux]
*[https://kaltura.uga.edu/media/t/1_ol51cuyn/176125031 basic Linux terms]
*[https://kaltura.uga.edu/media/t/1_wdyxhgdg/176125031 Linux Paths and Directories]

'''Training Goals:'''

1. Understand fundamental concepts of Linux working environment (filesystem hierarchy, path, PATH, etc.)

2. Know how to use Linux common commands (ls, cd, pwd, cat, more, nano, mkdir, rm, cp, mv, etc.)

3. Understand what is Linux bash shell and know how to make a simple Linux script and run it in Linux environment

'''Scheduled Sessions:'''

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
! scope="col" | Title
! scope="col" |Date/Time
|-
|Use Linux on Cluster
|August 18th, Tuesday, 1:00 PM - 3:00 PM
|-
|Use Linux on Cluster
|September 9th, Wednesday, 1:00 PM - 3:00 PM
|-
|Use Linux on Cluster
|September 14th, Monday, 1:00 PM - 3:00 PM
|-
|Use Linux on Cluster
|September 22nd, Tuesday, 1:00 PM - 3:00 PM
|}

===Using Sapelo2 Cluster at the GACRC, Part II ===
This workshop will cover high-performance computing on Sapelo2, including job scheduling, resource requests (CPU, memory, GPU), and techniques for optimizing job performance.

'''Prerequisites:'''
*Linux basics. A Linux-inexperienced user must complete a prerequisite Linux training for Linux-inexperienced cluster new users.
*Sapelo2 cluster new user training. Fundamental HPC and Sapelo2 knowledge is required for this advanced Sapelo2 workshop.

'''Training Goals:'''

1. Learn about high-performance computing framework

2. Why is my job pending? How can I get my job to start sooner? How to find available computing resources on Sapelo2?

3. How to request computing resources such as nodes, CPU cores, memory, GPU device, etc. to run serial, threaded, MPI, and GPU jobs on Sapelo2?

4. How can I make my job run more efficiently (through the correct use of software and hardware)?

5. A quick intro to MPI library and how to compile/run MPI jobs on Sapelo2

'''Scheduled Sessions:'''

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
! scope="col" |Title
! scope="col" |Date/Time
|-
|Using Sapelo2 Cluster at the GACRC, Part II
|September 18th, Friday, 1:00 PM - 3:00 PM
|}

===Installing Software Packages in Virtual Environments on Sapelo2 ===
This workshop will cover the basics of virtual environments as well as provide practical guidance and best practices for using virtual environments on the Sapelo2 cluster. Participants will learn the basics of creating and configuring virtual environments, how to install software packages in both a Conda virtual environment and a Python virtual environment, and manage dependencies in their environments.

'''Prerequisite:'''

Must already have strong understanding of the Linux environment and Sapelo2.

'''Training Goals:'''

1. Learn how to create a virtual environment on Sapelo2

2. Be able to install software packages into both Conda and Python virtual environments

3. Understand how to manage dependencies of their virtual environments

'''Scheduled Sessions:'''

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
! scope="col" |Title
! scope="col" |Date/Time
|-
|Installing Software Packages in Virtual Environments on Sapelo2
|September 23rd, Wednesday, 2:00 PM - 2:45 PM
|}

===Job Parallelization with GNU Parallel and Slurm Arrays ===
Learn how to run multiple commands in parallel using GNU Parallel and Slurm Arrays. These tools greatly reduce the runtime of certain types of jobs by running multiple instances of the same command in parallel. The workshop focuses on problems that involve executing the same command on multiple different inputs. This workshop is intended for users comfortable writing job submission scripts and using a command line. Concurrent and parallel programming techniques are not covered in this workshop.

'''Prerequisite:'''

Must already have strong understanding of the Linux environment and Sapelo2.

'''Training Goals:'''

1. Understand which jobs benefit from GNU Parallel and Slurm Arrays

2. Use GNU Parallel and Slurm Arrays to parallelize jobs

3. Understand the differences and similarities between GNU Parallel and Slurm Arrays

'''Scheduled Sessions:'''

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
! scope="col" |Title
! scope="col" |Date/Time
|-
|Job Parallelization with GNU Parallel and Slurm Arrays
|September 25th, Friday, 1:00 PM - 3:00 PM
|}



==How to Register==

The training workshops '''Using Sapelo2 Cluster at the GACRC''' and '''Use Linux on Cluster''' are '''ONLY''' offered to '''new users''' who need user accounts on the GACRC Sapelo2 cluster or current Sapelo2 users seeking a refresher. If you would like to use the cluster, please ask your group PI/UGA faculty member to send us an account creation request for you, using the [https://uga.teamdynamix.com/TDClient/Requests/ServiceDet?ID=25839 GACRC User Account Request Form].

If you would like to attend the '''Using Sapelo2 Cluster at the GACRC, Part II''', the '''Installing Software Packages in Virtual Environments on Sapelo2''', and/or the '''Job Parallelization with GNU Parallel and Slurm Arrays''' training workshops, please send us a request using the [https://uga.teamdynamix.com/TDClient/Requests/ServiceDet?ID=25852 GACRC Training Request Form]. In your request, please tell us which session(s) you would like to attend.



== Download==

This section provides the slides that we use for our current workshops and material used for several of our past training events and presentations.

===Sapelo2 Cluster Training===

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|[[Media:GACRC_Sapelo2_cluster_new_user_training_workshop_v10.8.pdf]]
|-
|}

===Teaching Cluster Training===

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
|[[Media:GACRC-Teaching-cluster-new-user-training-workshop-Spring2026.pdf]]
|-
|}

===Linux Training for New Cluster Users===

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
|[[Media:Linux_Training_For_New_Users_Of_Cluster_Suchi_04252019.pdf]]
|-
|}

===Installing Software Packages in Virtual Environments on Sapelo2===

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
|[[Media:GACRC_virtual_environments_training_v1.2.pdf]]
|}

===Job Parallelization with GNU Parallel and Slurm Arrays===

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
|[[Media:GNU_Parallel_and_SLURM_Arrays_v1.1.pdf]]
|}



===Topical Sessions===

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|
|-
|[[Media:AI_Resources_on_the_GACRC_Sapelo2_Cluster.pdf]]
|-
|[[Media:Using_Sapelo2_Cluster_at_the_GACRC_Part_II_Rocky8.pdf]]

|}

===Out-Reach/In-Class Talk===

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
! scope="col" |Dept./Center/Institute
! scope="col" |Type
! scope="col" |Workshop PDF
|-
|Fall 2026
|
|[[Media:GACRC_Teaching_Cluster_Training-Python.pdf]]
|-
|Fall 2026
|
|[[Media:GACRC_Teaching_Cluster_Training-Amber.pdf]]
|-
|GEOG - Spring2026 || In-Class || [[Media:GACRC-Teaching-cluster-new-user-training-workshop-python-Spring2026.pdf]]
|-
|BCMB8330 - Spring2026 || In-Class || [[Media:GACRC-Teaching-cluster-new-user-training-workshop_bcmb8330_Spring2026.pdf]]

|}

'''NOTE:''' The slides may become outdated and you should always check GACRC Wiki for up to date information.

CryoSPARC-Sapelo2

2026-08-05T16:25:51Z

Moses:

[[Category:Sapelo2]][[Category:Software]][[Category:Engineering]]

== Category ==

Engineering

== Program On ==

Sapelo2

== Version ==

4.3.1

== Author / Distributor ==

See https://guide.cryosparc.com/

== Description ==

"CryoSPARC (Cryo-EM Single Particle Ab-Initio Reconstruction and Classification) is a state of the art HPC software solution for complete processing of single-particle cryo-electron microscopy (cryo-EM) data. CryoSPARC is useful for solving cryo-EM structures of membrane proteins, viruses, complexes, flexible molecules, small particles, phase plate data and negative stain data." For more information, please see https://guide.cryosparc.com/.

'''NOTE''': Users are required to be added into GACRC '''cryosparc''' group before they can run this software from Sapelo2. Please fill out the [https://uga.teamdynamix.com/TDClient/2060/Portal/Requests/ServiceDet?ID=25844 GACRC General Support form] to request. We will reach out to you after we received your request.

== Configurations ==
'''Master node VM:'''

* Host name: '''cryosparc.gacrc.uga.edu'''
* Intel Xeon processors (16 cores) and 64GB of RAM
* mongodb is installed and run on the master node
'''Worker nodes:'''
* One NVIDIA Tesla A100 node: Intel Xeon processors (64 cores), 1TB host RAM memory, 4 NVIDIA Tesla A100 GPU cards (80GiB device memory per card), and NVMe SSD 3570GB local drive.
* cryoSPARC recommends using SSD for caching particle data. /lscratch/gacrc-cryo is set up on the worker node for this purpose.
* The amount of space that cryoSPARC can use in /lscratch/gacrc-cryo is capped at 100GB.
'''cryoSPARC group:''' '''cryosparc'''

'''cryoSPARC service account:''' '''gacrc-cryo'''

* gacrc-cryo is the '''service account''' that will run cryoSPARC workflow jobs for all cryoSPARC users.
* Some tasks can only be handled by gacrc-cryo, like make a new lane of worker node(s), user management, and connect or update worker node(s) to master, etc..
* Regular CryoSPARC users can run cryosparcm on the master node to check cryoSPARC status, using cryosparcm status or cryosparcm checkdb.

'''cryoSPARC project space:''' '''/scratch/gacrc-cryo'''

== User Login ==
There are two ways to access the CryoSPARC web interface. The recommended method is to connect through the UGA VPN and access the CryoSPARC web server directly.


=== VPN + Direct Web Access ===
# Connect to the UGA VPN using the Cisco Secure Client (Cisco AnyConnect) and select '''remote.uga.edu'''.
#: '''Note:''' Even if you are working on campus, you must still connect to the UGA VPN before accessing the CryoSPARC web server.
# Open the URL for your assigned CryoSPARC instance in your web browser. For example:
#:
#: <code>http://cryosparc.gacrc.uga.edu:39000</code>
# Log in using your registered UGA email address and CryoSPARC password.
#:
#: '''Note:''' Your registered UGA email address may be an email alias rather than your official '''MyID@uga.edu''' address. Please use the email address that was registered with your CryoSPARC account.



























=== Troubleshooting ===
If you are unable to access the CryoSPARC web interface:

* Verify that you are connected to the UGA VPN if you are using the recommended VPN + Direct Web Access method.
* Confirm that you are using the correct URL for your assigned CryoSPARC instance.
* Make sure you are logging in with your registered UGA email address and CryoSPARC password. Your registered UGA email address may be an email alias rather than your official MyID@uga.edu address.
* If you are using the SSH tunnel method, ensure that the SSH session remains active while accessing the web interface.
* If you have forgotten your CryoSPARC password, contact GACRC Support to request a password reset token.
* If the problem persists, please contact GACRC Support and include:
** The URL you are using to access CryoSPARC.
** Your UGA MyID and your registered UGA email address.
** A screenshot of the error message or the login/password reset screen, if applicable.

== Run cryoSPARC workflow jobs ==

=== Project space selection ===
A project in cryoSPARC is a high level container corresponding with a project directory on the file system, which stores all associated Jobs of a project. Each project in cryoSPARC is entirely contained within a file system directory. All the jobs and their respective intermediate and output data created within a project will be stored within the project directory.

* When you start a new project in cryoSPARC GUI, please select and use '''/scratch/gacrc-cryo''' as the cryoSPARC project space.
* This folder is owned by gacrc-cryo. Regular cryoSPARC users have access and read permissions which allow them to browse files in this folder and copy files from this folder to their own storage spaces on Sapelo2.

=== Run job on the master node ===
cryoSPARC will use the master node to run some types of workflow jobs, for example, "Import Movies", "Inspect Picks", and the interactive job "Select 2D Classes". When a job is created, if cryoSPARC will use the master node to run the job, you will be notified about this in cryoSPARC GUI.

=== Run job using "Lane Sapelo2 Default (cluster)" ===
* In cryoSPARC, queue a job to "'''Lane Sapelo2 Default (cluster)'''"; The job will be dispatched to the worker node via Slurm. Please note, gacrc-cryo, instead of your own Sapelo2 user account, is the user account owning and running the job. We highly recommend you to use this method to run cryoSPARC workflow jobs on Sapelo2.
* cryoSPARC will decide on how many CPU cores and how much memory it will use to run a workflow job, depend on the type of the job and your data size. Currently, we configured that from each worker node cryoSPARC can use up to '''20GB''' memory and '''4''' CPU cores.
* If the job needs to run on GPU devices, cryoSPARC will queue the job with a default number of GPU devices , for example 1. You can change this number by yourself in cryoSPARC GUI when you create the job. Please note that the maximum number of GPU devices installed on the worker node is '''4'''.

==Documentation (v4.0+)==

About cryoSPARC: https://guide.cryosparc.com/

Get Started with CryoSPARC: Introductory Tutorial: https://guide.cryosparc.com/processing-data/get-started-with-cryosparc-introductory-tutorial

A Tour of the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/a-tour-of-the-cryosparc-interface

Using the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/using-the-cryosparc-interface

Creating and Running Jobs: https://guide.cryosparc.com/application-guide-v4.0+/creating-and-running-jobs

Tutorial videos: https://guide.cryosparc.com/processing-data/tutorial-videos

==Installation==

*Version 4.3.1 master is installed on the master node (cryosparc.gacrc.uga.edu).
*Version 4.3.1 workers are installed on one worker GPU node (NVIDIA Tesla A100 GPU node).

==System==
64-bit Linux

CryoSPARC-Sapelo2

2026-08-05T16:25:10Z

Moses:

[[Category:Sapelo2]][[Category:Software]][[Category:Engineering]]

== Category ==

Engineering

== Program On ==

Sapelo2

== Version ==

4.3.1

== Author / Distributor ==

See https://guide.cryosparc.com/

== Description ==

"CryoSPARC (Cryo-EM Single Particle Ab-Initio Reconstruction and Classification) is a state of the art HPC software solution for complete processing of single-particle cryo-electron microscopy (cryo-EM) data. CryoSPARC is useful for solving cryo-EM structures of membrane proteins, viruses, complexes, flexible molecules, small particles, phase plate data and negative stain data." For more information, please see https://guide.cryosparc.com/.

'''NOTE''': Users are required to be added into GACRC '''cryosparc''' group before they can run this software from Sapelo2. Please fill out the [https://uga.teamdynamix.com/TDClient/2060/Portal/Requests/ServiceDet?ID=25844 GACRC General Support form] to request. We will reach out to you after we received your request.

== Configurations ==
'''Master node VM:'''

* Host name: '''cryosparc.gacrc.uga.edu'''
* Intel Xeon processors (16 cores) and 64GB of RAM
* mongodb is installed and run on the master node
'''Worker nodes:'''
* One NVIDIA Tesla A100 node: Intel Xeon processors (64 cores), 1TB host RAM memory, 4 NVIDIA Tesla A100 GPU cards (80GiB device memory per card), and NVMe SSD 3570GB local drive.
* cryoSPARC recommends using SSD for caching particle data. /lscratch/gacrc-cryo is set up on the worker node for this purpose.
* The amount of space that cryoSPARC can use in /lscratch/gacrc-cryo is capped at 100GB.
'''cryoSPARC group:''' '''cryosparc'''

'''cryoSPARC service account:''' '''gacrc-cryo'''

* gacrc-cryo is the '''service account''' that will run cryoSPARC workflow jobs for all cryoSPARC users.
* Some tasks can only be handled by gacrc-cryo, like make a new lane of worker node(s), user management, and connect or update worker node(s) to master, etc..
* Regular CryoSPARC users can run cryosparcm on the master node to check cryoSPARC status, using cryosparcm status or cryosparcm checkdb.

'''cryoSPARC project space:''' '''/scratch/gacrc-cryo'''

== User Login ==
There are two ways to access the CryoSPARC web interface. The recommended method is to connect through the UGA VPN and access the CryoSPARC web server directly.


=== VPN + Direct Web Access ===
# Connect to the UGA VPN using the Cisco Secure Client (Cisco AnyConnect) and select '''remote.uga.edu'''.
#: '''Note:''' Even if you are working on campus, you must still connect to the UGA VPN before accessing the CryoSPARC web server.
# Open the URL for your assigned CryoSPARC instance in your web browser. For example:
#:
#: <code>http://cryosparc.gacrc.uga.edu:39000</code>
# Log in using your registered UGA email address and CryoSPARC password.
#:
#: '''Note:''' Your registered UGA email address may be an email alias rather than your official '''MyID@uga.edu''' address. Please use the email address that was registered with your CryoSPARC account.




























=== Troubleshooting ===
If you are unable to access the CryoSPARC web interface:

* Verify that you are connected to the UGA VPN if you are using the recommended VPN + Direct Web Access method.
* Confirm that you are using the correct URL for your assigned CryoSPARC instance.
* Make sure you are logging in with your registered UGA email address and CryoSPARC password. Your registered UGA email address may be an email alias rather than your official MyID@uga.edu address.
* If you are using the SSH tunnel method, ensure that the SSH session remains active while accessing the web interface.
* If you have forgotten your CryoSPARC password, contact GACRC Support to request a password reset token.
* If the problem persists, please contact GACRC Support and include:
** The URL you are using to access CryoSPARC.
** Your UGA MyID and your registered UGA email address.
** A screenshot of the error message or the login/password reset screen, if applicable.

== Run cryoSPARC workflow jobs ==

=== Project space selection ===
A project in cryoSPARC is a high level container corresponding with a project directory on the file system, which stores all associated Jobs of a project. Each project in cryoSPARC is entirely contained within a file system directory. All the jobs and their respective intermediate and output data created within a project will be stored within the project directory.

* When you start a new project in cryoSPARC GUI, please select and use '''/scratch/gacrc-cryo''' as the cryoSPARC project space.
* This folder is owned by gacrc-cryo. Regular cryoSPARC users have access and read permissions which allow them to browse files in this folder and copy files from this folder to their own storage spaces on Sapelo2.

=== Run job on the master node ===
cryoSPARC will use the master node to run some types of workflow jobs, for example, "Import Movies", "Inspect Picks", and the interactive job "Select 2D Classes". When a job is created, if cryoSPARC will use the master node to run the job, you will be notified about this in cryoSPARC GUI.

=== Run job using "Lane Sapelo2 Default (cluster)" ===
* In cryoSPARC, queue a job to "'''Lane Sapelo2 Default (cluster)'''"; The job will be dispatched to the worker node via Slurm. Please note, gacrc-cryo, instead of your own Sapelo2 user account, is the user account owning and running the job. We highly recommend you to use this method to run cryoSPARC workflow jobs on Sapelo2.
* cryoSPARC will decide on how many CPU cores and how much memory it will use to run a workflow job, depend on the type of the job and your data size. Currently, we configured that from each worker node cryoSPARC can use up to '''20GB''' memory and '''4''' CPU cores.
* If the job needs to run on GPU devices, cryoSPARC will queue the job with a default number of GPU devices , for example 1. You can change this number by yourself in cryoSPARC GUI when you create the job. Please note that the maximum number of GPU devices installed on the worker node is '''4'''.

==Documentation (v4.0+)==

About cryoSPARC: https://guide.cryosparc.com/

Get Started with CryoSPARC: Introductory Tutorial: https://guide.cryosparc.com/processing-data/get-started-with-cryosparc-introductory-tutorial

A Tour of the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/a-tour-of-the-cryosparc-interface

Using the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/using-the-cryosparc-interface

Creating and Running Jobs: https://guide.cryosparc.com/application-guide-v4.0+/creating-and-running-jobs

Tutorial videos: https://guide.cryosparc.com/processing-data/tutorial-videos

==Installation==

*Version 4.3.1 master is installed on the master node (cryosparc.gacrc.uga.edu).
*Version 4.3.1 workers are installed on one worker GPU node (NVIDIA Tesla A100 GPU node).

==System==
64-bit Linux

CryoSPARC-Sapelo2

2026-08-05T16:24:12Z

Moses:

[[Category:Sapelo2]][[Category:Software]][[Category:Engineering]]

== Category ==

Engineering

== Program On ==

Sapelo2

== Version ==

4.3.1

== Author / Distributor ==

See https://guide.cryosparc.com/

== Description ==

"CryoSPARC (Cryo-EM Single Particle Ab-Initio Reconstruction and Classification) is a state of the art HPC software solution for complete processing of single-particle cryo-electron microscopy (cryo-EM) data. CryoSPARC is useful for solving cryo-EM structures of membrane proteins, viruses, complexes, flexible molecules, small particles, phase plate data and negative stain data." For more information, please see https://guide.cryosparc.com/.

'''NOTE''': Users are required to be added into GACRC '''cryosparc''' group before they can run this software from Sapelo2. Please fill out the [https://uga.teamdynamix.com/TDClient/2060/Portal/Requests/ServiceDet?ID=25844 GACRC General Support form] to request. We will reach out to you after we received your request.

== Configurations ==
'''Master node VM:'''

* Host name: '''cryosparc.gacrc.uga.edu'''
* Intel Xeon processors (16 cores) and 64GB of RAM
* mongodb is installed and run on the master node
'''Worker nodes:'''
* One NVIDIA Tesla A100 node: Intel Xeon processors (64 cores), 1TB host RAM memory, 4 NVIDIA Tesla A100 GPU cards (80GiB device memory per card), and NVMe SSD 3570GB local drive.
* cryoSPARC recommends using SSD for caching particle data. /lscratch/gacrc-cryo is set up on the worker node for this purpose.
* The amount of space that cryoSPARC can use in /lscratch/gacrc-cryo is capped at 100GB.
'''cryoSPARC group:''' '''cryosparc'''

'''cryoSPARC service account:''' '''gacrc-cryo'''

* gacrc-cryo is the '''service account''' that will run cryoSPARC workflow jobs for all cryoSPARC users.
* Some tasks can only be handled by gacrc-cryo, like make a new lane of worker node(s), user management, and connect or update worker node(s) to master, etc..
* Regular CryoSPARC users can run cryosparcm on the master node to check cryoSPARC status, using cryosparcm status or cryosparcm checkdb.

'''cryoSPARC project space:''' '''/scratch/gacrc-cryo'''

== User Login ==
There are two ways to access the CryoSPARC web interface. The recommended method is to connect through the UGA VPN and access the CryoSPARC web server directly. SSH tunneling remains available as an alternative if needed.

=== VPN + Direct Web Access ===
# Connect to the UGA VPN using the Cisco Secure Client (Cisco AnyConnect) and select '''remote.uga.edu'''.
#: '''Note:''' Even if you are working on campus, you must still connect to the UGA VPN before accessing the CryoSPARC web server.
# Open the URL for your assigned CryoSPARC instance in your web browser. For example:
#:
#: <code>http://cryosparc.gacrc.uga.edu:39000</code>
# Log in using your registered UGA email address and CryoSPARC password.
#:
#: '''Note:''' Your registered UGA email address may be an email alias rather than your official '''MyID@uga.edu''' address. Please use the email address that was registered with your CryoSPARC account.




























=== Troubleshooting ===
If you are unable to access the CryoSPARC web interface:

* Verify that you are connected to the UGA VPN if you are using the recommended VPN + Direct Web Access method.
* Confirm that you are using the correct URL for your assigned CryoSPARC instance.
* Make sure you are logging in with your registered UGA email address and CryoSPARC password. Your registered UGA email address may be an email alias rather than your official MyID@uga.edu address.
* If you are using the SSH tunnel method, ensure that the SSH session remains active while accessing the web interface.
* If you have forgotten your CryoSPARC password, contact GACRC Support to request a password reset token.
* If the problem persists, please contact GACRC Support and include:
** The URL you are using to access CryoSPARC.
** Your UGA MyID and your registered UGA email address.
** A screenshot of the error message or the login/password reset screen, if applicable.

== Run cryoSPARC workflow jobs ==

=== Project space selection ===
A project in cryoSPARC is a high level container corresponding with a project directory on the file system, which stores all associated Jobs of a project. Each project in cryoSPARC is entirely contained within a file system directory. All the jobs and their respective intermediate and output data created within a project will be stored within the project directory.

* When you start a new project in cryoSPARC GUI, please select and use '''/scratch/gacrc-cryo''' as the cryoSPARC project space.
* This folder is owned by gacrc-cryo. Regular cryoSPARC users have access and read permissions which allow them to browse files in this folder and copy files from this folder to their own storage spaces on Sapelo2.

=== Run job on the master node ===
cryoSPARC will use the master node to run some types of workflow jobs, for example, "Import Movies", "Inspect Picks", and the interactive job "Select 2D Classes". When a job is created, if cryoSPARC will use the master node to run the job, you will be notified about this in cryoSPARC GUI.

=== Run job using "Lane Sapelo2 Default (cluster)" ===
* In cryoSPARC, queue a job to "'''Lane Sapelo2 Default (cluster)'''"; The job will be dispatched to the worker node via Slurm. Please note, gacrc-cryo, instead of your own Sapelo2 user account, is the user account owning and running the job. We highly recommend you to use this method to run cryoSPARC workflow jobs on Sapelo2.
* cryoSPARC will decide on how many CPU cores and how much memory it will use to run a workflow job, depend on the type of the job and your data size. Currently, we configured that from each worker node cryoSPARC can use up to '''20GB''' memory and '''4''' CPU cores.
* If the job needs to run on GPU devices, cryoSPARC will queue the job with a default number of GPU devices , for example 1. You can change this number by yourself in cryoSPARC GUI when you create the job. Please note that the maximum number of GPU devices installed on the worker node is '''4'''.

==Documentation (v4.0+)==

About cryoSPARC: https://guide.cryosparc.com/

Get Started with CryoSPARC: Introductory Tutorial: https://guide.cryosparc.com/processing-data/get-started-with-cryosparc-introductory-tutorial

A Tour of the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/a-tour-of-the-cryosparc-interface

Using the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/using-the-cryosparc-interface

Creating and Running Jobs: https://guide.cryosparc.com/application-guide-v4.0+/creating-and-running-jobs

Tutorial videos: https://guide.cryosparc.com/processing-data/tutorial-videos

==Installation==

*Version 4.3.1 master is installed on the master node (cryosparc.gacrc.uga.edu).
*Version 4.3.1 workers are installed on one worker GPU node (NVIDIA Tesla A100 GPU node).

==System==
64-bit Linux

CryoSPARC-Sapelo2

2026-08-05T16:23:43Z

Moses:

[[Category:Sapelo2]][[Category:Software]][[Category:Engineering]]

== Category ==

Engineering

== Program On ==

Sapelo2

== Version ==

4.3.1

== Author / Distributor ==

See https://guide.cryosparc.com/

== Description ==

"CryoSPARC (Cryo-EM Single Particle Ab-Initio Reconstruction and Classification) is a state of the art HPC software solution for complete processing of single-particle cryo-electron microscopy (cryo-EM) data. CryoSPARC is useful for solving cryo-EM structures of membrane proteins, viruses, complexes, flexible molecules, small particles, phase plate data and negative stain data." For more information, please see https://guide.cryosparc.com/.

'''NOTE''': Users are required to be added into GACRC '''cryosparc''' group before they can run this software from Sapelo2. Please fill out the [https://uga.teamdynamix.com/TDClient/2060/Portal/Requests/ServiceDet?ID=25844 GACRC General Support form] to request. We will reach out to you after we received your request.

== Configurations ==
'''Master node VM:'''

* Host name: '''cryosparc.gacrc.uga.edu'''
* Intel Xeon processors (16 cores) and 64GB of RAM
* mongodb is installed and run on the master node
'''Worker nodes:'''
* One NVIDIA Tesla A100 node: Intel Xeon processors (64 cores), 1TB host RAM memory, 4 NVIDIA Tesla A100 GPU cards (80GiB device memory per card), and NVMe SSD 3570GB local drive.
* cryoSPARC recommends using SSD for caching particle data. /lscratch/gacrc-cryo is set up on the worker node for this purpose.
* The amount of space that cryoSPARC can use in /lscratch/gacrc-cryo is capped at 100GB.
'''cryoSPARC group:''' '''cryosparc'''

'''cryoSPARC service account:''' '''gacrc-cryo'''

* gacrc-cryo is the '''service account''' that will run cryoSPARC workflow jobs for all cryoSPARC users.
* Some tasks can only be handled by gacrc-cryo, like make a new lane of worker node(s), user management, and connect or update worker node(s) to master, etc..
* Regular CryoSPARC users can run cryosparcm on the master node to check cryoSPARC status, using cryosparcm status or cryosparcm checkdb.

'''cryoSPARC project space:''' '''/scratch/gacrc-cryo'''

== User Login ==
There are two ways to access the CryoSPARC web interface. The recommended method is to connect through the UGA VPN and access the CryoSPARC web server directly. SSH tunneling remains available as an alternative if needed.

=== Method 1 (Recommended): VPN + Direct Web Access ===
# Connect to the UGA VPN using the Cisco Secure Client (Cisco AnyConnect) and select '''remote.uga.edu'''.
#: '''Note:''' Even if you are working on campus, you must still connect to the UGA VPN before accessing the CryoSPARC web server.
# Open the URL for your assigned CryoSPARC instance in your web browser. For example:
#:
#: <code>http://cryosparc.gacrc.uga.edu:39000</code>
# Log in using your registered UGA email address and CryoSPARC password.
#:
#: '''Note:''' Your registered UGA email address may be an email alias rather than your official '''MyID@uga.edu''' address. Please use the email address that was registered with your CryoSPARC account.




























=== Troubleshooting ===
If you are unable to access the CryoSPARC web interface:

* Verify that you are connected to the UGA VPN if you are using the recommended VPN + Direct Web Access method.
* Confirm that you are using the correct URL for your assigned CryoSPARC instance.
* Make sure you are logging in with your registered UGA email address and CryoSPARC password. Your registered UGA email address may be an email alias rather than your official MyID@uga.edu address.
* If you are using the SSH tunnel method, ensure that the SSH session remains active while accessing the web interface.
* If you have forgotten your CryoSPARC password, contact GACRC Support to request a password reset token.
* If the problem persists, please contact GACRC Support and include:
** The URL you are using to access CryoSPARC.
** Your UGA MyID and your registered UGA email address.
** A screenshot of the error message or the login/password reset screen, if applicable.

== Run cryoSPARC workflow jobs ==

=== Project space selection ===
A project in cryoSPARC is a high level container corresponding with a project directory on the file system, which stores all associated Jobs of a project. Each project in cryoSPARC is entirely contained within a file system directory. All the jobs and their respective intermediate and output data created within a project will be stored within the project directory.

* When you start a new project in cryoSPARC GUI, please select and use '''/scratch/gacrc-cryo''' as the cryoSPARC project space.
* This folder is owned by gacrc-cryo. Regular cryoSPARC users have access and read permissions which allow them to browse files in this folder and copy files from this folder to their own storage spaces on Sapelo2.

=== Run job on the master node ===
cryoSPARC will use the master node to run some types of workflow jobs, for example, "Import Movies", "Inspect Picks", and the interactive job "Select 2D Classes". When a job is created, if cryoSPARC will use the master node to run the job, you will be notified about this in cryoSPARC GUI.

=== Run job using "Lane Sapelo2 Default (cluster)" ===
* In cryoSPARC, queue a job to "'''Lane Sapelo2 Default (cluster)'''"; The job will be dispatched to the worker node via Slurm. Please note, gacrc-cryo, instead of your own Sapelo2 user account, is the user account owning and running the job. We highly recommend you to use this method to run cryoSPARC workflow jobs on Sapelo2.
* cryoSPARC will decide on how many CPU cores and how much memory it will use to run a workflow job, depend on the type of the job and your data size. Currently, we configured that from each worker node cryoSPARC can use up to '''20GB''' memory and '''4''' CPU cores.
* If the job needs to run on GPU devices, cryoSPARC will queue the job with a default number of GPU devices , for example 1. You can change this number by yourself in cryoSPARC GUI when you create the job. Please note that the maximum number of GPU devices installed on the worker node is '''4'''.

==Documentation (v4.0+)==

About cryoSPARC: https://guide.cryosparc.com/

Get Started with CryoSPARC: Introductory Tutorial: https://guide.cryosparc.com/processing-data/get-started-with-cryosparc-introductory-tutorial

A Tour of the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/a-tour-of-the-cryosparc-interface

Using the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/using-the-cryosparc-interface

Creating and Running Jobs: https://guide.cryosparc.com/application-guide-v4.0+/creating-and-running-jobs

Tutorial videos: https://guide.cryosparc.com/processing-data/tutorial-videos

==Installation==

*Version 4.3.1 master is installed on the master node (cryosparc.gacrc.uga.edu).
*Version 4.3.1 workers are installed on one worker GPU node (NVIDIA Tesla A100 GPU node).

==System==
64-bit Linux

CryoSPARC-Sapelo2

2026-08-05T16:19:00Z

Moses:

[[Category:Sapelo2]][[Category:Software]][[Category:Engineering]]

== Category ==

Engineering

== Program On ==

Sapelo2

== Version ==

4.3.1

== Author / Distributor ==

See https://guide.cryosparc.com/

== Description ==

"CryoSPARC (Cryo-EM Single Particle Ab-Initio Reconstruction and Classification) is a state of the art HPC software solution for complete processing of single-particle cryo-electron microscopy (cryo-EM) data. CryoSPARC is useful for solving cryo-EM structures of membrane proteins, viruses, complexes, flexible molecules, small particles, phase plate data and negative stain data." For more information, please see https://guide.cryosparc.com/.

'''NOTE''': Users are required to be added into GACRC '''cryosparc''' group before they can run this software from Sapelo2. Please fill out the [https://uga.teamdynamix.com/TDClient/2060/Portal/Requests/ServiceDet?ID=25844 GACRC General Support form] to request. We will reach out to you after we received your request.

== Configurations ==
'''Master node VM:'''

* Host name: '''cryosparc.gacrc.uga.edu'''
* Intel Xeon processors (16 cores) and 64GB of RAM
* mongodb is installed and run on the master node
'''Worker nodes:'''
* One NVIDIA Tesla A100 node: Intel Xeon processors (64 cores), 1TB host RAM memory, 4 NVIDIA Tesla A100 GPU cards (80GiB device memory per card), and NVMe SSD 3570GB local drive.
* cryoSPARC recommends using SSD for caching particle data. /lscratch/gacrc-cryo is set up on the worker node for this purpose.
* The amount of space that cryoSPARC can use in /lscratch/gacrc-cryo is capped at 100GB.
'''cryoSPARC group:''' '''cryosparc'''

'''cryoSPARC service account:''' '''gacrc-cryo'''

* gacrc-cryo is the '''service account''' that will run cryoSPARC workflow jobs for all cryoSPARC users.
* Some tasks can only be handled by gacrc-cryo, like make a new lane of worker node(s), user management, and connect or update worker node(s) to master, etc..
* Regular CryoSPARC users can run cryosparcm on the master node to check cryoSPARC status, using cryosparcm status or cryosparcm checkdb.

'''cryoSPARC project space:''' '''/scratch/gacrc-cryo'''

== User Login ==
There are two ways to access the CryoSPARC web interface. The recommended method is to connect through the UGA VPN and access the CryoSPARC web server directly. SSH tunneling remains available as an alternative if needed.

=== Method 1 (Recommended): VPN + Direct Web Access ===
# Connect to the UGA VPN using the Cisco Secure Client (Cisco AnyConnect) and select '''remote.uga.edu'''.
#: '''Note:''' Even if you are working on campus, you must still connect to the UGA VPN before accessing the CryoSPARC web server.
# Open the URL for your assigned CryoSPARC instance in your web browser. For example:
#:
#: <code>http://cryosparc.gacrc.uga.edu:39000</code>
# Log in using your registered UGA email address and CryoSPARC password.
#:
#: '''Note:''' Your registered UGA email address may be an email alias rather than your official '''MyID@uga.edu''' address. Please use the email address that was registered with your CryoSPARC account.

!=== Method 2: SSH Tunnel ===
!Users may also access CryoSPARC by establishing an SSH tunnel to expose port 39000 from the CryoSPARC master node to their local computer.
!
!If you are using Linux or macOS, run the following command in a terminal:
!
!<pre>
!ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu
!</pre>
!
!If you are using Windows, download '''[https://the.earth.li/~sgtatham/putty/latest/x86/plink.exe plink program]''' and run:
!
!<pre>
!plink -ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu
!</pre>

!Place <code>plink.exe</code> in your current working directory, or specify its full path when running the command.

!Unless you have configured SSH public key authentication, you will be prompted for your UGA MyID password and Duo authentication. After authentication succeeds, the SSH session will remain open. This is expected !and indicates that the tunnel has been established successfully.

!With the SSH tunnel active, open your web browser and navigate to:

!<pre>
!http://localhost:39000
!</pre>

!The CryoSPARC login page should appear.

=== Troubleshooting ===
If you are unable to access the CryoSPARC web interface:

* Verify that you are connected to the UGA VPN if you are using the recommended VPN + Direct Web Access method.
* Confirm that you are using the correct URL for your assigned CryoSPARC instance.
* Make sure you are logging in with your registered UGA email address and CryoSPARC password. Your registered UGA email address may be an email alias rather than your official MyID@uga.edu address.
* If you are using the SSH tunnel method, ensure that the SSH session remains active while accessing the web interface.
* If you have forgotten your CryoSPARC password, contact GACRC Support to request a password reset token.
* If the problem persists, please contact GACRC Support and include:
** The URL you are using to access CryoSPARC.
** Your UGA MyID and your registered UGA email address.
** A screenshot of the error message or the login/password reset screen, if applicable.

== Run cryoSPARC workflow jobs ==

=== Project space selection ===
A project in cryoSPARC is a high level container corresponding with a project directory on the file system, which stores all associated Jobs of a project. Each project in cryoSPARC is entirely contained within a file system directory. All the jobs and their respective intermediate and output data created within a project will be stored within the project directory.

* When you start a new project in cryoSPARC GUI, please select and use '''/scratch/gacrc-cryo''' as the cryoSPARC project space.
* This folder is owned by gacrc-cryo. Regular cryoSPARC users have access and read permissions which allow them to browse files in this folder and copy files from this folder to their own storage spaces on Sapelo2.

=== Run job on the master node ===
cryoSPARC will use the master node to run some types of workflow jobs, for example, "Import Movies", "Inspect Picks", and the interactive job "Select 2D Classes". When a job is created, if cryoSPARC will use the master node to run the job, you will be notified about this in cryoSPARC GUI.

=== Run job using "Lane Sapelo2 Default (cluster)" ===
* In cryoSPARC, queue a job to "'''Lane Sapelo2 Default (cluster)'''"; The job will be dispatched to the worker node via Slurm. Please note, gacrc-cryo, instead of your own Sapelo2 user account, is the user account owning and running the job. We highly recommend you to use this method to run cryoSPARC workflow jobs on Sapelo2.
* cryoSPARC will decide on how many CPU cores and how much memory it will use to run a workflow job, depend on the type of the job and your data size. Currently, we configured that from each worker node cryoSPARC can use up to '''20GB''' memory and '''4''' CPU cores.
* If the job needs to run on GPU devices, cryoSPARC will queue the job with a default number of GPU devices , for example 1. You can change this number by yourself in cryoSPARC GUI when you create the job. Please note that the maximum number of GPU devices installed on the worker node is '''4'''.

==Documentation (v4.0+)==

About cryoSPARC: https://guide.cryosparc.com/

Get Started with CryoSPARC: Introductory Tutorial: https://guide.cryosparc.com/processing-data/get-started-with-cryosparc-introductory-tutorial

A Tour of the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/a-tour-of-the-cryosparc-interface

Using the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/using-the-cryosparc-interface

Creating and Running Jobs: https://guide.cryosparc.com/application-guide-v4.0+/creating-and-running-jobs

Tutorial videos: https://guide.cryosparc.com/processing-data/tutorial-videos

==Installation==

*Version 4.3.1 master is installed on the master node (cryosparc.gacrc.uga.edu).
*Version 4.3.1 workers are installed on one worker GPU node (NVIDIA Tesla A100 GPU node).

==System==
64-bit Linux

Software

2026-07-22T12:23:09Z

Moses:

On Sapelo2 and on the Teaching cluster users have the option to install their own software or use software installed centrally by the GACRC staff. Detailed information on how to find and access software packages installed on Sapelo2 are available at the [[Software on Sapelo2]] page and on the teaching cluster at the [[Software on Teaching Cluster]] page.

Below is a very limited list of software packages installed on Sapelo2 and on the Teaching cluster. We only intend to make an application page for software packages that requires extra documentation not covered in [[Software on Sapelo2]] or [[Software on Teaching Cluster]].

To view a list of all modules installed on Sapelo2/Teaching, along with a short description of each module, please run the following command on Sapelo2/Teaching:
<pre class="gcommand">
module spider
</pre>
You can also use the command above to search for a specific application. For more information, please see [[Lmod]].

The '''file transfer''' nodes ('''xfer''' nodes) do not have environment modules installed. File transfer utilities are installed centrally on the xfer nodes and available on the users' default PATH. Such utilities include bs (basespace-cli), fpsync, rclone, rsync, etc.
https://wiki.gacrc.uga.edu/wiki/Main_Page

'''Note:''' Although we have not made individual software pages for the applications installed on Sapelo2, there are currently over 1300 software packages installed there. For more information, please see [[Software on Sapelo2]].

==Partial List of Installed Software==
Last updated '''{{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}}'''. This is a partial list of installed software so there may be software or versions of software available on Sapelo2 which are not included in this table.
'''Note:''' Click on the icons to the right of the column headings to sort the table.
[[#0|0-9]] [[#A|A]] [[#B|B]] [[#C|C]] [[#D|D]] [[#E|E]] [[#F|F]] [[#G|G]] [[#H|H]] [[#I|I]] [[#J|J]] [[#K|K]] [[#L|L]] [[#M|M]] [[#N|N]] [[#O|O]] [[#P|P]] [[#Q|Q]] [[#R|R]] [[#S|S]] [[#T|T]] [[#U|U]] [[#V|V]] [[#W|W]] [[#X|X]] [[#Y|Y]] [[#Z|Z]]
{| width="100%" border="1" cellspacing="0" cellpadding="2" align="center" class="wikitable sortable"
|-
! scope="col" width="200px"| Name
! scope="col" class="unsortable" width="240px"| Version
! scope="col" width="160px"| Category
! scope="col" width="60px"| Cluster
! scope="col" width="20px"| Top
|-













| [[AlphaFold-Sapelo2|AlphaFold 2]] || 2.3.1, 2.3.2 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-
|- -->
| [[AlphaFold3-Sapelo2|AlphaFold 3]] || 3.0.0, 3.0.1 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-





| [[AMBER-Sapelo2|AMBER]] || 22.4, 24.3 || [[:Category:Chemistry|Chemistry]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->








| [[anvi'o-Sapelo2|anvi'o]] || 4, 5.1, 5.3, 5.4, 6.1, 7, 7.1 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:sapelo2|sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->














| | [[Bactopia-Sapelo2|Bactopia]] || 3.2.0, 4.0.0 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->


| [[basespace-cli-Sapelo2|basespace-cli]] || 1.2.1, 1.7.0 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->










|[[Beast-Sapelo2|Beast]] || 1.10.4, 2.6.7, 2.7.3, 2.7.7, 10.5.0 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->










| [[BioPython-Sapelo2|BioPython]] || 1.76, 1.79, 1.80, 1.83, 1.84, 1.85 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
|[[Biopython-Teaching|Biopython]] || 1.76, 1.79, 1.80, 1.83, 1.84, 1.85 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-




| [[BLAST+-Sapelo2|BLAST+]] || 2.13.0, 2.14.1, 2.16.0, 2.17.0 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] ||[[File:Up20.png|20px|link=#top]]
|- -->
| [[BLAST+-Teaching|BLAST+]] || 2.13.0, 2.14.1, 2.16.0, 2.17.0 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-








| [[Bowtie2-Sapelo2|Bowtie2]] || 2.4.4, 2.4.5, 2.5.1, 2.5.2, 2.5.4 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[Bowtie2-Teaching|Bowtie2]] || 2.4.4, 2.4.5, 2.5.1, 2.5.2, 2.5.4 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-

| [[Bracken-Sapelo2|Bracken]] || 3.1 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[BRAKER-Sapelo2|BRAKER]] || 3.0.8 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-



| [[BUSCO-Sapelo2|BUSCO]] || 5.8.3, 6.0.0 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-




| [[Cactus-Sapelo2|Cactus]] || 1.2.3, 2.0.3, 2.4.3, 2.4.4, 2.5.0, 2.6.0, 2.6.7, 2.6.9, 2.7.0, 2.9.0, 2.9.3, 2.9.9, 3.0.0 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-

| [[Canu-Sapelo2|Canu]] || 2.3||[[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-









| [[CellRanger-ATAC-Sapelo2|CellRanger-ATAC]] || 2.1.0 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->








| [[Chimera-Teaching|Chimera]] || 1.16 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-























| [[cryoSPARC-Sapelo2|CryoSPARC]] || 3.3.1 || [[:Category:Engineering|Engineering]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-
| [[Cromwell-Sapelo2|Cromwell]] || 56 || [[:Category:Tools|Tools]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-
|[[CUDA-Sapelo2|CUDA]] || 11.7.0, 11.8.0, 12.1.1, 12.4.0, 12.6.0, 12.8.0, 13.1.0 ||[[:Category:Programming|Programming]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-







| [[Cytoscape-Sapelo2|Cytoscape]] || 3.9.1, 3.10.4 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[Cytoscape-Teaching|Cytoscape]] || 3.9.1, 3.10.4 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-



























|-->
| [[dMRIharmonization-Sapelo2|dMRIharmonization]] || 20240227 || [[:Category:Engineering|Engineering]]|| [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-->





| [[EGAPx-Sapelo2|EGAPx]] || N/A || [[:Category:Bioinformatics|Bioinformatics]] || N/A || [[File:Up20.png|20px|link=#top]]
|- -->


| [[EIGENSOFT-Sapelo2|EIGENSOFT]] || 7.2.1 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[EIGENSOFT-Teaching|EIGENSOFT]] || 7.2.1 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-
| [[Flankophile-Sapelo2|Flankophile]] || N/A || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-






































|-
| [[Funannotate-Sapelo2|Funannotate]] || 1.8.15, 1.8.17 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-
|- -->













| [[GAUSSIAN-Sapelo2|GAUSSIAN]] || 09, 16 || [[:Category:Chemistry|Chemistry]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
|[[GAUSSIAN-Teaching|GAUSSIAN]] || 09, 16 || [[:Category:Chemistry|Chemistry]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-
| [[GaussView-Sapelo2|GaussView]] || 5, 6.1 || [[:Category:Chemistry|Chemistry]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[GaussView-Teaching|GaussView]] || 6.1 || [[:Category:Chemistry|Chemistry]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-







| [[GEM-Sapelo2|GEM]] || 1.5.1 ||[[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->


| [[GeneMarkES-Sapelo2|GeneMark-ET]] || 4.71 ||[[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->





























|[[gocryptfs-Sapelo2|gocryptfs]] || 2.2.1, 2.5.2 || [[:Category:Other|Other]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-





| [[GROMACS-Sapelo2 |GROMACS]] || 2023.4, 2024.4 ||[[:Category:Chemistry|Chemistry]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->


















| [[HISAT2-Sapelo2|HISAT2]] || 2.2.1 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[HISAT2-Teaching|HISAT2]] || 2.2.1 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|- -->



| [[HpcGridRunner-Sapelo2|HPCGridRunner]] || 1.0.2 || [[:Category:Tools|Tools]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-










|-
| [[iCommands-Sapelo2|iCommands]] || 4.2.8 || [[:Category:Tools|Tools]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-










| [[InterProScan-Sapelo2|InterProScan]] || 5.55-88.0, 5.64-96.0, 5.73-104.0, 5.75-106.0, 5.76-107.0 ||[[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->



| [[IQ-Tree-Sapelo2|IQ-Tree]] || 2.2.2.7, 2.3.5, 2.3.6, 3.0.1 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[IQ-Tree-Teaching|IQ-Tree]] || 2.2.2.7, 2.3.5, 2.3.6, 3.0.1 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-








| [[Java-Teaching|Java]] || 1.8.0_241, 1.8.0_311, 8.402, 11.0.20, 17.0.6, 21.0.2, 21.0.5, 25.36 || [[:Category:Programming|Programming]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-






| [[Jupyter-Sapelo2|Jupyter]] || 6.5.6, 7.0.2, 7.2.0, 7.2.3, 7.4.4, 7.4.5, 7.4.7 || [[:Category:Programming|Programming]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-
| [[Jupyter-Teaching|Jupyter]] || 6.4.12 || [[:Category:Programming|Programming]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-
|- -->













| [[LAMMPS-Sapelo2|LAMMPS]] || 22Jul2025, 29Aug2024 || [[:Category:Chemistry|Chemistry]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-



































| [[Magma-Sapelo2|Magma]] || 2.27-1, 2.28-27 || [[:Category:Other|Other]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-


| [[Maker-Sapelo2|Maker]] || 3.01.04 ||[[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-









| [[MATLAB-Sapelo2|MATLAB]] || R2023b || [[:Category:Programming|Programming]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-









| [[Medusa-Sapelo2 |Medusa]] || 1.6 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-













| [[MetaPhlAn4-Sapelo2|MetaPhlAn4]] || 4.0.3.1, 4.0.6, 4.1.1 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-









































| [[Nsight-Compute-CLI-Sapelo2|Nsight Compute CLI]] || 2024.3.0.0, 2025.1.0.0, 2025.4.0.0 || [[:Category:Other|Other]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-




































| [[Ont-Guppy-Sapelo2|Ont-Guppy]] || 6.5.7 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-





| [[ORCA-Sapelo2 |ORCA]] || 4.2.1, 5.0.4 || [[:Category:Chemistry|Chemistry]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-




|[[ORP-Sapelo2|ORP]] || 2.2.6, 2.2.8 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[OrthoFinder-Sapelo2|OrthoFinder]] || 2.5.4, 2.5.5 ||[[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->








| [[PAML-Teaching|PAML]] || 4.9j, 4.10.5 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|- -->









| [[PASA-Sapelo2|PASA]] || 2.5.3 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->













| [[Perl-Teaching|Perl]] || 5.34.0, 5.34.1, 5.36.0, 5.36.1, 5.38.0, 5.38.2, 5.40.0, 5.40.2 || [[:Category:Programming|Programming]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|- -->







| [[Phenix-Sapelo2|Phenix]] || 1.21.2-5419 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-

























































|-
| [[Python-Sapelo2 |Python]] || 2.7.18, 3.9.6, 3.10.4, 3.10.8, 3.11.3, 3.11.5, 3.12.3, 3.13.1, 3.13.5 || [[:Category:Programming|Programming]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[Python-Teaching|Python]] || 2.7.18, 3.9.6, 3.10.4, 3.10.8, 3.11.3, 3.11.5, 3.12.3, 3.13.1, 3.13.5 || [[:Category:Programming|Programming]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|- -->






| [[QIIME2-Sapelo2|QIIME2]] || 2020.6, 2023.2, 2023.5.1, 2023.7, 2023.9, 2024.2 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->







| [[R-Sapelo2 |R]] || 4.2.1, 4.3.1, 4.3.2, 4.4.1, 4.4.2, 4.5.1 ||[[:Category:Statistics|Statistics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-
| [[R-Teaching|R]] || 4.2.1, 4.3.1, 4.3.2, 4.4.1, 4.4.2, 4.5.1 || [[:Category:Statistics|Statistics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[racon-Sapelo2 |Racon]] || 1.5.0 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-




| [[RAxML-NG-Sapelo2 |RAxML-NG]] || 1.2.2 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[RAxML-Sapelo2 |RAxML]] || 8.2.13 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[RAxML-Teaching|RAxML]] || 8.2.13 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|- -->

















| [[RevBayes-Teaching|RevBayes]] || 1.1.0, 1.2.1 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-







| [[Rosetta-Sapelo2 |Rosetta]] || 2021.16.61629, 2022.46.334 ||[[:Category:Chemistry|Chemistry]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->


| [[Rstudio-Sapelo2|Rstudio]] || 2023.06.1-524 || [[:Category:Other|Other]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-










| [[SAMtools-Teaching|SAMtools]] || 0.1.20, 1.6, 1.13, 1.14, 1.16.1, 1.18, 1.21 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|- -->

| [[SequenceTubeMap-Sapelo2|sequenceTubeMap]] || 20230906 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:sapelo2|sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->









































| [[snpEff-Sapelo2|snpEff]] || 5.0e || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->





















| [[SRAToolKit-Sapelo2 |SRAToolKit]] || 3.0.1, 3.0.3 ||[[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->













| [[StringTie-Teaching|StringTie]] || 2.2.3, 3.0.0 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-
| [[Structure-Sapelo2|Structure]] || 2.3.4 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[Structure-Teaching|Structure]] || 2.3.4 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-


































| [[Trinity-Sapelo2|Trinity]] || 2.5.1, 2.8.4, 2.8.5, 2.15.1, 2.15.2 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->



| [[UBCG-Sapelo2|UBCG]] || 3.0
|[[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-














| [[Velvet-Sapelo2|Velvet]] || 1.2.10 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->






















|}
[[#top|Back To Top]] [[File:Up20.png|20px|link=#top]]

[[Category:Sapelo2]][[Category:Teaching]][[Category:Software]]

Software

2026-07-21T19:28:09Z

Moses:

On Sapelo2 and on the Teaching cluster users have the option to install their own software or use software installed centrally by the GACRC staff. Detailed information on how to find and access software packages installed on Sapelo2 are available at the [[Software on Sapelo2]] page and on the teaching cluster at the [[Software on Teaching Cluster]] page.

Below is a very limited list of software packages installed on Sapelo2 and on the Teaching cluster. We only intend to make an application page for software packages that requires extra documentation not covered in [[Software on Sapelo2]] or [[Software on Teaching Cluster]].

To view a list of all modules installed on Sapelo2/Teaching, along with a short description of each module, please run the following command on Sapelo2/Teaching:
<pre class="gcommand">
module spider
</pre>
You can also use the command above to search for a specific application. For more information, please see [[Lmod]].

The '''file transfer''' nodes ('''xfer''' nodes) do not have environment modules installed. File transfer utilities are installed centrally on the xfer nodes and available on the users' default PATH. Such utilities include bs (basespace-cli), fpsync, rclone, rsync, etc.
https://wiki.gacrc.uga.edu/wiki/Main_Page

'''Note:''' Although we have not made individual software pages for the applications installed on Sapelo2, there are currently over 1300 software packages installed there. For more information, please see [[Software on Sapelo2]].

==Partial List of Installed Software==
Last updated '''{{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}}'''. This is a partial list of installed software so there may be software or versions of software available on Sapelo2 which are not included in this table.
'''Note:''' Click on the icons to the right of the column headings to sort the table.
[[#0|0-9]] [[#A|A]] [[#B|B]] [[#C|C]] [[#D|D]] [[#E|E]] [[#F|F]] [[#G|G]] [[#H|H]] [[#I|I]] [[#J|J]] [[#K|K]] [[#L|L]] [[#M|M]] [[#N|N]] [[#O|O]] [[#P|P]] [[#Q|Q]] [[#R|R]] [[#S|S]] [[#T|T]] [[#U|U]] [[#V|V]] [[#W|W]] [[#X|X]] [[#Y|Y]] [[#Z|Z]]
{| width="100%" border="1" cellspacing="0" cellpadding="2" align="center" class="wikitable sortable"
|-
! scope="col" width="200px"| Name
! scope="col" class="unsortable" width="240px"| Version
! scope="col" width="160px"| Category
! scope="col" width="60px"| Cluster
! scope="col" width="20px"| Top
|-













| [[AlphaFold-Sapelo2|AlphaFold 2]] || 2.3.1, 2.3.2 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-
|- -->
| [[AlphaFold3-Sapelo2|AlphaFold 3]] || 3.0.0, 3.0.1 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-





| [[AMBER-Sapelo2|AMBER]] || 22.4, 24.3 || [[:Category:Chemistry|Chemistry]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->








| [[anvi'o-Sapelo2|anvi'o]] || 4, 5.1, 5.3, 5.4, 6.1, 7, 7.1 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:sapelo2|sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->














| | [[Bactopia-Sapelo2|Bactopia]] || 3.2.0, 4.0.0 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->


| [[basespace-cli-Sapelo2|basespace-cli]] || 1.2.1, 1.7.0 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->










|[[Beast-Sapelo2|Beast]] || 1.10.4, 2.6.7, 2.7.3, 2.7.7, 10.5.0 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->










| [[BioPython-Sapelo2|BioPython]] || 1.76, 1.79, 1.80, 1.83, 1.84, 1.85 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
|[[Biopython-Teaching|Biopython]] || 1.76, 1.79, 1.80, 1.83, 1.84, 1.85 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-




| [[BLAST+-Sapelo2|BLAST+]] || 2.13.0, 2.14.1, 2.16.0, 2.17.0 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] ||[[File:Up20.png|20px|link=#top]]
|- -->
| [[BLAST+-Teaching|BLAST+]] || 2.13.0, 2.14.1, 2.16.0, 2.17.0 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-








| [[Bowtie2-Sapelo2|Bowtie2]] || 2.4.4, 2.4.5, 2.5.1, 2.5.2, 2.5.4 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[Bowtie2-Teaching|Bowtie2]] || 2.4.4, 2.4.5, 2.5.1, 2.5.2, 2.5.4 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-

| [[Bracken-Sapelo2|Bracken]] || 3.1 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[BRAKER-Sapelo2|BRAKER]] || 3.0.8 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-



| [[BUSCO-Sapelo2|BUSCO]] || 5.8.3, 6.0.0 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-




| [[Cactus-Sapelo2|Cactus]] || 1.2.3, 2.0.3, 2.4.3, 2.4.4, 2.5.0, 2.6.0, 2.6.7, 2.6.9, 2.7.0, 2.9.0, 2.9.3, 2.9.9, 3.0.0 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-

| [[Canu-Sapelo2|Canu]] || 2.3||[[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-









| [[CellRanger-ATAC-Sapelo2|CellRanger-ATAC]] || 2.1.0 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->








| [[Chimera-Teaching|Chimera]] || 1.16 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-























| [[cryoSPARC-Sapelo2|CryoSPARC]] || 3.3.1 || [[:Category:Engineering|Engineering]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-
| [[Cromwell-Sapelo2|Cromwell]] || 56 || [[:Category:Tools|Tools]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-
|[[CUDA-Sapelo2|CUDA]] || 11.7.0, 11.8.0, 12.1.1, 12.4.0, 12.6.0, 12.8.0, 13.1.0 ||[[:Category:Programming|Programming]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-







| [[Cytoscape-Sapelo2|Cytoscape]] || 3.9.1, 3.10.4 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[Cytoscape-Teaching|Cytoscape]] || 3.9.1, 3.10.4 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-



























|-->
| [[dMRIharmonization-Sapelo2|dMRIharmonization]] || 20240227 || [[:Category:Engineering|Engineering]]|| [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-->





| [[EGAPx-Sapelo2|EGAPx]] || N/A || [[:Category:Bioinformatics|Bioinformatics]] || N/A || [[File:Up20.png|20px|link=#top]]
|- -->


| [[EIGENSOFT-Sapelo2|EIGENSOFT]] || 7.2.1 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[EIGENSOFT-Teaching|EIGENSOFT]] || 7.2.1 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-
| [[Flankophile-Sapelo2|Flankophile]] || N/A || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-






































|-
| [[Funannotate-Sapelo2|Funannotate]] || 1.8.15, 1.8.17 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-
|- -->













| [[GAUSSIAN-Sapelo2|GAUSSIAN]] || 09, 16 || [[:Category:Chemistry|Chemistry]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
|[[GAUSSIAN-Teaching|GAUSSIAN]] || 09, 16 || [[:Category:Chemistry|Chemistry]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-
| [[GaussView-Sapelo2|GaussView]] || 5, 6.1 || [[:Category:Chemistry|Chemistry]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[GaussView-Teaching|GaussView]] || 6.1 || [[:Category:Chemistry|Chemistry]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-







| [[GEM-Sapelo2|GEM]] || 1.5.1 ||[[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->


| [[GeneMarkES-Sapelo2|GeneMark-ET]] || 4.71 ||[[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->





























|[[gocryptfs-Sapelo2|gocryptfs]] || 2.2.1, 2.5.2 || [[:Category:Other|Other]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-





| [[GROMACS-Sapelo2 |GROMACS]] || 2023.4, 2024.4 ||[[:Category:Chemistry|Chemistry]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->


















| [[HISAT2-Sapelo2|HISAT2]] || 2.2.1 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[HISAT2-Teaching|HISAT2]] || 2.2.1 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|- -->



| [[HpcGridRunner-Sapelo2|HPCGridRunner]] || 1.0.2 || [[:Category:Tools|Tools]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-










|-
| [[iCommands-Sapelo2|iCommands]] || 4.2.8 || [[:Category:Tools|Tools]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-










| [[InterProScan-Sapelo2|InterProScan]] || 5.55-88.0, 5.64-96.0, 5.73-104.0, 5.75-106.0, 5.76-107.0 ||[[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->



| [[IQ-Tree-Sapelo2|IQ-Tree]] || 2.2.2.7, 2.3.5, 2.3.6, 3.0.1 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[IQ-Tree-Teaching|IQ-Tree]] || 2.2.2.7, 2.3.5, 2.3.6, 3.0.1 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-








| [[Java-Teaching|Java]] || 1.8.0_241, 1.8.0_311, 8.402, 11.0.20, 17.0.6, 21.0.2, 21.0.5, 25.36 || [[:Category:Programming|Programming]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-






| [[Jupyter-Sapelo2|Jupyter]] || 6.5.6, 7.0.2, 7.2.0, 7.2.3, 7.4.4, 7.4.5, 7.4.7 || [[:Category:Programming|Programming]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-
| [[Jupyter-Teaching|Jupyter]] || 6.4.12 || [[:Category:Programming|Programming]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-
|- -->













| [[LAMMPS-Sapelo2|LAMMPS]] || 22Jul2025, 29Aug2024 || [[:Category:Chemistry|Chemistry]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-



































| [[Magma-Sapelo2|Magma]] || 2.27-1, 2.28-27 || [[:Category:Other|Other]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-


| [[Maker-Sapelo2|Maker]] || 3.01.04 ||[[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-









| [[MATLAB-Sapelo2|MATLAB]] || R2023b || [[:Category:Programming|Programming]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-









| [[Medusa-Sapelo2 |Medusa]] || 1.6 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-













| [[MetaPhlAn4-Sapelo2|MetaPhlAn4]] || 4.0.3.1, 4.0.6, 4.1.1 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-









































| [[Nsight-Compute-CLI-Sapelo2|Nsight Compute CLI]] || 2024.3.0.0, 2025.1.0.0, 2025.4.0.0 || [[:Category:Other|Other]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-




































| [[Ont-Guppy-Sapelo2|Ont-Guppy]] || 6.5.7 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-





| [[ORCA-Sapelo2 |ORCA]] || 4.2.1, 5.0.4 || [[:Category:Chemistry|Chemistry]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-




|[[ORP-Sapelo2|ORP]] || 2.2.6, 2.2.8 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[OrthoFinder-Sapelo2|OrthoFinder]] || 2.5.4, 2.5.5 ||[[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->

< [[OrthoMCL-Sapelo2|OrthoMCL]] || 2.0.9 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->






| [[PAML-Teaching|PAML]] || 4.9j, 4.10.5 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|- -->









| [[PASA-Sapelo2|PASA]] || 2.5.3 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->













| [[Perl-Teaching|Perl]] || 5.34.0, 5.34.1, 5.36.0, 5.36.1, 5.38.0, 5.38.2, 5.40.0, 5.40.2 || [[:Category:Programming|Programming]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|- -->







| [[Phenix-Sapelo2|Phenix]] || 1.21.2-5419 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-

























































|-
| [[Python-Sapelo2 |Python]] || 2.7.18, 3.9.6, 3.10.4, 3.10.8, 3.11.3, 3.11.5, 3.12.3, 3.13.1, 3.13.5 || [[:Category:Programming|Programming]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[Python-Teaching|Python]] || 2.7.18, 3.9.6, 3.10.4, 3.10.8, 3.11.3, 3.11.5, 3.12.3, 3.13.1, 3.13.5 || [[:Category:Programming|Programming]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|- -->






| [[QIIME2-Sapelo2|QIIME2]] || 2020.6, 2023.2, 2023.5.1, 2023.7, 2023.9, 2024.2 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->







| [[R-Sapelo2 |R]] || 4.2.1, 4.3.1, 4.3.2, 4.4.1, 4.4.2, 4.5.1 ||[[:Category:Statistics|Statistics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-
| [[R-Teaching|R]] || 4.2.1, 4.3.1, 4.3.2, 4.4.1, 4.4.2, 4.5.1 || [[:Category:Statistics|Statistics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[racon-Sapelo2 |Racon]] || 1.5.0 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-




| [[RAxML-NG-Sapelo2 |RAxML-NG]] || 1.2.2 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[RAxML-Sapelo2 |RAxML]] || 8.2.13 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[RAxML-Teaching|RAxML]] || 8.2.13 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|- -->

















| [[RevBayes-Teaching|RevBayes]] || 1.1.0, 1.2.1 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-







| [[Rosetta-Sapelo2 |Rosetta]] || 2021.16.61629, 2022.46.334 ||[[:Category:Chemistry|Chemistry]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->


| [[Rstudio-Sapelo2|Rstudio]] || 2023.06.1-524 || [[:Category:Other|Other]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-










| [[SAMtools-Teaching|SAMtools]] || 0.1.20, 1.6, 1.13, 1.14, 1.16.1, 1.18, 1.21 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|- -->

| [[SequenceTubeMap-Sapelo2|sequenceTubeMap]] || 20230906 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:sapelo2|sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->









































| [[snpEff-Sapelo2|snpEff]] || 5.0e || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->





















| [[SRAToolKit-Sapelo2 |SRAToolKit]] || 3.0.1, 3.0.3 ||[[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->













| [[StringTie-Teaching|StringTie]] || 2.2.3, 3.0.0 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-
| [[Structure-Sapelo2|Structure]] || 2.3.4 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->
| [[Structure-Teaching|Structure]] || 2.3.4 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Teaching|Teaching]] || [[File:Up20.png|20px|link=#top]]
|-


































| [[Trinity-Sapelo2|Trinity]] || 2.5.1, 2.8.4, 2.8.5, 2.15.1, 2.15.2 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->



| [[UBCG-Sapelo2|UBCG]] || 3.0
|[[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|-














| [[Velvet-Sapelo2|Velvet]] || 1.2.10 || [[:Category:Bioinformatics|Bioinformatics]] || [[:Category:Sapelo2|Sapelo2]] || [[File:Up20.png|20px|link=#top]]
|- -->






















|}
[[#top|Back To Top]] [[File:Up20.png|20px|link=#top]]

[[Category:Sapelo2]][[Category:Teaching]][[Category:Software]]

CryoSPARC-Sapelo2

2026-07-10T15:29:16Z

Moses: /* How to run cryoSPARC from Sapelo2 */

[[Category:Sapelo2]][[Category:Software]][[Category:Engineering]]

== Category ==

Engineering

== Program On ==

Sapelo2

== Version ==

4.3.1

== Author / Distributor ==

See https://guide.cryosparc.com/

== Description ==

"CryoSPARC (Cryo-EM Single Particle Ab-Initio Reconstruction and Classification) is a state of the art HPC software solution for complete processing of single-particle cryo-electron microscopy (cryo-EM) data. CryoSPARC is useful for solving cryo-EM structures of membrane proteins, viruses, complexes, flexible molecules, small particles, phase plate data and negative stain data." For more information, please see https://guide.cryosparc.com/.

'''NOTE''': Users are required to be added into GACRC '''cryosparc''' group before they can run this software from Sapelo2. Please fill out the [https://uga.teamdynamix.com/TDClient/2060/Portal/Requests/ServiceDet?ID=25844 GACRC General Support form] to request. We will reach out to you after we received your request.

== Configurations ==
'''Master node VM:'''

* Host name: '''cryosparc.gacrc.uga.edu'''
* Intel Xeon processors (16 cores) and 64GB of RAM
* mongodb is installed and run on the master node
'''Worker nodes:'''
* One NVIDIA Tesla A100 node: Intel Xeon processors (64 cores), 1TB host RAM memory, 4 NVIDIA Tesla A100 GPU cards (80GiB device memory per card), and NVMe SSD 3570GB local drive.
* cryoSPARC recommends using SSD for caching particle data. /lscratch/gacrc-cryo is set up on the worker node for this purpose.
* The amount of space that cryoSPARC can use in /lscratch/gacrc-cryo is capped at 100GB.
'''cryoSPARC group:''' '''cryosparc'''

'''cryoSPARC service account:''' '''gacrc-cryo'''

* gacrc-cryo is the '''service account''' that will run cryoSPARC workflow jobs for all cryoSPARC users.
* Some tasks can only be handled by gacrc-cryo, like make a new lane of worker node(s), user management, and connect or update worker node(s) to master, etc..
* Regular CryoSPARC users can run cryosparcm on the master node to check cryoSPARC status, using cryosparcm status or cryosparcm checkdb.

'''cryoSPARC project space:''' '''/scratch/gacrc-cryo'''

== User Login ==
There are two ways to access the CryoSPARC web interface. The recommended method is to connect through the UGA VPN and access the CryoSPARC web server directly. SSH tunneling remains available as an alternative if needed.

=== Method 1 (Recommended): VPN + Direct Web Access ===
# Connect to the UGA VPN using the Cisco Secure Client (Cisco AnyConnect) and select '''remote.uga.edu'''.
#: '''Note:''' Even if you are working on campus, you must still connect to the UGA VPN before accessing the CryoSPARC web server.
# Open the URL for your assigned CryoSPARC instance in your web browser. For example:
#:
#: <code>http://cryosparc.gacrc.uga.edu:39000</code>
# Log in using your registered UGA email address and CryoSPARC password.
#:
#: '''Note:''' Your registered UGA email address may be an email alias rather than your official '''MyID@uga.edu''' address. Please use the email address that was registered with your CryoSPARC account.

=== Method 2: SSH Tunnel ===
Users may also access CryoSPARC by establishing an SSH tunnel to expose port 39000 from the CryoSPARC master node to their local computer.

If you are using Linux or macOS, run the following command in a terminal:

<pre>
ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu
</pre>

If you are using Windows, download '''[https://the.earth.li/~sgtatham/putty/latest/x86/plink.exe plink program]''' and run:

<pre>
plink -ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu
</pre>

Place <code>plink.exe</code> in your current working directory, or specify its full path when running the command.

Unless you have configured SSH public key authentication, you will be prompted for your UGA MyID password and Duo authentication. After authentication succeeds, the SSH session will remain open. This is expected and indicates that the tunnel has been established successfully.

With the SSH tunnel active, open your web browser and navigate to:

<pre>
http://localhost:39000
</pre>

The CryoSPARC login page should appear.

=== Troubleshooting ===
If you are unable to access the CryoSPARC web interface:

* Verify that you are connected to the UGA VPN if you are using the recommended VPN + Direct Web Access method.
* Confirm that you are using the correct URL for your assigned CryoSPARC instance.
* Make sure you are logging in with your registered UGA email address and CryoSPARC password. Your registered UGA email address may be an email alias rather than your official MyID@uga.edu address.
* If you are using the SSH tunnel method, ensure that the SSH session remains active while accessing the web interface.
* If you have forgotten your CryoSPARC password, contact GACRC Support to request a password reset token.
* If the problem persists, please contact GACRC Support and include:
** The URL you are using to access CryoSPARC.
** Your UGA MyID and your registered UGA email address.
** A screenshot of the error message or the login/password reset screen, if applicable.

== Run cryoSPARC workflow jobs ==

=== Project space selection ===
A project in cryoSPARC is a high level container corresponding with a project directory on the file system, which stores all associated Jobs of a project. Each project in cryoSPARC is entirely contained within a file system directory. All the jobs and their respective intermediate and output data created within a project will be stored within the project directory.

* When you start a new project in cryoSPARC GUI, please select and use '''/scratch/gacrc-cryo''' as the cryoSPARC project space.
* This folder is owned by gacrc-cryo. Regular cryoSPARC users have access and read permissions which allow them to browse files in this folder and copy files from this folder to their own storage spaces on Sapelo2.

=== Run job on the master node ===
cryoSPARC will use the master node to run some types of workflow jobs, for example, "Import Movies", "Inspect Picks", and the interactive job "Select 2D Classes". When a job is created, if cryoSPARC will use the master node to run the job, you will be notified about this in cryoSPARC GUI.

=== Run job using "Lane Sapelo2 Default (cluster)" ===
* In cryoSPARC, queue a job to "'''Lane Sapelo2 Default (cluster)'''"; The job will be dispatched to the worker node via Slurm. Please note, gacrc-cryo, instead of your own Sapelo2 user account, is the user account owning and running the job. We highly recommend you to use this method to run cryoSPARC workflow jobs on Sapelo2.
* cryoSPARC will decide on how many CPU cores and how much memory it will use to run a workflow job, depend on the type of the job and your data size. Currently, we configured that from each worker node cryoSPARC can use up to '''20GB''' memory and '''4''' CPU cores.
* If the job needs to run on GPU devices, cryoSPARC will queue the job with a default number of GPU devices , for example 1. You can change this number by yourself in cryoSPARC GUI when you create the job. Please note that the maximum number of GPU devices installed on the worker node is '''4'''.

==Documentation (v4.0+)==

About cryoSPARC: https://guide.cryosparc.com/

Get Started with CryoSPARC: Introductory Tutorial: https://guide.cryosparc.com/processing-data/get-started-with-cryosparc-introductory-tutorial

A Tour of the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/a-tour-of-the-cryosparc-interface

Using the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/using-the-cryosparc-interface

Creating and Running Jobs: https://guide.cryosparc.com/application-guide-v4.0+/creating-and-running-jobs

Tutorial videos: https://guide.cryosparc.com/processing-data/tutorial-videos

==Installation==

*Version 4.3.1 master is installed on the master node (cryosparc.gacrc.uga.edu).
*Version 4.3.1 workers are installed on one worker GPU node (NVIDIA Tesla A100 GPU node).

==System==
64-bit Linux

CryoSPARC-Sapelo2

2026-07-10T15:27:29Z

Moses: /* User Login */

[[Category:Sapelo2]][[Category:Software]][[Category:Engineering]]

== Category ==

Engineering

== Program On ==

Sapelo2

== Version ==

4.3.1

== Author / Distributor ==

See https://guide.cryosparc.com/

== Description ==

"CryoSPARC (Cryo-EM Single Particle Ab-Initio Reconstruction and Classification) is a state of the art HPC software solution for complete processing of single-particle cryo-electron microscopy (cryo-EM) data. CryoSPARC is useful for solving cryo-EM structures of membrane proteins, viruses, complexes, flexible molecules, small particles, phase plate data and negative stain data." For more information, please see https://guide.cryosparc.com/.

'''NOTE''': Users are required to be added into GACRC '''cryosparc''' group before they can run this software from Sapelo2. Please fill out the [https://uga.teamdynamix.com/TDClient/2060/Portal/Requests/ServiceDet?ID=25844 GACRC General Support form] to request. We will reach out to you after we received your request.

== Configurations ==
'''Master node VM:'''

* Host name: '''cryosparc.gacrc.uga.edu'''
* Intel Xeon processors (16 cores) and 64GB of RAM
* mongodb is installed and run on the master node
'''Worker nodes:'''
* One NVIDIA Tesla A100 node: Intel Xeon processors (64 cores), 1TB host RAM memory, 4 NVIDIA Tesla A100 GPU cards (80GiB device memory per card), and NVMe SSD 3570GB local drive.
* cryoSPARC recommends using SSD for caching particle data. /lscratch/gacrc-cryo is set up on the worker node for this purpose.
* The amount of space that cryoSPARC can use in /lscratch/gacrc-cryo is capped at 100GB.
'''cryoSPARC group:''' '''cryosparc'''

'''cryoSPARC service account:''' '''gacrc-cryo'''

* gacrc-cryo is the '''service account''' that will run cryoSPARC workflow jobs for all cryoSPARC users.
* Some tasks can only be handled by gacrc-cryo, like make a new lane of worker node(s), user management, and connect or update worker node(s) to master, etc..
* Regular CryoSPARC users can run cryosparcm on the master node to check cryoSPARC status, using cryosparcm status or cryosparcm checkdb.

'''cryoSPARC project space:''' '''/scratch/gacrc-cryo'''
== How to run cryoSPARC from Sapelo2 ==

=== User Login ===

There are two ways to access the CryoSPARC web interface. The recommended method is to connect through the UGA VPN and access the CryoSPARC web server directly. SSH tunneling remains available as an alternative if needed.

==== Method 1 (Recommended): VPN + Direct Web Access ====
# Connect to the UGA VPN using the Cisco Secure Client (Cisco AnyConnect) and select '''remote.uga.edu'''.
#: '''Note:''' Even if you are working on campus, you must still connect to the UGA VPN before accessing the CryoSPARC web server.
# Open the URL for your assigned CryoSPARC instance in your web browser. For example:
#:
#: <code>http://cryosparc.gacrc.uga.edu:39000</code>
# Log in using your registered UGA email address and CryoSPARC password.
#:
#: '''Note:''' Your registered UGA email address may be an email alias rather than your official '''MyID@uga.edu''' address. Please use the email address that was registered with your CryoSPARC account.

==== Method 2: SSH Tunnel ====
Users may also access CryoSPARC by establishing an SSH tunnel to expose port 39000 from the CryoSPARC master node to their local computer.

If you are using Linux or macOS, run the following command in a terminal:

<pre>
ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu
</pre>

If you are using Windows, download '''[https://the.earth.li/~sgtatham/putty/latest/x86/plink.exe plink program]''' and run:

<pre>
plink -ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu
</pre>

Place <code>plink.exe</code> in your current working directory, or specify its full path when running the command.

Unless you have configured SSH public key authentication, you will be prompted for your UGA MyID password and Duo authentication. After authentication succeeds, the SSH session will remain open. This is expected and indicates that the tunnel has been established successfully.

With the SSH tunnel active, open your web browser and navigate to:

<pre>
http://localhost:39000
</pre>

The CryoSPARC login page should appear.

==== Troubleshooting ====
If you are unable to access the CryoSPARC web interface:

* Verify that you are connected to the UGA VPN if you are using the recommended VPN + Direct Web Access method.
* Confirm that you are using the correct URL for your assigned CryoSPARC instance.
* Make sure you are logging in with your registered UGA email address and CryoSPARC password. Your registered UGA email address may be an email alias rather than your official MyID@uga.edu address.
* If you are using the SSH tunnel method, ensure that the SSH session remains active while accessing the web interface.
* If you have forgotten your CryoSPARC password, contact GACRC Support to request a password reset token.
* If the problem persists, please contact GACRC Support and include:
** The URL you are using to access CryoSPARC.
** Your UGA MyID and your registered UGA email address.
** A screenshot of the error message or the login/password reset screen, if applicable.

=== Run cryoSPARC workflow jobs ===

==== Project space selection ====
A project in cryoSPARC is a high level container corresponding with a project directory on the file system, which stores all associated Jobs of a project. Each project in cryoSPARC is entirely contained within a file system directory. All the jobs and their respective intermediate and output data created within a project will be stored within the project directory.

* When you start a new project in cryoSPARC GUI, please select and use '''/scratch/gacrc-cryo''' as the cryoSPARC project space.
* This folder is owned by gacrc-cryo. Regular cryoSPARC users have access and read permissions which allow them to browse files in this folder and copy files from this folder to their own storage spaces on Sapelo2.

==== Run job on the master node ====
cryoSPARC will use the master node to run some types of workflow jobs, for example, "Import Movies", "Inspect Picks", and the interactive job "Select 2D Classes". When a job is created, if cryoSPARC will use the master node to run the job, you will be notified about this in cryoSPARC GUI.

==== Run job using "Lane Sapelo2 Default (cluster)" ====

* In cryoSPARC, queue a job to "'''Lane Sapelo2 Default (cluster)'''"; The job will be dispatched to the worker node via Slurm. Please note, gacrc-cryo, instead of your own Sapelo2 user account, is the user account owning and running the job. We highly recommend you to use this method to run cryoSPARC workflow jobs on Sapelo2.
* cryoSPARC will decide on how many CPU cores and how much memory it will use to run a workflow job, depend on the type of the job and your data size. Currently, we configured that from each worker node cryoSPARC can use up to '''20GB''' memory and '''4''' CPU cores.
* If the job needs to run on GPU devices, cryoSPARC will queue the job with a default number of GPU devices , for example 1. You can change this number by yourself in cryoSPARC GUI when you create the job. Please note that the maximum number of GPU devices installed on the worker node is '''4'''.

==Documentation (v4.0+)==

About cryoSPARC: https://guide.cryosparc.com/

Get Started with CryoSPARC: Introductory Tutorial: https://guide.cryosparc.com/processing-data/get-started-with-cryosparc-introductory-tutorial

A Tour of the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/a-tour-of-the-cryosparc-interface

Using the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/using-the-cryosparc-interface

Creating and Running Jobs: https://guide.cryosparc.com/application-guide-v4.0+/creating-and-running-jobs

Tutorial videos: https://guide.cryosparc.com/processing-data/tutorial-videos

==Installation==

*Version 4.3.1 master is installed on the master node (cryosparc.gacrc.uga.edu).
*Version 4.3.1 workers are installed on one worker GPU node (NVIDIA Tesla A100 GPU node).

==System==
64-bit Linux

CryoSPARC-Sapelo2

2026-07-10T15:26:45Z

Moses: /* User Login */

[[Category:Sapelo2]][[Category:Software]][[Category:Engineering]]

== Category ==

Engineering

== Program On ==

Sapelo2

== Version ==

4.3.1

== Author / Distributor ==

See https://guide.cryosparc.com/

== Description ==

"CryoSPARC (Cryo-EM Single Particle Ab-Initio Reconstruction and Classification) is a state of the art HPC software solution for complete processing of single-particle cryo-electron microscopy (cryo-EM) data. CryoSPARC is useful for solving cryo-EM structures of membrane proteins, viruses, complexes, flexible molecules, small particles, phase plate data and negative stain data." For more information, please see https://guide.cryosparc.com/.

'''NOTE''': Users are required to be added into GACRC '''cryosparc''' group before they can run this software from Sapelo2. Please fill out the [https://uga.teamdynamix.com/TDClient/2060/Portal/Requests/ServiceDet?ID=25844 GACRC General Support form] to request. We will reach out to you after we received your request.

== Configurations ==
'''Master node VM:'''

* Host name: '''cryosparc.gacrc.uga.edu'''
* Intel Xeon processors (16 cores) and 64GB of RAM
* mongodb is installed and run on the master node
'''Worker nodes:'''
* One NVIDIA Tesla A100 node: Intel Xeon processors (64 cores), 1TB host RAM memory, 4 NVIDIA Tesla A100 GPU cards (80GiB device memory per card), and NVMe SSD 3570GB local drive.
* cryoSPARC recommends using SSD for caching particle data. /lscratch/gacrc-cryo is set up on the worker node for this purpose.
* The amount of space that cryoSPARC can use in /lscratch/gacrc-cryo is capped at 100GB.
'''cryoSPARC group:''' '''cryosparc'''

'''cryoSPARC service account:''' '''gacrc-cryo'''

* gacrc-cryo is the '''service account''' that will run cryoSPARC workflow jobs for all cryoSPARC users.
* Some tasks can only be handled by gacrc-cryo, like make a new lane of worker node(s), user management, and connect or update worker node(s) to master, etc..
* Regular CryoSPARC users can run cryosparcm on the master node to check cryoSPARC status, using cryosparcm status or cryosparcm checkdb.

'''cryoSPARC project space:''' '''/scratch/gacrc-cryo'''
== How to run cryoSPARC from Sapelo2 ==

=== User Login ===

There are two ways to access the CryoSPARC web interface. The recommended method is to connect through the UGA VPN and access the CryoSPARC web server directly. SSH tunneling remains available as an alternative if needed.

==== Method 1 (Recommended): VPN + Direct Web Access ====
# Connect to the UGA VPN using the Cisco Secure Client (Cisco AnyConnect) and select '''remote.uga.edu'''.
#: '''Note:''' Even if you are working on campus, you must still connect to the UGA VPN before accessing the CryoSPARC web server.
# Open the URL for your assigned CryoSPARC instance in your web browser. For example:
#:
#: <code>http://cryosparc.gacrc.uga.edu:39000</code>
# Log in using your registered UGA email address and CryoSPARC password.
#:
#: '''Note:''' Your registered UGA email address may be an email alias rather than your official '''MyID@uga.edu''' address. Please use the email address that was registered with your CryoSPARC account.

==== Method 2: SSH Tunnel ====
Users may also access CryoSPARC by establishing an SSH tunnel to expose port 39000 from the CryoSPARC master node to their local computer.

If you are using Linux or macOS, run the following command in a terminal:

<pre>
ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu
</pre>

If you are using Windows, download '''[https://the.earth.li/~sgtatham/putty/latest/x86/plink.exe plink program]''' and run:

<pre>
plink -ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu
</pre>

Place <code>plink.exe</code> in your current working directory, or specify its full path when running the command.

Unless you have configured SSH public key authentication, you will be prompted for your UGA MyID password and Duo authentication. After authentication succeeds, the SSH session will remain open. This is expected and indicates that the tunnel has been established successfully.

With the SSH tunnel active, open your web browser and navigate to:

<pre>
http://localhost:39000
</pre>

The CryoSPARC login page should appear.

===== Troubleshooting =====
If you are unable to access the CryoSPARC web interface:

* Verify that you are connected to the UGA VPN if you are using the recommended VPN + Direct Web Access method.
* Confirm that you are using the correct URL for your assigned CryoSPARC instance.
* Make sure you are logging in with your registered UGA email address and CryoSPARC password. Your registered UGA email address may be an email alias rather than your official MyID@uga.edu address.
* If you are using the SSH tunnel method, ensure that the SSH session remains active while accessing the web interface.
* If you have forgotten your CryoSPARC password, contact GACRC Support to request a password reset token.
* If the problem persists, please contact GACRC Support and include:
** The URL you are using to access CryoSPARC.
** Your UGA MyID and your registered UGA email address.
** A screenshot of the error message or the login/password reset screen, if applicable.

=== Run cryoSPARC workflow jobs ===

==== Project space selection ====
A project in cryoSPARC is a high level container corresponding with a project directory on the file system, which stores all associated Jobs of a project. Each project in cryoSPARC is entirely contained within a file system directory. All the jobs and their respective intermediate and output data created within a project will be stored within the project directory.

* When you start a new project in cryoSPARC GUI, please select and use '''/scratch/gacrc-cryo''' as the cryoSPARC project space.
* This folder is owned by gacrc-cryo. Regular cryoSPARC users have access and read permissions which allow them to browse files in this folder and copy files from this folder to their own storage spaces on Sapelo2.

==== Run job on the master node ====
cryoSPARC will use the master node to run some types of workflow jobs, for example, "Import Movies", "Inspect Picks", and the interactive job "Select 2D Classes". When a job is created, if cryoSPARC will use the master node to run the job, you will be notified about this in cryoSPARC GUI.

==== Run job using "Lane Sapelo2 Default (cluster)" ====

* In cryoSPARC, queue a job to "'''Lane Sapelo2 Default (cluster)'''"; The job will be dispatched to the worker node via Slurm. Please note, gacrc-cryo, instead of your own Sapelo2 user account, is the user account owning and running the job. We highly recommend you to use this method to run cryoSPARC workflow jobs on Sapelo2.
* cryoSPARC will decide on how many CPU cores and how much memory it will use to run a workflow job, depend on the type of the job and your data size. Currently, we configured that from each worker node cryoSPARC can use up to '''20GB''' memory and '''4''' CPU cores.
* If the job needs to run on GPU devices, cryoSPARC will queue the job with a default number of GPU devices , for example 1. You can change this number by yourself in cryoSPARC GUI when you create the job. Please note that the maximum number of GPU devices installed on the worker node is '''4'''.

==Documentation (v4.0+)==

About cryoSPARC: https://guide.cryosparc.com/

Get Started with CryoSPARC: Introductory Tutorial: https://guide.cryosparc.com/processing-data/get-started-with-cryosparc-introductory-tutorial

A Tour of the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/a-tour-of-the-cryosparc-interface

Using the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/using-the-cryosparc-interface

Creating and Running Jobs: https://guide.cryosparc.com/application-guide-v4.0+/creating-and-running-jobs

Tutorial videos: https://guide.cryosparc.com/processing-data/tutorial-videos

==Installation==

*Version 4.3.1 master is installed on the master node (cryosparc.gacrc.uga.edu).
*Version 4.3.1 workers are installed on one worker GPU node (NVIDIA Tesla A100 GPU node).

==System==
64-bit Linux

CryoSPARC-Sapelo2

2026-07-10T15:26:07Z

Moses: /* How to run cryoSPARC from Sapelo2 */

[[Category:Sapelo2]][[Category:Software]][[Category:Engineering]]

== Category ==

Engineering

== Program On ==

Sapelo2

== Version ==

4.3.1

== Author / Distributor ==

See https://guide.cryosparc.com/

== Description ==

"CryoSPARC (Cryo-EM Single Particle Ab-Initio Reconstruction and Classification) is a state of the art HPC software solution for complete processing of single-particle cryo-electron microscopy (cryo-EM) data. CryoSPARC is useful for solving cryo-EM structures of membrane proteins, viruses, complexes, flexible molecules, small particles, phase plate data and negative stain data." For more information, please see https://guide.cryosparc.com/.

'''NOTE''': Users are required to be added into GACRC '''cryosparc''' group before they can run this software from Sapelo2. Please fill out the [https://uga.teamdynamix.com/TDClient/2060/Portal/Requests/ServiceDet?ID=25844 GACRC General Support form] to request. We will reach out to you after we received your request.

== Configurations ==
'''Master node VM:'''

* Host name: '''cryosparc.gacrc.uga.edu'''
* Intel Xeon processors (16 cores) and 64GB of RAM
* mongodb is installed and run on the master node
'''Worker nodes:'''
* One NVIDIA Tesla A100 node: Intel Xeon processors (64 cores), 1TB host RAM memory, 4 NVIDIA Tesla A100 GPU cards (80GiB device memory per card), and NVMe SSD 3570GB local drive.
* cryoSPARC recommends using SSD for caching particle data. /lscratch/gacrc-cryo is set up on the worker node for this purpose.
* The amount of space that cryoSPARC can use in /lscratch/gacrc-cryo is capped at 100GB.
'''cryoSPARC group:''' '''cryosparc'''

'''cryoSPARC service account:''' '''gacrc-cryo'''

* gacrc-cryo is the '''service account''' that will run cryoSPARC workflow jobs for all cryoSPARC users.
* Some tasks can only be handled by gacrc-cryo, like make a new lane of worker node(s), user management, and connect or update worker node(s) to master, etc..
* Regular CryoSPARC users can run cryosparcm on the master node to check cryoSPARC status, using cryosparcm status or cryosparcm checkdb.

'''cryoSPARC project space:''' '''/scratch/gacrc-cryo'''
== How to run cryoSPARC from Sapelo2 ==

=== User Login ===

There are two ways to access the CryoSPARC web interface. The recommended method is to connect through the UGA VPN and access the CryoSPARC web server directly. SSH tunneling remains available as an alternative if needed.

=== Method 1 (Recommended): VPN + Direct Web Access ===

# Connect to the UGA VPN using the Cisco Secure Client (Cisco AnyConnect) and select '''remote.uga.edu'''.
#: '''Note:''' Even if you are working on campus, you must still connect to the UGA VPN before accessing the CryoSPARC web server.
# Open the URL for your assigned CryoSPARC instance in your web browser. For example:
#:
#: <code>http://cryosparc.gacrc.uga.edu:39000</code>
# Log in using your registered UGA email address and CryoSPARC password.
#:
#: '''Note:''' Your registered UGA email address may be an email alias rather than your official '''MyID@uga.edu''' address. Please use the email address that was registered with your CryoSPARC account.

=== Method 2: SSH Tunnel ===

Users may also access CryoSPARC by establishing an SSH tunnel to expose port 39000 from the CryoSPARC master node to their local computer.

If you are using Linux or macOS, run the following command in a terminal:

<pre>
ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu
</pre>

If you are using Windows, download '''[https://the.earth.li/~sgtatham/putty/latest/x86/plink.exe plink program]''' and run:

<pre>
plink -ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu
</pre>

Place <code>plink.exe</code> in your current working directory, or specify its full path when running the command.

Unless you have configured SSH public key authentication, you will be prompted for your UGA MyID password and Duo authentication. After authentication succeeds, the SSH session will remain open. This is expected and indicates that the tunnel has been established successfully.

With the SSH tunnel active, open your web browser and navigate to:

<pre>
http://localhost:39000
</pre>

The CryoSPARC login page should appear.

=== Troubleshooting ===

If you are unable to access the CryoSPARC web interface:

* Verify that you are connected to the UGA VPN if you are using the recommended VPN + Direct Web Access method.
* Confirm that you are using the correct URL for your assigned CryoSPARC instance.
* Make sure you are logging in with your registered UGA email address and CryoSPARC password. Your registered UGA email address may be an email alias rather than your official MyID@uga.edu address.
* If you are using the SSH tunnel method, ensure that the SSH session remains active while accessing the web interface.
* If you have forgotten your CryoSPARC password, contact GACRC Support to request a password reset token.
* If the problem persists, please contact GACRC Support and include:
** The URL you are using to access CryoSPARC.
** Your UGA MyID and your registered UGA email address.
** A screenshot of the error message or the login/password reset screen, if applicable.

=== Run cryoSPARC workflow jobs ===

==== Project space selection ====
A project in cryoSPARC is a high level container corresponding with a project directory on the file system, which stores all associated Jobs of a project. Each project in cryoSPARC is entirely contained within a file system directory. All the jobs and their respective intermediate and output data created within a project will be stored within the project directory.

* When you start a new project in cryoSPARC GUI, please select and use '''/scratch/gacrc-cryo''' as the cryoSPARC project space.
* This folder is owned by gacrc-cryo. Regular cryoSPARC users have access and read permissions which allow them to browse files in this folder and copy files from this folder to their own storage spaces on Sapelo2.

==== Run job on the master node ====
cryoSPARC will use the master node to run some types of workflow jobs, for example, "Import Movies", "Inspect Picks", and the interactive job "Select 2D Classes". When a job is created, if cryoSPARC will use the master node to run the job, you will be notified about this in cryoSPARC GUI.

==== Run job using "Lane Sapelo2 Default (cluster)" ====

* In cryoSPARC, queue a job to "'''Lane Sapelo2 Default (cluster)'''"; The job will be dispatched to the worker node via Slurm. Please note, gacrc-cryo, instead of your own Sapelo2 user account, is the user account owning and running the job. We highly recommend you to use this method to run cryoSPARC workflow jobs on Sapelo2.
* cryoSPARC will decide on how many CPU cores and how much memory it will use to run a workflow job, depend on the type of the job and your data size. Currently, we configured that from each worker node cryoSPARC can use up to '''20GB''' memory and '''4''' CPU cores.
* If the job needs to run on GPU devices, cryoSPARC will queue the job with a default number of GPU devices , for example 1. You can change this number by yourself in cryoSPARC GUI when you create the job. Please note that the maximum number of GPU devices installed on the worker node is '''4'''.

==Documentation (v4.0+)==

About cryoSPARC: https://guide.cryosparc.com/

Get Started with CryoSPARC: Introductory Tutorial: https://guide.cryosparc.com/processing-data/get-started-with-cryosparc-introductory-tutorial

A Tour of the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/a-tour-of-the-cryosparc-interface

Using the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/using-the-cryosparc-interface

Creating and Running Jobs: https://guide.cryosparc.com/application-guide-v4.0+/creating-and-running-jobs

Tutorial videos: https://guide.cryosparc.com/processing-data/tutorial-videos

==Installation==

*Version 4.3.1 master is installed on the master node (cryosparc.gacrc.uga.edu).
*Version 4.3.1 workers are installed on one worker GPU node (NVIDIA Tesla A100 GPU node).

==System==
64-bit Linux

CryoSPARC-Sapelo2

2026-07-10T15:22:30Z

Moses: /* Troubleshooting */

[[Category:Sapelo2]][[Category:Software]][[Category:Engineering]]

== Category ==

Engineering

== Program On ==

Sapelo2

== Version ==

4.3.1

== Author / Distributor ==

See https://guide.cryosparc.com/

== Description ==

"CryoSPARC (Cryo-EM Single Particle Ab-Initio Reconstruction and Classification) is a state of the art HPC software solution for complete processing of single-particle cryo-electron microscopy (cryo-EM) data. CryoSPARC is useful for solving cryo-EM structures of membrane proteins, viruses, complexes, flexible molecules, small particles, phase plate data and negative stain data." For more information, please see https://guide.cryosparc.com/.

'''NOTE''': Users are required to be added into GACRC '''cryosparc''' group before they can run this software from Sapelo2. Please fill out the [https://uga.teamdynamix.com/TDClient/2060/Portal/Requests/ServiceDet?ID=25844 GACRC General Support form] to request. We will reach out to you after we received your request.

== Configurations ==
'''Master node VM:'''

* Host name: '''cryosparc.gacrc.uga.edu'''
* Intel Xeon processors (16 cores) and 64GB of RAM
* mongodb is installed and run on the master node
'''Worker nodes:'''
* One NVIDIA Tesla A100 node: Intel Xeon processors (64 cores), 1TB host RAM memory, 4 NVIDIA Tesla A100 GPU cards (80GiB device memory per card), and NVMe SSD 3570GB local drive.
* cryoSPARC recommends using SSD for caching particle data. /lscratch/gacrc-cryo is set up on the worker node for this purpose.
* The amount of space that cryoSPARC can use in /lscratch/gacrc-cryo is capped at 100GB.
'''cryoSPARC group:''' '''cryosparc'''

'''cryoSPARC service account:''' '''gacrc-cryo'''

* gacrc-cryo is the '''service account''' that will run cryoSPARC workflow jobs for all cryoSPARC users.
* Some tasks can only be handled by gacrc-cryo, like make a new lane of worker node(s), user management, and connect or update worker node(s) to master, etc..
* Regular CryoSPARC users can run cryosparcm on the master node to check cryoSPARC status, using cryosparcm status or cryosparcm checkdb.

'''cryoSPARC project space:''' '''/scratch/gacrc-cryo'''
#

== How to run cryoSPARC from Sapelo2 ==

=== User login ===

== User Login ==

There are two ways to access the CryoSPARC web interface. The recommended method is to connect through the UGA VPN and access the CryoSPARC web server directly. SSH tunneling remains available as an alternative if needed.

=== Method 1 (Recommended): VPN + Direct Web Access ===

# Connect to the UGA VPN using the Cisco Secure Client (Cisco AnyConnect) and select '''remote.uga.edu'''.
#: '''Note:''' Even if you are working on campus, you must still connect to the UGA VPN before accessing the CryoSPARC web server.
# Open the URL for your assigned CryoSPARC instance in your web browser. For example:
#:
#: <code>http://cryosparc.gacrc.uga.edu:39000</code>
# Log in using your registered UGA email address and CryoSPARC password.
#:
#: '''Note:''' Your registered UGA email address may be an email alias rather than your official '''MyID@uga.edu''' address. Please use the email address that was registered with your CryoSPARC account.

=== Method 2: SSH Tunnel ===

Users may also access CryoSPARC by establishing an SSH tunnel to expose port 39000 from the CryoSPARC master node to their local computer.

If you are using Linux or macOS, run the following command in a terminal:

<pre>
ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu
</pre>

If you are using Windows, download '''[https://the.earth.li/~sgtatham/putty/latest/x86/plink.exe plink program]''' and run:

<pre>
plink -ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu
</pre>

Place <code>plink.exe</code> in your current working directory, or specify its full path when running the command.

Unless you have configured SSH public key authentication, you will be prompted for your UGA MyID password and Duo authentication. After authentication succeeds, the SSH session will remain open. This is expected and indicates that the tunnel has been established successfully.

With the SSH tunnel active, open your web browser and navigate to:

<pre>
http://localhost:39000
</pre>

The CryoSPARC login page should appear.

=== Troubleshooting ===

If you are unable to access the CryoSPARC web interface:

* Verify that you are connected to the UGA VPN if you are using the recommended VPN + Direct Web Access method.
* Confirm that you are using the correct URL for your assigned CryoSPARC instance.
* Make sure you are logging in with your registered UGA email address and CryoSPARC password. Your registered UGA email address may be an email alias rather than your official MyID@uga.edu address.
* If you are using the SSH tunnel method, ensure that the SSH session remains active while accessing the web interface.
* If you have forgotten your CryoSPARC password, contact GACRC Support to request a password reset token.
* If the problem persists, please contact GACRC Support and include:
** The URL you are using to access CryoSPARC.
** Your UGA MyID and your registered UGA email address.
** A screenshot of the error message or the login/password reset screen, if applicable.

=== Run cryoSPARC workflow jobs ===

==== Project space selection ====
A project in cryoSPARC is a high level container corresponding with a project directory on the file system, which stores all associated Jobs of a project. Each project in cryoSPARC is entirely contained within a file system directory. All the jobs and their respective intermediate and output data created within a project will be stored within the project directory.

* When you start a new project in cryoSPARC GUI, please select and use '''/scratch/gacrc-cryo''' as the cryoSPARC project space.
* This folder is owned by gacrc-cryo. Regular cryoSPARC users have access and read permissions which allow them to browse files in this folder and copy files from this folder to their own storage spaces on Sapelo2.

==== Run job on the master node ====
cryoSPARC will use the master node to run some types of workflow jobs, for example, "Import Movies", "Inspect Picks", and the interactive job "Select 2D Classes". When a job is created, if cryoSPARC will use the master node to run the job, you will be notified about this in cryoSPARC GUI.

==== Run job using "Lane Sapelo2 Default (cluster)" ====

* In cryoSPARC, queue a job to "'''Lane Sapelo2 Default (cluster)'''"; The job will be dispatched to the worker node via Slurm. Please note, gacrc-cryo, instead of your own Sapelo2 user account, is the user account owning and running the job. We highly recommend you to use this method to run cryoSPARC workflow jobs on Sapelo2.
* cryoSPARC will decide on how many CPU cores and how much memory it will use to run a workflow job, depend on the type of the job and your data size. Currently, we configured that from each worker node cryoSPARC can use up to '''20GB''' memory and '''4''' CPU cores.
* If the job needs to run on GPU devices, cryoSPARC will queue the job with a default number of GPU devices , for example 1. You can change this number by yourself in cryoSPARC GUI when you create the job. Please note that the maximum number of GPU devices installed on the worker node is '''4'''.

==Documentation (v4.0+)==

About cryoSPARC: https://guide.cryosparc.com/

Get Started with CryoSPARC: Introductory Tutorial: https://guide.cryosparc.com/processing-data/get-started-with-cryosparc-introductory-tutorial

A Tour of the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/a-tour-of-the-cryosparc-interface

Using the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/using-the-cryosparc-interface

Creating and Running Jobs: https://guide.cryosparc.com/application-guide-v4.0+/creating-and-running-jobs

Tutorial videos: https://guide.cryosparc.com/processing-data/tutorial-videos

==Installation==

*Version 4.3.1 master is installed on the master node (cryosparc.gacrc.uga.edu).
*Version 4.3.1 workers are installed on one worker GPU node (NVIDIA Tesla A100 GPU node).

==System==
64-bit Linux

CryoSPARC-Sapelo2

2026-07-10T15:09:51Z

Moses: /* Method 1 (Recommended): VPN + Direct Web Access */

[[Category:Sapelo2]][[Category:Software]][[Category:Engineering]]

== Category ==

Engineering

== Program On ==

Sapelo2

== Version ==

4.3.1

== Author / Distributor ==

See https://guide.cryosparc.com/

== Description ==

"CryoSPARC (Cryo-EM Single Particle Ab-Initio Reconstruction and Classification) is a state of the art HPC software solution for complete processing of single-particle cryo-electron microscopy (cryo-EM) data. CryoSPARC is useful for solving cryo-EM structures of membrane proteins, viruses, complexes, flexible molecules, small particles, phase plate data and negative stain data." For more information, please see https://guide.cryosparc.com/.

'''NOTE''': Users are required to be added into GACRC '''cryosparc''' group before they can run this software from Sapelo2. Please fill out the [https://uga.teamdynamix.com/TDClient/2060/Portal/Requests/ServiceDet?ID=25844 GACRC General Support form] to request. We will reach out to you after we received your request.

== Configurations ==
'''Master node VM:'''

* Host name: '''cryosparc.gacrc.uga.edu'''
* Intel Xeon processors (16 cores) and 64GB of RAM
* mongodb is installed and run on the master node
'''Worker nodes:'''
* One NVIDIA Tesla A100 node: Intel Xeon processors (64 cores), 1TB host RAM memory, 4 NVIDIA Tesla A100 GPU cards (80GiB device memory per card), and NVMe SSD 3570GB local drive.
* cryoSPARC recommends using SSD for caching particle data. /lscratch/gacrc-cryo is set up on the worker node for this purpose.
* The amount of space that cryoSPARC can use in /lscratch/gacrc-cryo is capped at 100GB.
'''cryoSPARC group:''' '''cryosparc'''

'''cryoSPARC service account:''' '''gacrc-cryo'''

* gacrc-cryo is the '''service account''' that will run cryoSPARC workflow jobs for all cryoSPARC users.
* Some tasks can only be handled by gacrc-cryo, like make a new lane of worker node(s), user management, and connect or update worker node(s) to master, etc..
* Regular CryoSPARC users can run cryosparcm on the master node to check cryoSPARC status, using cryosparcm status or cryosparcm checkdb.

'''cryoSPARC project space:''' '''/scratch/gacrc-cryo'''
#

== How to run cryoSPARC from Sapelo2 ==

=== User login ===

== User Login ==

There are two ways to access the CryoSPARC web interface. The recommended method is to connect through the UGA VPN and access the CryoSPARC web server directly. SSH tunneling remains available as an alternative if needed.

=== Method 1 (Recommended): VPN + Direct Web Access ===

# Connect to the UGA VPN using the Cisco Secure Client (Cisco AnyConnect) and select '''remote.uga.edu'''.
#: '''Note:''' Even if you are working on campus, you must still connect to the UGA VPN before accessing the CryoSPARC web server.
# Open the URL for your assigned CryoSPARC instance in your web browser. For example:
#:
#: <code>http://cryosparc.gacrc.uga.edu:39000</code>
# Log in using your registered UGA email address and password.
#:
#: '''Note:''' Your registered UGA email address may be an email alias rather than your official '''MyID@uga.edu''' address. Please use the email address that was registered with your CryoSPARC account.

=== Method 2: SSH Tunnel ===

Users may also access CryoSPARC by establishing an SSH tunnel to expose port 39000 from the CryoSPARC master node to their local computer.

If you are using Linux or macOS, run the following command in a terminal:

<pre>
ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu
</pre>

If you are using Windows, download '''[https://the.earth.li/~sgtatham/putty/latest/x86/plink.exe plink program]''' and run:

<pre>
plink -ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu
</pre>

Place <code>plink.exe</code> in your current working directory, or specify its full path when running the command.

Unless you have configured SSH public key authentication, you will be prompted for your UGA MyID password and Duo authentication. After authentication succeeds, the SSH session will remain open. This is expected and indicates that the tunnel has been established successfully.

With the SSH tunnel active, open your web browser and navigate to:

<pre>
http://localhost:39000
</pre>

The CryoSPARC login page should appear.

=== Troubleshooting ===

If you are unable to access the CryoSPARC web interface:

* Verify that you are connected to the UGA VPN when using the recommended access method.
* Confirm that you are using the correct URL for your assigned CryoSPARC instance.
* Make sure you are logging in with your registered CryoSPARC username (your UGA email address, not your MyID).
* If using the SSH tunnel method, ensure that the SSH session remains active while accessing the web interface.
* If you have forgotten your CryoSPARC password, contact GACRC Support to request a password reset token.
* If the problem persists, please contact GACRC Support and include:
** The URL you are using to access CryoSPARC.
** Your CryoSPARC username.
** A screenshot of the error message or TOKEN prompt, if applicable.

=== Run cryoSPARC workflow jobs ===

==== Project space selection ====
A project in cryoSPARC is a high level container corresponding with a project directory on the file system, which stores all associated Jobs of a project. Each project in cryoSPARC is entirely contained within a file system directory. All the jobs and their respective intermediate and output data created within a project will be stored within the project directory.

* When you start a new project in cryoSPARC GUI, please select and use '''/scratch/gacrc-cryo''' as the cryoSPARC project space.
* This folder is owned by gacrc-cryo. Regular cryoSPARC users have access and read permissions which allow them to browse files in this folder and copy files from this folder to their own storage spaces on Sapelo2.

==== Run job on the master node ====
cryoSPARC will use the master node to run some types of workflow jobs, for example, "Import Movies", "Inspect Picks", and the interactive job "Select 2D Classes". When a job is created, if cryoSPARC will use the master node to run the job, you will be notified about this in cryoSPARC GUI.

==== Run job using "Lane Sapelo2 Default (cluster)" ====

* In cryoSPARC, queue a job to "'''Lane Sapelo2 Default (cluster)'''"; The job will be dispatched to the worker node via Slurm. Please note, gacrc-cryo, instead of your own Sapelo2 user account, is the user account owning and running the job. We highly recommend you to use this method to run cryoSPARC workflow jobs on Sapelo2.
* cryoSPARC will decide on how many CPU cores and how much memory it will use to run a workflow job, depend on the type of the job and your data size. Currently, we configured that from each worker node cryoSPARC can use up to '''20GB''' memory and '''4''' CPU cores.
* If the job needs to run on GPU devices, cryoSPARC will queue the job with a default number of GPU devices , for example 1. You can change this number by yourself in cryoSPARC GUI when you create the job. Please note that the maximum number of GPU devices installed on the worker node is '''4'''.

==Documentation (v4.0+)==

About cryoSPARC: https://guide.cryosparc.com/

Get Started with CryoSPARC: Introductory Tutorial: https://guide.cryosparc.com/processing-data/get-started-with-cryosparc-introductory-tutorial

A Tour of the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/a-tour-of-the-cryosparc-interface

Using the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/using-the-cryosparc-interface

Creating and Running Jobs: https://guide.cryosparc.com/application-guide-v4.0+/creating-and-running-jobs

Tutorial videos: https://guide.cryosparc.com/processing-data/tutorial-videos

==Installation==

*Version 4.3.1 master is installed on the master node (cryosparc.gacrc.uga.edu).
*Version 4.3.1 workers are installed on one worker GPU node (NVIDIA Tesla A100 GPU node).

==System==
64-bit Linux

CryoSPARC-Sapelo2

2026-07-10T15:04:46Z

Moses: /* User Login */

[[Category:Sapelo2]][[Category:Software]][[Category:Engineering]]

== Category ==

Engineering

== Program On ==

Sapelo2

== Version ==

4.3.1

== Author / Distributor ==

See https://guide.cryosparc.com/

== Description ==

"CryoSPARC (Cryo-EM Single Particle Ab-Initio Reconstruction and Classification) is a state of the art HPC software solution for complete processing of single-particle cryo-electron microscopy (cryo-EM) data. CryoSPARC is useful for solving cryo-EM structures of membrane proteins, viruses, complexes, flexible molecules, small particles, phase plate data and negative stain data." For more information, please see https://guide.cryosparc.com/.

'''NOTE''': Users are required to be added into GACRC '''cryosparc''' group before they can run this software from Sapelo2. Please fill out the [https://uga.teamdynamix.com/TDClient/2060/Portal/Requests/ServiceDet?ID=25844 GACRC General Support form] to request. We will reach out to you after we received your request.

== Configurations ==
'''Master node VM:'''

* Host name: '''cryosparc.gacrc.uga.edu'''
* Intel Xeon processors (16 cores) and 64GB of RAM
* mongodb is installed and run on the master node
'''Worker nodes:'''
* One NVIDIA Tesla A100 node: Intel Xeon processors (64 cores), 1TB host RAM memory, 4 NVIDIA Tesla A100 GPU cards (80GiB device memory per card), and NVMe SSD 3570GB local drive.
* cryoSPARC recommends using SSD for caching particle data. /lscratch/gacrc-cryo is set up on the worker node for this purpose.
* The amount of space that cryoSPARC can use in /lscratch/gacrc-cryo is capped at 100GB.
'''cryoSPARC group:''' '''cryosparc'''

'''cryoSPARC service account:''' '''gacrc-cryo'''

* gacrc-cryo is the '''service account''' that will run cryoSPARC workflow jobs for all cryoSPARC users.
* Some tasks can only be handled by gacrc-cryo, like make a new lane of worker node(s), user management, and connect or update worker node(s) to master, etc..
* Regular CryoSPARC users can run cryosparcm on the master node to check cryoSPARC status, using cryosparcm status or cryosparcm checkdb.

'''cryoSPARC project space:''' '''/scratch/gacrc-cryo'''
#

== How to run cryoSPARC from Sapelo2 ==

=== User login ===

== User Login ==

There are two ways to access the CryoSPARC web interface. The recommended method is to connect through the UGA VPN and access the CryoSPARC web server directly. SSH tunneling remains available as an alternative if needed.

=== Method 1 (Recommended): VPN + Direct Web Access ===

# Connect to the UGA VPN using the Cisco Secure Client and select '''remote.uga.edu'''.
#: '''Note:''' If you are working on campus, you still need to connect to UGA VPN before accessing the CryoSPARC web server.
# Open the URL for your assigned CryoSPARC instance in your web browser. For example:
#:
#: <code>http://cryosparc.gacrc.uga.edu:39000</code>
# Log in using your registered UGA email address and password.
#:
#: '''Note:''' Your registered UGA email may be an alias to your official UGA email, i.e. <code>MyID@uga.edu</code>.

=== Method 2: SSH Tunnel ===

Users may also access CryoSPARC by establishing an SSH tunnel to expose port 39000 from the CryoSPARC master node to their local computer.

If you are using Linux or macOS, run the following command in a terminal:

<pre>
ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu
</pre>

If you are using Windows, download '''[https://the.earth.li/~sgtatham/putty/latest/x86/plink.exe plink program]''' and run:

<pre>
plink -ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu
</pre>

Place <code>plink.exe</code> in your current working directory, or specify its full path when running the command.

Unless you have configured SSH public key authentication, you will be prompted for your UGA MyID password and Duo authentication. After authentication succeeds, the SSH session will remain open. This is expected and indicates that the tunnel has been established successfully.

With the SSH tunnel active, open your web browser and navigate to:

<pre>
http://localhost:39000
</pre>

The CryoSPARC login page should appear.

=== Troubleshooting ===

If you are unable to access the CryoSPARC web interface:

* Verify that you are connected to the UGA VPN when using the recommended access method.
* Confirm that you are using the correct URL for your assigned CryoSPARC instance.
* Make sure you are logging in with your registered CryoSPARC username (your UGA email address, not your MyID).
* If using the SSH tunnel method, ensure that the SSH session remains active while accessing the web interface.
* If you have forgotten your CryoSPARC password, contact GACRC Support to request a password reset token.
* If the problem persists, please contact GACRC Support and include:
** The URL you are using to access CryoSPARC.
** Your CryoSPARC username.
** A screenshot of the error message or TOKEN prompt, if applicable.

=== Run cryoSPARC workflow jobs ===

==== Project space selection ====
A project in cryoSPARC is a high level container corresponding with a project directory on the file system, which stores all associated Jobs of a project. Each project in cryoSPARC is entirely contained within a file system directory. All the jobs and their respective intermediate and output data created within a project will be stored within the project directory.

* When you start a new project in cryoSPARC GUI, please select and use '''/scratch/gacrc-cryo''' as the cryoSPARC project space.
* This folder is owned by gacrc-cryo. Regular cryoSPARC users have access and read permissions which allow them to browse files in this folder and copy files from this folder to their own storage spaces on Sapelo2.

==== Run job on the master node ====
cryoSPARC will use the master node to run some types of workflow jobs, for example, "Import Movies", "Inspect Picks", and the interactive job "Select 2D Classes". When a job is created, if cryoSPARC will use the master node to run the job, you will be notified about this in cryoSPARC GUI.

==== Run job using "Lane Sapelo2 Default (cluster)" ====

* In cryoSPARC, queue a job to "'''Lane Sapelo2 Default (cluster)'''"; The job will be dispatched to the worker node via Slurm. Please note, gacrc-cryo, instead of your own Sapelo2 user account, is the user account owning and running the job. We highly recommend you to use this method to run cryoSPARC workflow jobs on Sapelo2.
* cryoSPARC will decide on how many CPU cores and how much memory it will use to run a workflow job, depend on the type of the job and your data size. Currently, we configured that from each worker node cryoSPARC can use up to '''20GB''' memory and '''4''' CPU cores.
* If the job needs to run on GPU devices, cryoSPARC will queue the job with a default number of GPU devices , for example 1. You can change this number by yourself in cryoSPARC GUI when you create the job. Please note that the maximum number of GPU devices installed on the worker node is '''4'''.

==Documentation (v4.0+)==

About cryoSPARC: https://guide.cryosparc.com/

Get Started with CryoSPARC: Introductory Tutorial: https://guide.cryosparc.com/processing-data/get-started-with-cryosparc-introductory-tutorial

A Tour of the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/a-tour-of-the-cryosparc-interface

Using the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/using-the-cryosparc-interface

Creating and Running Jobs: https://guide.cryosparc.com/application-guide-v4.0+/creating-and-running-jobs

Tutorial videos: https://guide.cryosparc.com/processing-data/tutorial-videos

==Installation==

*Version 4.3.1 master is installed on the master node (cryosparc.gacrc.uga.edu).
*Version 4.3.1 workers are installed on one worker GPU node (NVIDIA Tesla A100 GPU node).

==System==
64-bit Linux

CryoSPARC-Sapelo2

2026-07-10T14:49:12Z

Moses: /* User Login */

[[Category:Sapelo2]][[Category:Software]][[Category:Engineering]]

== Category ==

Engineering

== Program On ==

Sapelo2

== Version ==

4.3.1

== Author / Distributor ==

See https://guide.cryosparc.com/

== Description ==

"CryoSPARC (Cryo-EM Single Particle Ab-Initio Reconstruction and Classification) is a state of the art HPC software solution for complete processing of single-particle cryo-electron microscopy (cryo-EM) data. CryoSPARC is useful for solving cryo-EM structures of membrane proteins, viruses, complexes, flexible molecules, small particles, phase plate data and negative stain data." For more information, please see https://guide.cryosparc.com/.

'''NOTE''': Users are required to be added into GACRC '''cryosparc''' group before they can run this software from Sapelo2. Please fill out the [https://uga.teamdynamix.com/TDClient/2060/Portal/Requests/ServiceDet?ID=25844 GACRC General Support form] to request. We will reach out to you after we received your request.

== Configurations ==
'''Master node VM:'''

* Host name: '''cryosparc.gacrc.uga.edu'''
* Intel Xeon processors (16 cores) and 64GB of RAM
* mongodb is installed and run on the master node
'''Worker nodes:'''
* One NVIDIA Tesla A100 node: Intel Xeon processors (64 cores), 1TB host RAM memory, 4 NVIDIA Tesla A100 GPU cards (80GiB device memory per card), and NVMe SSD 3570GB local drive.
* cryoSPARC recommends using SSD for caching particle data. /lscratch/gacrc-cryo is set up on the worker node for this purpose.
* The amount of space that cryoSPARC can use in /lscratch/gacrc-cryo is capped at 100GB.
'''cryoSPARC group:''' '''cryosparc'''

'''cryoSPARC service account:''' '''gacrc-cryo'''

* gacrc-cryo is the '''service account''' that will run cryoSPARC workflow jobs for all cryoSPARC users.
* Some tasks can only be handled by gacrc-cryo, like make a new lane of worker node(s), user management, and connect or update worker node(s) to master, etc..
* Regular CryoSPARC users can run cryosparcm on the master node to check cryoSPARC status, using cryosparcm status or cryosparcm checkdb.

'''cryoSPARC project space:''' '''/scratch/gacrc-cryo'''
#

== How to run cryoSPARC from Sapelo2 ==

=== User login ===

== User Login ==

There are two ways to access the CryoSPARC web interface. The recommended method is to connect through the UGA VPN and access the CryoSPARC web server directly. SSH tunneling remains available as an alternative if needed.

=== Method 1 (Recommended): VPN + Direct Web Access ===

# Connect to the UGA VPN using the Cisco Secure Client and select '''remote.uga.edu'''.
# Open the URL for your assigned CryoSPARC instance in your web browser. For example:
#:
#: <code>http://cryosparc-cp2lab.gacrc.uga.edu:39000</code>
# Log in using your CryoSPARC username and password.
#:
#: '''Note:''' Your CryoSPARC username is your registered UGA email address (for example, <code>firstname.lastname@uga.edu</code>), which may differ from your UGA MyID.

=== Method 2: SSH Tunnel ===

Users may also access CryoSPARC by establishing an SSH tunnel to expose port 39000 from the CryoSPARC master node to their local computer.

If you are using Linux or macOS, run the following command in a terminal:

<pre>
ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu
</pre>

If you are using Windows, download '''[https://the.earth.li/~sgtatham/putty/latest/x86/plink.exe plink program]''' and run:

<pre>
plink -ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu
</pre>

Place <code>plink.exe</code> in your current working directory, or specify its full path when running the command.

Unless you have configured SSH public key authentication, you will be prompted for your UGA MyID password and Duo authentication. After authentication succeeds, the SSH session will remain open. This is expected and indicates that the tunnel has been established successfully.

With the SSH tunnel active, open your web browser and navigate to:

<pre>
http://localhost:39000
</pre>

The CryoSPARC login page should appear.

=== Troubleshooting ===

If you are unable to access the CryoSPARC web interface:

* Verify that you are connected to the UGA VPN when using the recommended access method.
* Confirm that you are using the correct URL for your assigned CryoSPARC instance.
* Make sure you are logging in with your registered CryoSPARC username (your UGA email address, not your MyID).
* If using the SSH tunnel method, ensure that the SSH session remains active while accessing the web interface.
* If you have forgotten your CryoSPARC password, contact GACRC Support to request a password reset token.
* If the problem persists, please contact GACRC Support and include:
** The URL you are using to access CryoSPARC.
** Your CryoSPARC username.
** A screenshot of the error message or TOKEN prompt, if applicable.

=== Run cryoSPARC workflow jobs ===

==== Project space selection ====
A project in cryoSPARC is a high level container corresponding with a project directory on the file system, which stores all associated Jobs of a project. Each project in cryoSPARC is entirely contained within a file system directory. All the jobs and their respective intermediate and output data created within a project will be stored within the project directory.

* When you start a new project in cryoSPARC GUI, please select and use '''/scratch/gacrc-cryo''' as the cryoSPARC project space.
* This folder is owned by gacrc-cryo. Regular cryoSPARC users have access and read permissions which allow them to browse files in this folder and copy files from this folder to their own storage spaces on Sapelo2.

==== Run job on the master node ====
cryoSPARC will use the master node to run some types of workflow jobs, for example, "Import Movies", "Inspect Picks", and the interactive job "Select 2D Classes". When a job is created, if cryoSPARC will use the master node to run the job, you will be notified about this in cryoSPARC GUI.

==== Run job using "Lane Sapelo2 Default (cluster)" ====

* In cryoSPARC, queue a job to "'''Lane Sapelo2 Default (cluster)'''"; The job will be dispatched to the worker node via Slurm. Please note, gacrc-cryo, instead of your own Sapelo2 user account, is the user account owning and running the job. We highly recommend you to use this method to run cryoSPARC workflow jobs on Sapelo2.
* cryoSPARC will decide on how many CPU cores and how much memory it will use to run a workflow job, depend on the type of the job and your data size. Currently, we configured that from each worker node cryoSPARC can use up to '''20GB''' memory and '''4''' CPU cores.
* If the job needs to run on GPU devices, cryoSPARC will queue the job with a default number of GPU devices , for example 1. You can change this number by yourself in cryoSPARC GUI when you create the job. Please note that the maximum number of GPU devices installed on the worker node is '''4'''.

==Documentation (v4.0+)==

About cryoSPARC: https://guide.cryosparc.com/

Get Started with CryoSPARC: Introductory Tutorial: https://guide.cryosparc.com/processing-data/get-started-with-cryosparc-introductory-tutorial

A Tour of the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/a-tour-of-the-cryosparc-interface

Using the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/using-the-cryosparc-interface

Creating and Running Jobs: https://guide.cryosparc.com/application-guide-v4.0+/creating-and-running-jobs

Tutorial videos: https://guide.cryosparc.com/processing-data/tutorial-videos

==Installation==

*Version 4.3.1 master is installed on the master node (cryosparc.gacrc.uga.edu).
*Version 4.3.1 workers are installed on one worker GPU node (NVIDIA Tesla A100 GPU node).

==System==
64-bit Linux

CryoSPARC-Sapelo2

2026-07-10T14:47:07Z

Moses: /* User login */

[[Category:Sapelo2]][[Category:Software]][[Category:Engineering]]

== Category ==

Engineering

== Program On ==

Sapelo2

== Version ==

4.3.1

== Author / Distributor ==

See https://guide.cryosparc.com/

== Description ==

"CryoSPARC (Cryo-EM Single Particle Ab-Initio Reconstruction and Classification) is a state of the art HPC software solution for complete processing of single-particle cryo-electron microscopy (cryo-EM) data. CryoSPARC is useful for solving cryo-EM structures of membrane proteins, viruses, complexes, flexible molecules, small particles, phase plate data and negative stain data." For more information, please see https://guide.cryosparc.com/.

'''NOTE''': Users are required to be added into GACRC '''cryosparc''' group before they can run this software from Sapelo2. Please fill out the [https://uga.teamdynamix.com/TDClient/2060/Portal/Requests/ServiceDet?ID=25844 GACRC General Support form] to request. We will reach out to you after we received your request.

== Configurations ==
'''Master node VM:'''

* Host name: '''cryosparc.gacrc.uga.edu'''
* Intel Xeon processors (16 cores) and 64GB of RAM
* mongodb is installed and run on the master node
'''Worker nodes:'''
* One NVIDIA Tesla A100 node: Intel Xeon processors (64 cores), 1TB host RAM memory, 4 NVIDIA Tesla A100 GPU cards (80GiB device memory per card), and NVMe SSD 3570GB local drive.
* cryoSPARC recommends using SSD for caching particle data. /lscratch/gacrc-cryo is set up on the worker node for this purpose.
* The amount of space that cryoSPARC can use in /lscratch/gacrc-cryo is capped at 100GB.
'''cryoSPARC group:''' '''cryosparc'''

'''cryoSPARC service account:''' '''gacrc-cryo'''

* gacrc-cryo is the '''service account''' that will run cryoSPARC workflow jobs for all cryoSPARC users.
* Some tasks can only be handled by gacrc-cryo, like make a new lane of worker node(s), user management, and connect or update worker node(s) to master, etc..
* Regular CryoSPARC users can run cryosparcm on the master node to check cryoSPARC status, using cryosparcm status or cryosparcm checkdb.

'''cryoSPARC project space:''' '''/scratch/gacrc-cryo'''
#

== How to run cryoSPARC from Sapelo2 ==

=== User login ===

== User Login ==

There are two ways to access the CryoSPARC web interface. The recommended method is to connect through the UGA VPN and access the CryoSPARC web server directly. SSH tunneling remains available as an alternative if needed.

=== Method 1 (Recommended): VPN + Direct Web Access ===

# Connect to the UGA VPN using the Cisco Secure Client and select '''remote.uga.edu'''.
# Open the URL for your assigned CryoSPARC instance in your web browser. For example:
#:
#: <code>http://cryosparc-cp2lab.gacrc.uga.edu:39000</code>
# Log in using your CryoSPARC username and password.
#:
#: '''Note:''' Your CryoSPARC username is your registered UGA email address (for example, <code>firstname.lastname@uga.edu</code>), which may differ from your UGA MyID.

=== Method 2: SSH Tunnel ===

Users may also access CryoSPARC by establishing an SSH tunnel to expose port 39000 from the CryoSPARC master node to their local computer.

If you are using Linux or macOS, run the following command in a terminal:

<pre>
ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu
</pre>

If you are using Windows, download '''plink.exe''' and run:

<pre>
plink -ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu
</pre>

Place <code>plink.exe</code> in your current working directory, or specify its full path when running the command.

Unless you have configured SSH public key authentication, you will be prompted for your UGA MyID password and Duo authentication. After authentication succeeds, the SSH session will remain open. This is expected and indicates that the tunnel has been established successfully.

With the SSH tunnel active, open your web browser and navigate to:

<pre>
http://localhost:39000
</pre>

The CryoSPARC login page should appear.

=== Troubleshooting ===

If you are unable to access the CryoSPARC web interface:

* Verify that you are connected to the UGA VPN when using the recommended access method.
* Confirm that you are using the correct URL for your assigned CryoSPARC instance.
* Make sure you are logging in with your registered CryoSPARC username (your UGA email address, not your MyID).
* If using the SSH tunnel method, ensure that the SSH session remains active while accessing the web interface.
* If you have forgotten your CryoSPARC password, contact GACRC Support to request a password reset token.
* If the problem persists, please contact GACRC Support and include:
** The URL you are using to access CryoSPARC.
** Your CryoSPARC username.
** A screenshot of the error message or TOKEN prompt, if applicable.

==== Method 2: SSH Tunnel ====
User needs to establish a SSH tunnel to expose the port 39000 from the master node to a local computer.

If you are using a Linux or Apple desktop or laptop, you can use the following command in Terminal to establish the ssh tunnel: <blockquote>'''ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu'''</blockquote>If you are using a Windows desktop or laptop, please download the '''[https://the.earth.li/~sgtatham/putty/latest/x86/plink.exe plink program]''' to use in place of the ssh client:<blockquote>'''plink -ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu'''</blockquote>
'''Note:''' Please put the plink.exe in the current directory where you have a command window open.

Unless you have SSH public key configured, you will be prompted for your MyID password and for Archpass Duo authentication. Once authentication is established, this session prompt will hang and you are ready to go to access the cryoSPARC User Interface.

Once you established the ssh tunnel by running the above command, you can open a browser (Chrome) on the local machine and navigate to<code><nowiki>http://localhost:39000</nowiki></code>. The cryoSPARC User Interface should be presented with the cryoSPARC login page.

=== Run cryoSPARC workflow jobs ===

==== Project space selection ====
A project in cryoSPARC is a high level container corresponding with a project directory on the file system, which stores all associated Jobs of a project. Each project in cryoSPARC is entirely contained within a file system directory. All the jobs and their respective intermediate and output data created within a project will be stored within the project directory.

* When you start a new project in cryoSPARC GUI, please select and use '''/scratch/gacrc-cryo''' as the cryoSPARC project space.
* This folder is owned by gacrc-cryo. Regular cryoSPARC users have access and read permissions which allow them to browse files in this folder and copy files from this folder to their own storage spaces on Sapelo2.

==== Run job on the master node ====
cryoSPARC will use the master node to run some types of workflow jobs, for example, "Import Movies", "Inspect Picks", and the interactive job "Select 2D Classes". When a job is created, if cryoSPARC will use the master node to run the job, you will be notified about this in cryoSPARC GUI.

==== Run job using "Lane Sapelo2 Default (cluster)" ====

* In cryoSPARC, queue a job to "'''Lane Sapelo2 Default (cluster)'''"; The job will be dispatched to the worker node via Slurm. Please note, gacrc-cryo, instead of your own Sapelo2 user account, is the user account owning and running the job. We highly recommend you to use this method to run cryoSPARC workflow jobs on Sapelo2.
* cryoSPARC will decide on how many CPU cores and how much memory it will use to run a workflow job, depend on the type of the job and your data size. Currently, we configured that from each worker node cryoSPARC can use up to '''20GB''' memory and '''4''' CPU cores.
* If the job needs to run on GPU devices, cryoSPARC will queue the job with a default number of GPU devices , for example 1. You can change this number by yourself in cryoSPARC GUI when you create the job. Please note that the maximum number of GPU devices installed on the worker node is '''4'''.

==Documentation (v4.0+)==

About cryoSPARC: https://guide.cryosparc.com/

Get Started with CryoSPARC: Introductory Tutorial: https://guide.cryosparc.com/processing-data/get-started-with-cryosparc-introductory-tutorial

A Tour of the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/a-tour-of-the-cryosparc-interface

Using the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/using-the-cryosparc-interface

Creating and Running Jobs: https://guide.cryosparc.com/application-guide-v4.0+/creating-and-running-jobs

Tutorial videos: https://guide.cryosparc.com/processing-data/tutorial-videos

==Installation==

*Version 4.3.1 master is installed on the master node (cryosparc.gacrc.uga.edu).
*Version 4.3.1 workers are installed on one worker GPU node (NVIDIA Tesla A100 GPU node).

==System==
64-bit Linux

CryoSPARC-Sapelo2

2026-07-10T14:46:29Z

Moses: /* User login */

[[Category:Sapelo2]][[Category:Software]][[Category:Engineering]]

== Category ==

Engineering

== Program On ==

Sapelo2

== Version ==

4.3.1

== Author / Distributor ==

See https://guide.cryosparc.com/

== Description ==

"CryoSPARC (Cryo-EM Single Particle Ab-Initio Reconstruction and Classification) is a state of the art HPC software solution for complete processing of single-particle cryo-electron microscopy (cryo-EM) data. CryoSPARC is useful for solving cryo-EM structures of membrane proteins, viruses, complexes, flexible molecules, small particles, phase plate data and negative stain data." For more information, please see https://guide.cryosparc.com/.

'''NOTE''': Users are required to be added into GACRC '''cryosparc''' group before they can run this software from Sapelo2. Please fill out the [https://uga.teamdynamix.com/TDClient/2060/Portal/Requests/ServiceDet?ID=25844 GACRC General Support form] to request. We will reach out to you after we received your request.

== Configurations ==
'''Master node VM:'''

* Host name: '''cryosparc.gacrc.uga.edu'''
* Intel Xeon processors (16 cores) and 64GB of RAM
* mongodb is installed and run on the master node
'''Worker nodes:'''
* One NVIDIA Tesla A100 node: Intel Xeon processors (64 cores), 1TB host RAM memory, 4 NVIDIA Tesla A100 GPU cards (80GiB device memory per card), and NVMe SSD 3570GB local drive.
* cryoSPARC recommends using SSD for caching particle data. /lscratch/gacrc-cryo is set up on the worker node for this purpose.
* The amount of space that cryoSPARC can use in /lscratch/gacrc-cryo is capped at 100GB.
'''cryoSPARC group:''' '''cryosparc'''

'''cryoSPARC service account:''' '''gacrc-cryo'''

* gacrc-cryo is the '''service account''' that will run cryoSPARC workflow jobs for all cryoSPARC users.
* Some tasks can only be handled by gacrc-cryo, like make a new lane of worker node(s), user management, and connect or update worker node(s) to master, etc..
* Regular CryoSPARC users can run cryosparcm on the master node to check cryoSPARC status, using cryosparcm status or cryosparcm checkdb.

'''cryoSPARC project space:''' '''/scratch/gacrc-cryo'''
#

== How to run cryoSPARC from Sapelo2 ==

=== User login ===

==== Method 2: SSH Tunnel ====
User needs to establish a SSH tunnel to expose the port 39000 from the master node to a local computer.

If you are using a Linux or Apple desktop or laptop, you can use the following command in Terminal to establish the ssh tunnel: <blockquote>'''ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu'''</blockquote>If you are using a Windows desktop or laptop, please download the '''[https://the.earth.li/~sgtatham/putty/latest/x86/plink.exe plink program]''' to use in place of the ssh client:<blockquote>'''plink -ssh -N -L 39000:10.2.0.60:39000 username@cryosparc.gacrc.uga.edu'''</blockquote>
'''Note:''' Please put the plink.exe in the current directory where you have a command window open.

Unless you have SSH public key configured, you will be prompted for your MyID password and for Archpass Duo authentication. Once authentication is established, this session prompt will hang and you are ready to go to access the cryoSPARC User Interface.

Once you established the ssh tunnel by running the above command, you can open a browser (Chrome) on the local machine and navigate to<code><nowiki>http://localhost:39000</nowiki></code>. The cryoSPARC User Interface should be presented with the cryoSPARC login page.

=== Run cryoSPARC workflow jobs ===

==== Project space selection ====
A project in cryoSPARC is a high level container corresponding with a project directory on the file system, which stores all associated Jobs of a project. Each project in cryoSPARC is entirely contained within a file system directory. All the jobs and their respective intermediate and output data created within a project will be stored within the project directory.

* When you start a new project in cryoSPARC GUI, please select and use '''/scratch/gacrc-cryo''' as the cryoSPARC project space.
* This folder is owned by gacrc-cryo. Regular cryoSPARC users have access and read permissions which allow them to browse files in this folder and copy files from this folder to their own storage spaces on Sapelo2.

==== Run job on the master node ====
cryoSPARC will use the master node to run some types of workflow jobs, for example, "Import Movies", "Inspect Picks", and the interactive job "Select 2D Classes". When a job is created, if cryoSPARC will use the master node to run the job, you will be notified about this in cryoSPARC GUI.

==== Run job using "Lane Sapelo2 Default (cluster)" ====

* In cryoSPARC, queue a job to "'''Lane Sapelo2 Default (cluster)'''"; The job will be dispatched to the worker node via Slurm. Please note, gacrc-cryo, instead of your own Sapelo2 user account, is the user account owning and running the job. We highly recommend you to use this method to run cryoSPARC workflow jobs on Sapelo2.
* cryoSPARC will decide on how many CPU cores and how much memory it will use to run a workflow job, depend on the type of the job and your data size. Currently, we configured that from each worker node cryoSPARC can use up to '''20GB''' memory and '''4''' CPU cores.
* If the job needs to run on GPU devices, cryoSPARC will queue the job with a default number of GPU devices , for example 1. You can change this number by yourself in cryoSPARC GUI when you create the job. Please note that the maximum number of GPU devices installed on the worker node is '''4'''.

==Documentation (v4.0+)==

About cryoSPARC: https://guide.cryosparc.com/

Get Started with CryoSPARC: Introductory Tutorial: https://guide.cryosparc.com/processing-data/get-started-with-cryosparc-introductory-tutorial

A Tour of the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/a-tour-of-the-cryosparc-interface

Using the CryoSPARC Interface: https://guide.cryosparc.com/application-guide-v4.0+/using-the-cryosparc-interface

Creating and Running Jobs: https://guide.cryosparc.com/application-guide-v4.0+/creating-and-running-jobs

Tutorial videos: https://guide.cryosparc.com/processing-data/tutorial-videos

==Installation==

*Version 4.3.1 master is installed on the master node (cryosparc.gacrc.uga.edu).
*Version 4.3.1 workers are installed on one worker GPU node (NVIDIA Tesla A100 GPU node).

==System==
64-bit Linux

Training

2026-05-04T12:52:57Z

Moses:

==GACRC Training==

The GACRC regularly hosts training sessions on a number of subjects relevant to the use of our computational and storage resources. Scheduled trainings will be announced through the GACRC mailing list.

'''NOTE: New users are required to attend a Sapelo2 cluster introductory training session and information about that will be sent once an account is requested.'''

==Regular Training Announcement==

In '''April 2026''', the GACRC is hosting 9 training sessions listed below. These training workshops will be offered remotely via Zoom Meeting. Detailed instructions for joining the Zoom meeting will be sent to your UGA email account before each training session you register for.

We will offer:

1. Linux training for Linux-inexperienced cluster new users (3 sessions)

2. Sapelo2 cluster new user training (3 sessions)

3. Sapelo2 Part II (1 session)

4. Job Parallelization with GNU Parallel and Slurm Arrays (1 session)

5. Installing Software Packages in Virtual Environments on Sapelo2 (1 session)

In '''May 2026''', the GACRC is hosting 9 training sessions listed below. These training workshops will be offered remotely via Zoom Meeting. Detailed instructions for joining the Zoom meeting will be sent to your UGA email account before each training session you register for.

We will offer:

1. Linux training for Linux-inexperienced cluster new users (3 sessions)

2. Sapelo2 cluster new user training (3 sessions)

==Event Schedule==

This section describes the training workshops that we offer, along with the sessions that are currently scheduled.

===Sapelo2 Cluster New User Training===

This mandatory training consists of an overview of the structure of Sapelo2 as well as hands-on practice submitting a job along with guidance and best practices when using the Sapelo2 cluster.

'''Prerequisites:'''

*Linux basics. A Linux-inexperienced user must complete a prerequisite Linux training for Linux-inexperienced cluster new users.

'''Workshop Training Goals:'''

*Understand the layout of Sapelo2

*Understand the Sapelo2 file systems

*Understand the Sapelo2 partitions

*Understand the Sapelo2 software environment

*Understand how to request computing resources and submit a computational batch job following the Sapelo2 cluster general workflow

*Understand how to initiate an interactive job

*Understand how to transfer files to and from the cluster

*Understand how to get support from GACRC support team when you have any issues on cluster

'''Scheduled Sessions:'''

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
! scope="col" |Title
! scope="col" |Date/Time
|-
|Using Sapelo2 Cluster at the GACRC
|May 8th, Friday, 2:00 PM - 4:00 PM
|-
|Using Sapelo2 Cluster at the GACRC
|May 14th, Thursday, 2:00 PM - 4:00 PM
|-
|Using Sapelo2 Cluster at the GACRC
|May 20th, Wednesday, 2:00 PM - 4:00 PM
|}

===Linux Training for Linux-inexperienced Cluster New Users===
The Sapelo2 High Performance Computing (HPC) cluster runs a headless Linux distribution as the operating system on each of its constituent nodes. The term headless refers to the fact that these nodes do not have a desktop graphical user interface (GUI) installed by default. Graphical desktop environments consume resources that analyses could otherwise use, so users employ a command-line interface (CLI) instead. To interact with these resources, users connect to a remote terminal via SSH and execute commands.

The Linux Training workshop provides hands-on practice of the fundamental Linux commands necessary to interact with HPC resources.

'''Prerequisite:'''

Please watch the introductory videos on Linux, basic Linux terms, and Linux Paths and Directories (total ~17 minutes) '''before attending the training workshop'''.

*[https://kaltura.uga.edu/media/t/1_81u2kfi2/176125031 Linux]
*[https://kaltura.uga.edu/media/t/1_ol51cuyn/176125031 basic Linux terms]
*[https://kaltura.uga.edu/media/t/1_wdyxhgdg/176125031 Linux Paths and Directories]

'''Training Goals:'''

1. Understand fundamental concepts of Linux working environment (filesystem hierarchy, path, PATH, etc.)

2. Know how to use Linux common commands (ls, cd, pwd, cat, more, nano, mkdir, rm, cp, mv, etc.)

3. Understand what is Linux bash shell and know how to make a simple Linux script and run it in Linux environment

'''Scheduled Sessions:'''

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
! scope="col" | Title
! scope="col" |Date/Time
|-
|Use Linux on Cluster
|May 6th, Wednesday, 1:00 PM - 3:00 PM
|-
|Use Linux on Cluster
|May 12th, Tuesday, 1:00 PM - 3:00 PM
|-
|Use Linux on Cluster
|May 18th, Monday, 1:00 PM - 3:00 PM
|}

===Using Sapelo2 Cluster at the GACRC, Part II ===
This workshop will cover high-performance computing on Sapelo2, including job scheduling, resource requests (CPU, memory, GPU), and techniques for optimizing job performance.

'''Prerequisites:'''
*Linux basics. A Linux-inexperienced user must complete a prerequisite Linux training for Linux-inexperienced cluster new users.
*Sapelo2 cluster new user training. Fundamental HPC and Sapelo2 knowledge is required for this advanced Sapelo2 workshop.

'''Training Goals:'''

1. Learn about high-performance computing framework

2. Why is my job pending? How can I get my job to start sooner? How to find available computing resources on Sapelo2?

3. How to request computing resources such as nodes, CPU cores, memory, GPU device, etc. to run serial, threaded, MPI, and GPU jobs on Sapelo2?

4. How can I make my job run more efficiently (through the correct use of software and hardware)?

5. A quick intro to MPI library and how to compile/run MPI jobs on Sapelo2

'''Scheduled Sessions:'''

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
! scope="col" |Title
! scope="col" |Date/Time
|-
|Using Sapelo2 Cluster at the GACRC, Part II
|April 17th, Friday, 1:00 - 3:00 PM
|}

===Installing Software Packages in Virtual Environments on Sapelo2 ===
This workshop will cover the basics of virtual environments as well as provide practical guidance and best practices for using virtual environments on the Sapelo2 cluster. Participants will learn the basics of creating and configuring virtual environments, how to install software packages in both a Conda virtual environment and a Python virtual environment, and manage dependencies in their environments.

'''Prerequisite:'''

Must already have strong understanding of the Linux environment and Sapelo2.

'''Training Goals:'''

1. Learn how to create a virtual environment on Sapelo2

2. Be able to install software packages into both Conda and Python virtual environments

3. Understand how to manage dependencies of their virtual environments

'''Scheduled Sessions:'''

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
! scope="col" |Title
! scope="col" |Date/Time
|-
|Installing Software Packages in Virtual Environments on Sapelo2
|April 23rd, Thursday, 2:00 - 3:00 PM
|}

===Job Parallelization with GNU Parallel and Slurm Arrays ===
Learn how to run multiple commands in parallel using GNU Parallel and Slurm Arrays. These tools greatly reduce the runtime of certain types of jobs by running multiple instances of the same command in parallel. The workshop focuses on problems that involve executing the same command on multiple different inputs. This workshop is intended for users comfortable writing job submission scripts and using a command line. Concurrent and parallel programming techniques are not covered in this workshop.

'''Prerequisite:'''

Must already have strong understanding of the Linux environment and Sapelo2.

'''Training Goals:'''

1. Understand which jobs benefit from GNU Parallel and Slurm Arrays

2. Use GNU Parallel and Slurm Arrays to parallelize jobs

3. Understand the differences and similarities between GNU Parallel and Slurm Arrays

'''Scheduled Sessions:'''

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
! scope="col" |Title
! scope="col" |Date/Time
|-
|Job Parallelization with GNU Parallel and Slurm Arrays
|April 30th, Thursday, 1:00 - 2:30 PM
|}



==How to Register==

The training workshops '''Using Sapelo2 Cluster at the GACRC''' and '''Use Linux on Cluster''' are '''ONLY''' offered to '''new users''' who need user accounts on the GACRC Sapelo2 cluster or current Sapelo2 users seeking a refresher. If you would like to use the cluster, please ask your group PI/UGA faculty member to send us an account creation request for you, using the [https://uga.teamdynamix.com/TDClient/Requests/ServiceDet?ID=25839 GACRC User Account Request Form].

If you would like to attend the '''Using Sapelo2 Cluster at the GACRC, Part II''', the '''Installing Software Packages in Virtual Environments on Sapelo2''', and/or the '''Job Parallelization with GNU Parallel and Slurm Arrays''' training workshops, please send us a request using the [https://uga.teamdynamix.com/TDClient/Requests/ServiceDet?ID=25852 GACRC Training Request Form]. In your request, please tell us which session(s) you would like to attend.



== Download==

This section provides the slides that we use for our current workshops and material used for several of our past training events and presentations.

====Sapelo2 Cluster Training====

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|[[Media:GACRC_Sapelo2_cluster_new_user_training_workshop_v10.8.pdf]]
|-
|}

====Teaching Cluster Training====

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
|[[Media:GACRC-Teaching-cluster-new-user-training-workshop-Spring2026.pdf]]
|-
|}

====Linux Training for New Cluster Users====

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
|[[Media:Linux_Training_For_New_Users_Of_Cluster_Suchi_04252019.pdf]]
|-
|}

====Installing Software Packages in Virtual Environments on Sapelo2====

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
|[[Media:GACRC_virtual_environments_training_v1.2.pdf]]
|}

====Job Parallelization with GNU Parallel and Slurm Arrays====

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
|[[Media:GNU_Parallel_and_SLURM_Arrays_v1.1.pdf]]
|}

====Python Basics====

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
|[[Media:Python_Language_Basics_I_v5.1.pdf]]
|-
|[[Media:Python_Language_Basics_II_v5.1.pdf]]
|-
|[[Media:Python_Basics_v6.1.pdf]]
|-
|}

====R Basics====

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
|[[Media:R Language Basics PowerPoint v2.0.1.pdf|Media:R_Language_Basics_PowerPoint_v2.0.pdf]]
|-
|[[Media:R_Language_Basics_Document_v2.0.pdf]]
|-
|[[Media:R_Language_Basics_part_2_Powerpoint_v1.0.pdf]]
|-
|[[Media:R_Language_Basics_part_2_Document_v1.0.pdf]]
|-
|}

====Perl Basics====

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
| [[Media:Perl_Language_Basics_I_Workshop_v1.pdf]]
|-
|}


====Topical Sessions====

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|
|-
|[[Media:AI_Resources_on_the_GACRC_Sapelo2_Cluster.pdf]]
|-
|[[Media:Using_Sapelo2_Cluster_at_the_GACRC_Part_II_Rocky8.pdf]]

|}

====Out-Reach/In-Class Talk====

{| class="wikitable unsortable" width="100%" border="1" cellspacing="0" cellpadding="2" align="center"
|-
! scope="col" |Dept./Center/Institute
! scope="col" |Type
! scope="col" |Workshop PDF
|-
|GEOG - Spring2026 || In-Class || [[Media:GACRC-Teaching-cluster-new-user-training-workshop-python-Spring2026.pdf]]
|-
|BCMB8330 - Spring2026 || In-Class || [[Media:GACRC-Teaching-cluster-new-user-training-workshop_bcmb8330_Spring2026.pdf]]
|-
|PHYS8601 - Spring2026 || In-Class || [[Media:GACRC_Teaching_cluster_new_user_training_workshop-phys8601-Spring2026.pdf]] ; [[Media:Gacrc_handout2026_phys8601.pdf]]
|-
|Anthropology Department || Out-Reach || [[Media:GACRC_overview_20251117_Anthropology.pdf]]
|-
|CSP seminar - Fall 2025|| Out-Reach || [[Media:GACRC_overview_20250819-CSP.pdf]]

|}

'''NOTE:''' The slides may become outdated and you should always check GACRC Wiki for up to date information.

Visual Studio Code SSH

2026-04-20T18:47:40Z

Moses: /* 1. Prepare a batch job submission script for VSCode tunnel session */

==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 ([[OnDemand|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 [https://code.visualstudio.com/download 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.

[[File:Vscode_activity_bar.png | frameless]]

----

====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 [https://code.visualstudio.com/docs/editor/intellisense#:~:text=IntelliSense%20is%20a%20general%20term,%2C%20and%20%22code%20hinting.%22 IntelliSense] for Python.

[[File:Vscode_extensions.png | 400px | frameless]]

----

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.

[[File:Vscode_ssh_extension.png | 600px | frameless]]

----

====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.

[[File:Vscode_installed.png |700x700px| frameless]]

----

==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.

[[File:Vscode_sshbutton.png | frameless]]

----

====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...".

[[File:Vscode_connection_options.png | 600px | frameless]]

----

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

[[File:Vscode_add_new_ssh_host.png | 600px | frameless]]
[[File:Vscode_connection.png | 600px | frameless]]

----

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

[[File:Vscode_sshconfig.png | 600px | frameless]]

----

====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.

[[File:Vscode_chooseconnection.png | 600px | frameless]]
[[File:Vscode_password.png | 600px | frameless]]
[[File:Vscode_duo.png | 600px | frameless]]

----

====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.

[[File:Vscode_explorer.png | 600px | frameless]]

----

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.

[[File:Vscode_opendir.png |700x700px| frameless]]

----

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.

[[File:Vscode_homedir.png |700x700px| frameless]]

----

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.

[[File:Vscode_add_dir.png |700x700px| frameless]]

----

====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.

[[File:Vscode_terminal.png |714x714px| frameless ]]

== 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 ====
<syntaxhighlight lang="shell">
interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel
</syntaxhighlight>
----

==== 3. Prepare Working Directory ====
<syntaxhighlight lang="shell">
cd /scratch/$USER/VSCode_tunnel/
</syntaxhighlight>
----

==== 4. Load VSCode Module ====
<syntaxhighlight lang="shell">
ml VSCode/1.88.1
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
code-tunnel tunnel user login --provider github
</syntaxhighlight>Follow the instructions in your local browser:

* Open <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code, for example, 15C1-6D7C
* Authorize access[[File:Vscode-tunnel-1.png|thumb|Open <nowiki>https://github.com/login/device</nowiki>|none|600x600px]][[File:Vscode-tunnel-2.png|none|thumb|600x600px|Enter the code]][[File:Vscode-tunnel-3.png|none|thumb|Authorize access|513x513px]][[File:Vscode-tunnel-4.png|none|thumb|600x600px|Authorization successful]]
----

==== 6. Start the Tunnel ====
<syntaxhighlight lang="shell">
code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.
[[File:Vscode-tunnel-5.png|none|thumb|1189x1189px|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 <nowiki>https://github.com/login/device</nowiki> , 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: <code>E1F9-D7E8</code>).
* 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

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

Example:

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

==== 8. Trust Workspace ====
VSCode is now connected through the tunnel (cloud relay).
[[File:Vscode-tunnel-6.png|none|thumb|910x910px|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 (<code>vscode-server-linux-x64.tar.gz</code>) and temporarily store it in <code>/tmp</code>.
* 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:
[[File:Vscode-tunnel-7.png|none|thumb|908x908px|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 (<code>sub.sh</code>) as shown below:<syntaxhighlight lang="shell">
#!/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

</syntaxhighlight>'''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:<syntaxhighlight lang="shell">
sbatch sub.sh
</syntaxhighlight>

==== 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 <code>cat</code>to 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 ====
<syntaxhighlight lang="shell">
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 ---
</syntaxhighlight>
=== 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>code-tunnel</code>
* <code>code-server</code>
* <code>node (server-main.js)</code>
* <code>extensionHost</code>
* <code>fileWatcher</code>
* <code>ptyHost</code>

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 [[OnDemand|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:<syntaxhighlight lang="shell">
ssh <node> "pgrep -u $USER -af 'code|vscode|node'"
</syntaxhighlight>To compare, run the same command on the login node where you started the interactive job or submitted the batch job:<syntaxhighlight>
pgrep -u $USER -af "code|vscode|node"
</syntaxhighlight>Example:<syntaxhighlight lang="shell">
zhuofei@ss-sub4 VSCode_tunnel$ ssh ra5-6 "pgrep -u $USER -af 'code|vscode|node'"
3064679 code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir /home/zhuofei/.code_tunnel --accept-server-license-terms
3064696 sh /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/bin/code-server --connection-token=j2x9Z0dD03TwZ5WpnxGpodje1UFflxwsjGy0uDjVIOA --accept-server-license-terms --start-server --enable-remote-auto-shutdown --socket-path=/tmp/code-6ca97adf-e1a0-4b74-a319-bd3dff74b07c
3064700 /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/node /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/server-main.js --connection-token=j2x9Z0dD03TwZ5WpnxGpodje1UFflxwsjGy0uDjVIOA --accept-server-license-terms --start-server --enable-remote-auto-shutdown --socket-path=/tmp/code-6ca97adf-e1a0-4b74-a319-bd3dff74b07c
3064724 /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/node /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/bootstrap-fork --type=fileWatcher
3064815 /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/node --dns-result-order=ipv4first /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/bootstrap-fork --type=extensionHost --transformURIs --useHostProxy=false
3064832 /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/node /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/bootstrap-fork --type=ptyHost --logsPath /home/zhuofei/.vscode-server/data/logs/20260420T110646
3064843 /bin/bash --init-file /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/vs/workbench/contrib/terminal/common/scripts/shellIntegration-bash.sh

zhuofei@ss-sub4 VSCode_tunnel$ pgrep -u $USER -af 'code|vscode|node'
# (no output)

</syntaxhighlight>

==== Observed Behavior ====
'''On compute node:'''

* VS Code Server process (<code>code-server</code>)
* Node runtime processes (shown as <code>node</code>)
* Extension host (<code>node ... --type=extensionHost</code>)
* File watcher (<code>node ... --type=fileWatcher</code>)
* Terminal backend (<code>node ... --type=ptyHost</code>)

'''On login node:'''

* No VSCode-related processes

----

==== Result ====

* VSCode backend processes run only on the compute node
* No VSCode services remain on the login node

----

==== Interpretation ====

* The VSCode workload is fully isolated to the compute node
* Login nodes remain clean and responsive
* This behavior aligns with HPC best practices

----

=== Best Practices ===

* Always run VSCode (server/tunnel) inside a Slurm interactive or batch job on a compute node.
* Never run VSCode directly on login nodes.
* Request appropriate CPU, memory, and GPU resources for your workload.
* Install only the extensions you need.
* Periodically remove unused extensions to reduce resource usage.
* Avoid leaving idle VSCode sessions running; terminate jobs when not in use.
* VS Code and its extensions are installed under ${HOME}/.vscode-server/, which counts toward your home directory quota.

=== Key Takeaway ===
VSCode is a multi-process system. It must be treated like a compute workload—not a simple SSH tool or text editor.

=== Final Note ===
This workflow is strongly recommended for:

* AI / LLM workloads
* GPU-based development
* Heavy interactive coding sessions

Visual Studio Code SSH

2026-04-20T18:46:17Z

Moses: /* 1. Prepare a batch job submission script for VSCode tunnel session */

==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 ([[OnDemand|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 [https://code.visualstudio.com/download 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.

[[File:Vscode_activity_bar.png | frameless]]

----

====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 [https://code.visualstudio.com/docs/editor/intellisense#:~:text=IntelliSense%20is%20a%20general%20term,%2C%20and%20%22code%20hinting.%22 IntelliSense] for Python.

[[File:Vscode_extensions.png | 400px | frameless]]

----

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.

[[File:Vscode_ssh_extension.png | 600px | frameless]]

----

====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.

[[File:Vscode_installed.png |700x700px| frameless]]

----

==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.

[[File:Vscode_sshbutton.png | frameless]]

----

====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...".

[[File:Vscode_connection_options.png | 600px | frameless]]

----

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

[[File:Vscode_add_new_ssh_host.png | 600px | frameless]]
[[File:Vscode_connection.png | 600px | frameless]]

----

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

[[File:Vscode_sshconfig.png | 600px | frameless]]

----

====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.

[[File:Vscode_chooseconnection.png | 600px | frameless]]
[[File:Vscode_password.png | 600px | frameless]]
[[File:Vscode_duo.png | 600px | frameless]]

----

====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.

[[File:Vscode_explorer.png | 600px | frameless]]

----

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.

[[File:Vscode_opendir.png |700x700px| frameless]]

----

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.

[[File:Vscode_homedir.png |700x700px| frameless]]

----

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.

[[File:Vscode_add_dir.png |700x700px| frameless]]

----

====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.

[[File:Vscode_terminal.png |714x714px| frameless ]]

== 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 ====
<syntaxhighlight lang="shell">
interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel
</syntaxhighlight>
----

==== 3. Prepare Working Directory ====
<syntaxhighlight lang="shell">
cd /scratch/$USER/VSCode_tunnel/
</syntaxhighlight>
----

==== 4. Load VSCode Module ====
<syntaxhighlight lang="shell">
ml VSCode/1.88.1
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
code-tunnel tunnel user login --provider github
</syntaxhighlight>Follow the instructions in your local browser:

* Open <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code, for example, 15C1-6D7C
* Authorize access[[File:Vscode-tunnel-1.png|thumb|Open <nowiki>https://github.com/login/device</nowiki>|none|600x600px]][[File:Vscode-tunnel-2.png|none|thumb|600x600px|Enter the code]][[File:Vscode-tunnel-3.png|none|thumb|Authorize access|513x513px]][[File:Vscode-tunnel-4.png|none|thumb|600x600px|Authorization successful]]
----

==== 6. Start the Tunnel ====
<syntaxhighlight lang="shell">
code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.
[[File:Vscode-tunnel-5.png|none|thumb|1189x1189px|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 <nowiki>https://github.com/login/device</nowiki> , 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: <code>E1F9-D7E8</code>).
* 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

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

Example:

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

==== 8. Trust Workspace ====
VSCode is now connected through the tunnel (cloud relay).
[[File:Vscode-tunnel-6.png|none|thumb|910x910px|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 (<code>vscode-server-linux-x64.tar.gz</code>) and temporarily store it in <code>/tmp</code>.
* 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:
[[File:Vscode-tunnel-7.png|none|thumb|908x908px|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 (<code>sub.sh</code>) as shown below:<syntaxhighlight lang="shell">
#!/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

</syntaxhighlight>'''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 there 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:<syntaxhighlight lang="shell">
sbatch sub.sh
</syntaxhighlight>

==== 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 <code>cat</code>to 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 ====
<syntaxhighlight lang="shell">
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 ---
</syntaxhighlight>
=== 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>code-tunnel</code>
* <code>code-server</code>
* <code>node (server-main.js)</code>
* <code>extensionHost</code>
* <code>fileWatcher</code>
* <code>ptyHost</code>

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 [[OnDemand|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:<syntaxhighlight lang="shell">
ssh <node> "pgrep -u $USER -af 'code|vscode|node'"
</syntaxhighlight>To compare, run the same command on the login node where you started the interactive job or submitted the batch job:<syntaxhighlight>
pgrep -u $USER -af "code|vscode|node"
</syntaxhighlight>Example:<syntaxhighlight lang="shell">
zhuofei@ss-sub4 VSCode_tunnel$ ssh ra5-6 "pgrep -u $USER -af 'code|vscode|node'"
3064679 code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir /home/zhuofei/.code_tunnel --accept-server-license-terms
3064696 sh /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/bin/code-server --connection-token=j2x9Z0dD03TwZ5WpnxGpodje1UFflxwsjGy0uDjVIOA --accept-server-license-terms --start-server --enable-remote-auto-shutdown --socket-path=/tmp/code-6ca97adf-e1a0-4b74-a319-bd3dff74b07c
3064700 /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/node /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/server-main.js --connection-token=j2x9Z0dD03TwZ5WpnxGpodje1UFflxwsjGy0uDjVIOA --accept-server-license-terms --start-server --enable-remote-auto-shutdown --socket-path=/tmp/code-6ca97adf-e1a0-4b74-a319-bd3dff74b07c
3064724 /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/node /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/bootstrap-fork --type=fileWatcher
3064815 /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/node --dns-result-order=ipv4first /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/bootstrap-fork --type=extensionHost --transformURIs --useHostProxy=false
3064832 /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/node /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/bootstrap-fork --type=ptyHost --logsPath /home/zhuofei/.vscode-server/data/logs/20260420T110646
3064843 /bin/bash --init-file /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/vs/workbench/contrib/terminal/common/scripts/shellIntegration-bash.sh

zhuofei@ss-sub4 VSCode_tunnel$ pgrep -u $USER -af 'code|vscode|node'
# (no output)

</syntaxhighlight>

==== Observed Behavior ====
'''On compute node:'''

* VS Code Server process (<code>code-server</code>)
* Node runtime processes (shown as <code>node</code>)
* Extension host (<code>node ... --type=extensionHost</code>)
* File watcher (<code>node ... --type=fileWatcher</code>)
* Terminal backend (<code>node ... --type=ptyHost</code>)

'''On login node:'''

* No VSCode-related processes

----

==== Result ====

* VSCode backend processes run only on the compute node
* No VSCode services remain on the login node

----

==== Interpretation ====

* The VSCode workload is fully isolated to the compute node
* Login nodes remain clean and responsive
* This behavior aligns with HPC best practices

----

=== Best Practices ===

* Always run VSCode (server/tunnel) inside a Slurm interactive or batch job on a compute node.
* Never run VSCode directly on login nodes.
* Request appropriate CPU, memory, and GPU resources for your workload.
* Install only the extensions you need.
* Periodically remove unused extensions to reduce resource usage.
* Avoid leaving idle VSCode sessions running; terminate jobs when not in use.
* VS Code and its extensions are installed under ${HOME}/.vscode-server/, which counts toward your home directory quota.

=== Key Takeaway ===
VSCode is a multi-process system. It must be treated like a compute workload—not a simple SSH tool or text editor.

=== Final Note ===
This workflow is strongly recommended for:

* AI / LLM workloads
* GPU-based development
* Heavy interactive coding sessions

Visual Studio Code SSH

2026-04-20T18:44:43Z

Moses:

==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 ([[OnDemand|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 [https://code.visualstudio.com/download 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.

[[File:Vscode_activity_bar.png | frameless]]

----

====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 [https://code.visualstudio.com/docs/editor/intellisense#:~:text=IntelliSense%20is%20a%20general%20term,%2C%20and%20%22code%20hinting.%22 IntelliSense] for Python.

[[File:Vscode_extensions.png | 400px | frameless]]

----

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.

[[File:Vscode_ssh_extension.png | 600px | frameless]]

----

====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.

[[File:Vscode_installed.png |700x700px| frameless]]

----

==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.

[[File:Vscode_sshbutton.png | frameless]]

----

====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...".

[[File:Vscode_connection_options.png | 600px | frameless]]

----

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

[[File:Vscode_add_new_ssh_host.png | 600px | frameless]]
[[File:Vscode_connection.png | 600px | frameless]]

----

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

[[File:Vscode_sshconfig.png | 600px | frameless]]

----

====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.

[[File:Vscode_chooseconnection.png | 600px | frameless]]
[[File:Vscode_password.png | 600px | frameless]]
[[File:Vscode_duo.png | 600px | frameless]]

----

====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.

[[File:Vscode_explorer.png | 600px | frameless]]

----

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.

[[File:Vscode_opendir.png |700x700px| frameless]]

----

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.

[[File:Vscode_homedir.png |700x700px| frameless]]

----

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.

[[File:Vscode_add_dir.png |700x700px| frameless]]

----

====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.

[[File:Vscode_terminal.png |714x714px| frameless ]]

== 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 ====
<syntaxhighlight lang="shell">
interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel
</syntaxhighlight>
----

==== 3. Prepare Working Directory ====
<syntaxhighlight lang="shell">
cd /scratch/$USER/VSCode_tunnel/
</syntaxhighlight>
----

==== 4. Load VSCode Module ====
<syntaxhighlight lang="shell">
ml VSCode/1.88.1
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
code-tunnel tunnel user login --provider github
</syntaxhighlight>Follow the instructions in your local browser:

* Open <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code, for example, 15C1-6D7C
* Authorize access[[File:Vscode-tunnel-1.png|thumb|Open <nowiki>https://github.com/login/device</nowiki>|none|600x600px]][[File:Vscode-tunnel-2.png|none|thumb|600x600px|Enter the code]][[File:Vscode-tunnel-3.png|none|thumb|Authorize access|513x513px]][[File:Vscode-tunnel-4.png|none|thumb|600x600px|Authorization successful]]
----

==== 6. Start the Tunnel ====
<syntaxhighlight lang="shell">
code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.
[[File:Vscode-tunnel-5.png|none|thumb|1189x1189px|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 <nowiki>https://github.com/login/device</nowiki> , 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: <code>E1F9-D7E8</code>).
* 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

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

Example:

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

==== 8. Trust Workspace ====
VSCode is now connected through the tunnel (cloud relay).
[[File:Vscode-tunnel-6.png|none|thumb|910x910px|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 (<code>vscode-server-linux-x64.tar.gz</code>) and temporarily store it in <code>/tmp</code>.
* 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:
[[File:Vscode-tunnel-7.png|none|thumb|908x908px|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 (<code>sub.sh</code>) as shown below:<syntaxhighlight lang="shell">
#!/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

</syntaxhighlight>'''Note:''' You can load additional compatible central modules in your batch job submission script. Any modules loaded there 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:<syntaxhighlight lang="shell">
sbatch sub.sh
</syntaxhighlight>

==== 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 <code>cat</code>to 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 ====
<syntaxhighlight lang="shell">
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 ---
</syntaxhighlight>
=== 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>code-tunnel</code>
* <code>code-server</code>
* <code>node (server-main.js)</code>
* <code>extensionHost</code>
* <code>fileWatcher</code>
* <code>ptyHost</code>

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 [[OnDemand|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:<syntaxhighlight lang="shell">
ssh <node> "pgrep -u $USER -af 'code|vscode|node'"
</syntaxhighlight>To compare, run the same command on the login node where you started the interactive job or submitted the batch job:<syntaxhighlight>
pgrep -u $USER -af "code|vscode|node"
</syntaxhighlight>Example:<syntaxhighlight lang="shell">
zhuofei@ss-sub4 VSCode_tunnel$ ssh ra5-6 "pgrep -u $USER -af 'code|vscode|node'"
3064679 code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir /home/zhuofei/.code_tunnel --accept-server-license-terms
3064696 sh /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/bin/code-server --connection-token=j2x9Z0dD03TwZ5WpnxGpodje1UFflxwsjGy0uDjVIOA --accept-server-license-terms --start-server --enable-remote-auto-shutdown --socket-path=/tmp/code-6ca97adf-e1a0-4b74-a319-bd3dff74b07c
3064700 /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/node /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/server-main.js --connection-token=j2x9Z0dD03TwZ5WpnxGpodje1UFflxwsjGy0uDjVIOA --accept-server-license-terms --start-server --enable-remote-auto-shutdown --socket-path=/tmp/code-6ca97adf-e1a0-4b74-a319-bd3dff74b07c
3064724 /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/node /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/bootstrap-fork --type=fileWatcher
3064815 /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/node --dns-result-order=ipv4first /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/bootstrap-fork --type=extensionHost --transformURIs --useHostProxy=false
3064832 /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/node /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/bootstrap-fork --type=ptyHost --logsPath /home/zhuofei/.vscode-server/data/logs/20260420T110646
3064843 /bin/bash --init-file /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/vs/workbench/contrib/terminal/common/scripts/shellIntegration-bash.sh

zhuofei@ss-sub4 VSCode_tunnel$ pgrep -u $USER -af 'code|vscode|node'
# (no output)

</syntaxhighlight>

==== Observed Behavior ====
'''On compute node:'''

* VS Code Server process (<code>code-server</code>)
* Node runtime processes (shown as <code>node</code>)
* Extension host (<code>node ... --type=extensionHost</code>)
* File watcher (<code>node ... --type=fileWatcher</code>)
* Terminal backend (<code>node ... --type=ptyHost</code>)

'''On login node:'''

* No VSCode-related processes

----

==== Result ====

* VSCode backend processes run only on the compute node
* No VSCode services remain on the login node

----

==== Interpretation ====

* The VSCode workload is fully isolated to the compute node
* Login nodes remain clean and responsive
* This behavior aligns with HPC best practices

----

=== Best Practices ===

* Always run VSCode (server/tunnel) inside a Slurm interactive or batch job on a compute node.
* Never run VSCode directly on login nodes.
* Request appropriate CPU, memory, and GPU resources for your workload.
* Install only the extensions you need.
* Periodically remove unused extensions to reduce resource usage.
* Avoid leaving idle VSCode sessions running; terminate jobs when not in use.
* VS Code and its extensions are installed under ${HOME}/.vscode-server/, which counts toward your home directory quota.

=== Key Takeaway ===
VSCode is a multi-process system. It must be treated like a compute workload—not a simple SSH tool or text editor.

=== Final Note ===
This workflow is strongly recommended for:

* AI / LLM workloads
* GPU-based development
* Heavy interactive coding sessions

Visual Studio Code SSH

2026-04-20T18:34:59Z

Moses: /* Interpretation */

==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 ([[OnDemand|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 [https://code.visualstudio.com/download 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.

[[File:Vscode_activity_bar.png | frameless]]

----

====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 [https://code.visualstudio.com/docs/editor/intellisense#:~:text=IntelliSense%20is%20a%20general%20term,%2C%20and%20%22code%20hinting.%22 IntelliSense] for Python.

[[File:Vscode_extensions.png | 400px | frameless]]

----

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.

[[File:Vscode_ssh_extension.png | 600px | frameless]]

----

====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.

[[File:Vscode_installed.png |700x700px| frameless]]

----

==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.

[[File:Vscode_sshbutton.png | frameless]]

----

====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...".

[[File:Vscode_connection_options.png | 600px | frameless]]

----

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

[[File:Vscode_add_new_ssh_host.png | 600px | frameless]]
[[File:Vscode_connection.png | 600px | frameless]]

----

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

[[File:Vscode_sshconfig.png | 600px | frameless]]

----

====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.

[[File:Vscode_chooseconnection.png | 600px | frameless]]
[[File:Vscode_password.png | 600px | frameless]]
[[File:Vscode_duo.png | 600px | frameless]]

----

====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.

[[File:Vscode_explorer.png | 600px | frameless]]

----

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.

[[File:Vscode_opendir.png |700x700px| frameless]]

----

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.

[[File:Vscode_homedir.png |700x700px| frameless]]

----

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.

[[File:Vscode_add_dir.png |700x700px| frameless]]

----

====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.

[[File:Vscode_terminal.png |714x714px| frameless ]]

== 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 ====
<syntaxhighlight lang="shell">
interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2
</syntaxhighlight>
----

==== 2. Clean Previous VSCode State (Recommended. Note that all VSCode extensions you downloaded will be removed) ====
<syntaxhighlight lang="shell">
rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel
</syntaxhighlight>
----

==== 3. Prepare Working Directory ====
<syntaxhighlight lang="shell">
cd /scratch/$USER/VSCode_tunnel/
</syntaxhighlight>
----

==== 4. Load VSCode Module ====
<syntaxhighlight lang="shell">
ml VSCode/1.88.1
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
code-tunnel tunnel user login --provider github
</syntaxhighlight>Follow the instructions in your local browser:

* Open <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code, for example, 15C1-6D7C
* Authorize access[[File:Vscode-tunnel-1.png|thumb|Open <nowiki>https://github.com/login/device</nowiki>|none|600x600px]][[File:Vscode-tunnel-2.png|none|thumb|600x600px|Enter the code]][[File:Vscode-tunnel-3.png|none|thumb|Authorize access|513x513px]][[File:Vscode-tunnel-4.png|none|thumb|600x600px|Authorization successful]]
----

==== 6. Start the Tunnel ====
<syntaxhighlight lang="shell">
code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.
[[File:Vscode-tunnel-5.png|none|thumb|1189x1189px|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 <nowiki>https://github.com/login/device</nowiki> , 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: <code>E1F9-D7E8</code>).
* 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

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

Example:

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

==== 8. Trust Workspace ====
VSCode is now connected through the tunnel (cloud relay).
[[File:Vscode-tunnel-6.png|none|thumb|910x910px|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 (<code>vscode-server-linux-x64.tar.gz</code>) and temporarily store it in <code>/tmp</code>.
* 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:
[[File:Vscode-tunnel-7.png|none|thumb|908x908px|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 (<code>sub.sh</code>) as shown below:<syntaxhighlight lang="shell">
#!/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

</syntaxhighlight>'''Note:''' You can load additional compatible central modules in your batch job submission script. Any modules loaded there 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:<syntaxhighlight lang="shell">
sbatch sub.sh
</syntaxhighlight>

==== 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 <code>cat</code>to 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 ====
<syntaxhighlight lang="shell">
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 ---
</syntaxhighlight>
=== 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>code-tunnel</code>
* <code>code-server</code>
* <code>node (server-main.js)</code>
* <code>extensionHost</code>
* <code>fileWatcher</code>
* <code>ptyHost</code>

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 [[OnDemand|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:<syntaxhighlight lang="shell">
ssh <node> "pgrep -u $USER -af 'code|vscode|node'"
</syntaxhighlight>To compare, run the same command on the login node where you started the interactive job or submitted the batch job:<syntaxhighlight>
pgrep -u $USER -af "code|vscode|node"
</syntaxhighlight>Example:<syntaxhighlight lang="shell">
zhuofei@ss-sub4 VSCode_tunnel$ ssh ra5-6 "pgrep -u $USER -af 'code|vscode|node'"
3064679 code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir /home/zhuofei/.code_tunnel --accept-server-license-terms
3064696 sh /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/bin/code-server --connection-token=j2x9Z0dD03TwZ5WpnxGpodje1UFflxwsjGy0uDjVIOA --accept-server-license-terms --start-server --enable-remote-auto-shutdown --socket-path=/tmp/code-6ca97adf-e1a0-4b74-a319-bd3dff74b07c
3064700 /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/node /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/server-main.js --connection-token=j2x9Z0dD03TwZ5WpnxGpodje1UFflxwsjGy0uDjVIOA --accept-server-license-terms --start-server --enable-remote-auto-shutdown --socket-path=/tmp/code-6ca97adf-e1a0-4b74-a319-bd3dff74b07c
3064724 /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/node /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/bootstrap-fork --type=fileWatcher
3064815 /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/node --dns-result-order=ipv4first /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/bootstrap-fork --type=extensionHost --transformURIs --useHostProxy=false
3064832 /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/node /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/bootstrap-fork --type=ptyHost --logsPath /home/zhuofei/.vscode-server/data/logs/20260420T110646
3064843 /bin/bash --init-file /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/vs/workbench/contrib/terminal/common/scripts/shellIntegration-bash.sh

zhuofei@ss-sub4 VSCode_tunnel$ pgrep -u $USER -af 'code|vscode|node'
# (no output)

</syntaxhighlight>

==== Observed Behavior ====
'''On compute node:'''

* VS Code Server process (<code>code-server</code>)
* Node runtime processes (shown as <code>node</code>)
* Extension host (<code>node ... --type=extensionHost</code>)
* File watcher (<code>node ... --type=fileWatcher</code>)
* Terminal backend (<code>node ... --type=ptyHost</code>)

'''On login node:'''

* No VSCode-related processes

----

==== Result ====

* VSCode backend processes run only on the compute node
* No VSCode services remain on the login node

----

==== Interpretation ====

* The VSCode workload is fully isolated to the compute node
* Login nodes remain clean and responsive
* This behavior aligns with HPC best practices

----

=== Best Practices ===

* Always run VSCode (server/tunnel) inside a Slurm interactive or batch job on a compute node.
* Never run VSCode directly on login nodes.
* Request appropriate CPU, memory, and GPU resources for your workload.
* Install only the extensions you need.
* Periodically remove unused extensions to reduce resource usage.
* Avoid leaving idle VSCode sessions running; terminate jobs when not in use.
* VS Code and its extensions are installed under ${HOME}/.vscode-server/, which counts toward your home directory quota.

=== Key Takeaway ===
VSCode is a multi-process system. It must be treated like a compute workload—not a simple SSH tool or text editor.

=== Final Note ===
This workflow is strongly recommended for:

* AI / LLM workloads
* GPU-based development
* Heavy interactive coding sessions

Visual Studio Code SSH

2026-04-20T18:22:40Z

Moses:

==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 ([[OnDemand|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 [https://code.visualstudio.com/download 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.

[[File:Vscode_activity_bar.png | frameless]]

----

====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 [https://code.visualstudio.com/docs/editor/intellisense#:~:text=IntelliSense%20is%20a%20general%20term,%2C%20and%20%22code%20hinting.%22 IntelliSense] for Python.

[[File:Vscode_extensions.png | 400px | frameless]]

----

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.

[[File:Vscode_ssh_extension.png | 600px | frameless]]

----

====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.

[[File:Vscode_installed.png |700x700px| frameless]]

----

==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.

[[File:Vscode_sshbutton.png | frameless]]

----

====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...".

[[File:Vscode_connection_options.png | 600px | frameless]]

----

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

[[File:Vscode_add_new_ssh_host.png | 600px | frameless]]
[[File:Vscode_connection.png | 600px | frameless]]

----

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

[[File:Vscode_sshconfig.png | 600px | frameless]]

----

====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.

[[File:Vscode_chooseconnection.png | 600px | frameless]]
[[File:Vscode_password.png | 600px | frameless]]
[[File:Vscode_duo.png | 600px | frameless]]

----

====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.

[[File:Vscode_explorer.png | 600px | frameless]]

----

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.

[[File:Vscode_opendir.png |700x700px| frameless]]

----

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.

[[File:Vscode_homedir.png |700x700px| frameless]]

----

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.

[[File:Vscode_add_dir.png |700x700px| frameless]]

----

====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.

[[File:Vscode_terminal.png |714x714px| frameless ]]

== 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 ====
<syntaxhighlight lang="shell">
interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2
</syntaxhighlight>
----

==== 2. Clean Previous VSCode State (Recommended. Note that all VSCode extensions you downloaded will be removed) ====
<syntaxhighlight lang="shell">
rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel
</syntaxhighlight>
----

==== 3. Prepare Working Directory ====
<syntaxhighlight lang="shell">
cd /scratch/$USER/VSCode_tunnel/
</syntaxhighlight>
----

==== 4. Load VSCode Module ====
<syntaxhighlight lang="shell">
ml VSCode/1.88.1
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
code-tunnel tunnel user login --provider github
</syntaxhighlight>Follow the instructions in your local browser:

* Open <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code, for example, 15C1-6D7C
* Authorize access[[File:Vscode-tunnel-1.png|thumb|Open <nowiki>https://github.com/login/device</nowiki>|none|600x600px]][[File:Vscode-tunnel-2.png|none|thumb|600x600px|Enter the code]][[File:Vscode-tunnel-3.png|none|thumb|Authorize access|513x513px]][[File:Vscode-tunnel-4.png|none|thumb|600x600px|Authorization successful]]
----

==== 6. Start the Tunnel ====
<syntaxhighlight lang="shell">
code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.
[[File:Vscode-tunnel-5.png|none|thumb|1189x1189px|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 <nowiki>https://github.com/login/device</nowiki> , 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: <code>E1F9-D7E8</code>).
* 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

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

Example:

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

==== 8. Trust Workspace ====
VSCode is now connected through the tunnel (cloud relay).
[[File:Vscode-tunnel-6.png|none|thumb|910x910px|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 (<code>vscode-server-linux-x64.tar.gz</code>) and temporarily store it in <code>/tmp</code>.
* 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:
[[File:Vscode-tunnel-7.png|none|thumb|908x908px|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 (<code>sub.sh</code>) as shown below:<syntaxhighlight lang="shell">
#!/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

</syntaxhighlight>'''Note:''' You can load additional compatible central modules in your batch job submission script. Any modules loaded there 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:<syntaxhighlight lang="shell">
sbatch sub.sh
</syntaxhighlight>

==== 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 <code>cat</code>to 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 ====
<syntaxhighlight lang="shell">
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 ---
</syntaxhighlight>
=== 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>code-tunnel</code>
* <code>code-server</code>
* <code>node (server-main.js)</code>
* <code>extensionHost</code>
* <code>fileWatcher</code>
* <code>ptyHost</code>

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 [[OnDemand|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:<syntaxhighlight lang="shell">
ssh <node> "pgrep -u $USER -af 'code|vscode|node'"
</syntaxhighlight>To compare, run the same command on the login node where you started the interactive job or submitted the batch job:<syntaxhighlight>
pgrep -u $USER -af "code|vscode|node"
</syntaxhighlight>Example:<syntaxhighlight lang="shell">
zhuofei@ss-sub4 VSCode_tunnel$ ssh ra5-6 "pgrep -u $USER -af 'code|vscode|node'"
3064679 code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir /home/zhuofei/.code_tunnel --accept-server-license-terms
3064696 sh /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/bin/code-server --connection-token=j2x9Z0dD03TwZ5WpnxGpodje1UFflxwsjGy0uDjVIOA --accept-server-license-terms --start-server --enable-remote-auto-shutdown --socket-path=/tmp/code-6ca97adf-e1a0-4b74-a319-bd3dff74b07c
3064700 /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/node /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/server-main.js --connection-token=j2x9Z0dD03TwZ5WpnxGpodje1UFflxwsjGy0uDjVIOA --accept-server-license-terms --start-server --enable-remote-auto-shutdown --socket-path=/tmp/code-6ca97adf-e1a0-4b74-a319-bd3dff74b07c
3064724 /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/node /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/bootstrap-fork --type=fileWatcher
3064815 /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/node --dns-result-order=ipv4first /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/bootstrap-fork --type=extensionHost --transformURIs --useHostProxy=false
3064832 /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/node /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/bootstrap-fork --type=ptyHost --logsPath /home/zhuofei/.vscode-server/data/logs/20260420T110646
3064843 /bin/bash --init-file /home/zhuofei/.code_tunnel/servers/Stable-560a9dba96f961efea7b1612916f89e5d5d4d679/server/out/vs/workbench/contrib/terminal/common/scripts/shellIntegration-bash.sh

zhuofei@ss-sub4 VSCode_tunnel$ pgrep -u $USER -af 'code|vscode|node'
# (no output)

</syntaxhighlight>

==== Observed Behavior ====
'''On compute node:'''

* VS Code Server process (<code>code-server</code>)
* Node runtime processes (shown as <code>node</code>)
* Extension host (<code>node ... --type=extensionHost</code>)
* File watcher (<code>node ... --type=fileWatcher</code>)
* Terminal backend (<code>node ... --type=ptyHost</code>)

'''On login node:'''

* No VSCode-related processes

----

==== Result ====

* VSCode backend processes run only on the compute node
* No VSCode services remain on the login node

----

==== Interpretation ====

* The VSCode workload is fully isolated to the compute node
* Login nodes remain clean and responsive
* This behavior aligns with HPC best practices

----

=== Best Practices ===
* Always run inside a Slurm allocation
* Never run VSCode directly on login nodes
* Install only necessary extensions
* Clean unused extensions periodically

=== Key Takeaway ===
VSCode is a distributed, multi-process system. It must be treated like a compute workload—not a simple SSH tool or text editor.

=== Final Note ===
This workflow is strongly recommended for:

* AI / LLM workloads
* GPU-based development
* Heavy interactive coding sessions

Visual Studio Code SSH

2026-04-20T16:25:32Z

Moses: /* Compute Node and Login Node Behavior (Observed) (To be completed ZH.20260417 4:53PM) */

==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 ([[OnDemand|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 [https://code.visualstudio.com/download 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.

[[File:Vscode_activity_bar.png | frameless]]

----

====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 [https://code.visualstudio.com/docs/editor/intellisense#:~:text=IntelliSense%20is%20a%20general%20term,%2C%20and%20%22code%20hinting.%22 IntelliSense] for Python.

[[File:Vscode_extensions.png | 400px | frameless]]

----

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.

[[File:Vscode_ssh_extension.png | 600px | frameless]]

----

====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.

[[File:Vscode_installed.png |700x700px| frameless]]

----

==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.

[[File:Vscode_sshbutton.png | frameless]]

----

====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...".

[[File:Vscode_connection_options.png | 600px | frameless]]

----

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

[[File:Vscode_add_new_ssh_host.png | 600px | frameless]]
[[File:Vscode_connection.png | 600px | frameless]]

----

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

[[File:Vscode_sshconfig.png | 600px | frameless]]

----

====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.

[[File:Vscode_chooseconnection.png | 600px | frameless]]
[[File:Vscode_password.png | 600px | frameless]]
[[File:Vscode_duo.png | 600px | frameless]]

----

====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.

[[File:Vscode_explorer.png | 600px | frameless]]

----

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.

[[File:Vscode_opendir.png |700x700px| frameless]]

----

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.

[[File:Vscode_homedir.png |700x700px| frameless]]

----

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.

[[File:Vscode_add_dir.png |700x700px| frameless]]

----

====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.

[[File:Vscode_terminal.png |714x714px| frameless ]]

== 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 ====
<syntaxhighlight lang="shell">
interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2
</syntaxhighlight>
----

==== 2. Clean Previous VSCode State (Recommended. Note that all VSCode extensions you downloaded will be removed) ====
<syntaxhighlight lang="shell">
rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel
</syntaxhighlight>
----

==== 3. Prepare Working Directory ====
<syntaxhighlight lang="shell">
cd /scratch/$USER/VSCode_tunnel/
</syntaxhighlight>
----

==== 4. Load VSCode Module ====
<syntaxhighlight lang="shell">
ml VSCode/1.88.1
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
code-tunnel tunnel user login --provider github
</syntaxhighlight>Follow the instructions in your local browser:

* Open <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code, for example, 15C1-6D7C
* Authorize access[[File:Vscode-tunnel-1.png|thumb|Open <nowiki>https://github.com/login/device</nowiki>|none|600x600px]][[File:Vscode-tunnel-2.png|none|thumb|600x600px|Enter the code]][[File:Vscode-tunnel-3.png|none|thumb|Authorize access|513x513px]][[File:Vscode-tunnel-4.png|none|thumb|600x600px|Authorization successful]]
----

==== 6. Start the Tunnel ====
<syntaxhighlight lang="shell">
code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.
[[File:Vscode-tunnel-5.png|none|thumb|1189x1189px|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 <nowiki>https://github.com/login/device</nowiki> , 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: <code>E1F9-D7E8</code>).
* 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

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

Example:

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

==== 8. Trust Workspace ====
VSCode is now connected through the tunnel (cloud relay).
[[File:Vscode-tunnel-6.png|none|thumb|910x910px|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 (<code>vscode-server-linux-x64.tar.gz</code>) and temporarily store it in <code>/tmp</code>.
* 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:
[[File:Vscode-tunnel-7.png|none|thumb|908x908px|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 (<code>sub.sh</code>) as shown below:<syntaxhighlight lang="shell">
#!/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

</syntaxhighlight>'''Note:''' You can load additional compatible central modules in your batch job submission script. Any modules loaded there 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:<syntaxhighlight lang="shell">
sbatch sub.sh
</syntaxhighlight>

==== 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 <code>cat</code>to 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 ====
<syntaxhighlight lang="shell">
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 ---
</syntaxhighlight>
=== 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>code-tunnel</code>
* <code>code-server</code>
* <code>node (server-main.js)</code>
* <code>extensionHost</code>
* <code>fileWatcher</code>
* <code>ptyHost</code>

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 [[OnDemand|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 relevant VSCode processes with:<syntaxhighlight lang="shell">
ssh <node> "pgrep -u $USER -af 'code|vscode|node|python'"
</syntaxhighlight>Example:<syntaxhighlight lang="shell">
ssh ra5-6 "pgrep -u $USER -af 'code|vscode|node|python'"
</syntaxhighlight>For comparing, you can also run the same pgrep on the login node where you started the interactive job or submitted compute node:

Processes include:

* VSCode server
* Node.js services
* Extension hosts
* Terminal backend

Resource usage example:

* CPU: low but persistent
* Memory: non-trivial
* GPU: allocated but may be idle
* Processes: <code>code-tunnel</code>, multiple <code>node</code>

----

Across all login nodes (<code>ss-sub1</code>–<code>ss-sub4</code>):

==== Result ====
* No VSCode backend processes present
* Only Slurm launcher processes visible
* No persistent services running

==== Interpretation ====
VSCode workload is fully isolated to compute node

Login nodes remain clean and responsive
----

=== Best Practices ===
* Always run inside a Slurm allocation
* Never run VSCode directly on login nodes
* Install only necessary extensions
* Clean unused extensions periodically

=== Key Takeaway ===
VSCode is a distributed, multi-process system. It must be treated like a compute workload—not a simple SSH tool or text editor.

=== Final Note ===
This workflow is strongly recommended for:

* AI / LLM workloads
* GPU-based development
* Heavy interactive coding sessions

Visual Studio Code SSH

2026-04-20T16:04:02Z

Moses:

==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 ([[OnDemand|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 [https://code.visualstudio.com/download 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.

[[File:Vscode_activity_bar.png | frameless]]

----

====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 [https://code.visualstudio.com/docs/editor/intellisense#:~:text=IntelliSense%20is%20a%20general%20term,%2C%20and%20%22code%20hinting.%22 IntelliSense] for Python.

[[File:Vscode_extensions.png | 400px | frameless]]

----

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.

[[File:Vscode_ssh_extension.png | 600px | frameless]]

----

====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.

[[File:Vscode_installed.png |700x700px| frameless]]

----

==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.

[[File:Vscode_sshbutton.png | frameless]]

----

====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...".

[[File:Vscode_connection_options.png | 600px | frameless]]

----

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

[[File:Vscode_add_new_ssh_host.png | 600px | frameless]]
[[File:Vscode_connection.png | 600px | frameless]]

----

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

[[File:Vscode_sshconfig.png | 600px | frameless]]

----

====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.

[[File:Vscode_chooseconnection.png | 600px | frameless]]
[[File:Vscode_password.png | 600px | frameless]]
[[File:Vscode_duo.png | 600px | frameless]]

----

====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.

[[File:Vscode_explorer.png | 600px | frameless]]

----

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.

[[File:Vscode_opendir.png |700x700px| frameless]]

----

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.

[[File:Vscode_homedir.png |700x700px| frameless]]

----

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.

[[File:Vscode_add_dir.png |700x700px| frameless]]

----

====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.

[[File:Vscode_terminal.png |714x714px| frameless ]]

== 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 ====
<syntaxhighlight lang="shell">
interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2
</syntaxhighlight>
----

==== 2. Clean Previous VSCode State (Recommended. Note that all VSCode extensions you downloaded will be removed) ====
<syntaxhighlight lang="shell">
rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel
</syntaxhighlight>
----

==== 3. Prepare Working Directory ====
<syntaxhighlight lang="shell">
cd /scratch/$USER/VSCode_tunnel/
</syntaxhighlight>
----

==== 4. Load VSCode Module ====
<syntaxhighlight lang="shell">
ml VSCode/1.88.1
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
code-tunnel tunnel user login --provider github
</syntaxhighlight>Follow the instructions in your local browser:

* Open <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code, for example, 15C1-6D7C
* Authorize access[[File:Vscode-tunnel-1.png|thumb|Open <nowiki>https://github.com/login/device</nowiki>|none|600x600px]][[File:Vscode-tunnel-2.png|none|thumb|600x600px|Enter the code]][[File:Vscode-tunnel-3.png|none|thumb|Authorize access|513x513px]][[File:Vscode-tunnel-4.png|none|thumb|600x600px|Authorization successful]]
----

==== 6. Start the Tunnel ====
<syntaxhighlight lang="shell">
code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.
[[File:Vscode-tunnel-5.png|none|thumb|1189x1189px|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 <nowiki>https://github.com/login/device</nowiki> , 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: <code>E1F9-D7E8</code>).
* 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

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

Example:

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

==== 8. Trust Workspace ====
VSCode is now connected through the tunnel (cloud relay).
[[File:Vscode-tunnel-6.png|none|thumb|910x910px|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 (<code>vscode-server-linux-x64.tar.gz</code>) and temporarily store it in <code>/tmp</code>.
* 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:
[[File:Vscode-tunnel-7.png|none|thumb|908x908px|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 (<code>sub.sh</code>) as shown below:<syntaxhighlight lang="shell">
#!/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

</syntaxhighlight>'''Note:''' You can load additional compatible central modules in your batch job submission script. Any modules loaded there 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:<syntaxhighlight lang="shell">
sbatch sub.sh
</syntaxhighlight>

==== 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 <code>cat</code>to 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 ====
<syntaxhighlight lang="shell">
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 ---
</syntaxhighlight>
=== 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>code-tunnel</code>
* <code>code-server</code>
* <code>node (server-main.js)</code>
* <code>extensionHost</code>
* <code>fileWatcher</code>
* <code>ptyHost</code>

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 [[OnDemand|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) (To be completed ZH.20260417 4:53PM) ===
Example on compute node:

Processes include:

* VSCode server
* Node.js services
* Extension hosts
* Terminal backend

Resource usage example:

* CPU: low but persistent
* Memory: non-trivial
* GPU: allocated but may be idle
* Processes: <code>code-tunnel</code>, multiple <code>node</code>

----

Across all login nodes (<code>ss-sub1</code>–<code>ss-sub4</code>):

==== Result ====
* No VSCode backend processes present
* Only Slurm launcher processes visible
* No persistent services running

==== Interpretation ====
VSCode workload is fully isolated to compute node

Login nodes remain clean and responsive
----

=== Extension Behavior ===

==== Before Python Extension ====
User extensions:

* Minimal (e.g., Copilot)

Server extensions:

* Built-in only

----

==== After Python Extension Installation ====
New extension appears:

==== Key Points ====
* User extensions → <code>~/.vscode-server/extensions/</code>
* Built-in extensions → server directory
* Server directory remains unchanged

----

==== Storage ====
* Extensions stored in home directory
* Can grow over time

==== Performance ====
Installing extensions (e.g., Python) adds:

* Language servers
* Background indexing
* Additional CPU/memory usage

----

=== Best Practices ===
* Always run inside a Slurm allocation
* Never run VSCode directly on login nodes
* Install only necessary extensions
* Clean unused extensions periodically

=== Key Takeaway ===
VSCode is a distributed, multi-process system.

It must be treated like a compute workload—not a simple SSH tool.

=== Final Note ===
This workflow is strongly recommended for:

* AI / LLM workloads
* GPU-based development
* Heavy interactive coding sessions

Visual Studio Code SSH

2026-04-20T16:00:29Z

Moses: /* Compute Node and Login Node Behavior (Observed) (To be completed ZH.20260417 4:53PM) */

==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 ([[OnDemand|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 [https://code.visualstudio.com/download 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.

[[File:Vscode_activity_bar.png | frameless]]

----

====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 [https://code.visualstudio.com/docs/editor/intellisense#:~:text=IntelliSense%20is%20a%20general%20term,%2C%20and%20%22code%20hinting.%22 IntelliSense] for Python.

[[File:Vscode_extensions.png | 400px | frameless]]

----

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.

[[File:Vscode_ssh_extension.png | 600px | frameless]]

----

====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.

[[File:Vscode_installed.png |700x700px| frameless]]

----

==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.

[[File:Vscode_sshbutton.png | frameless]]

----

====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...".

[[File:Vscode_connection_options.png | 600px | frameless]]

----

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

[[File:Vscode_add_new_ssh_host.png | 600px | frameless]]
[[File:Vscode_connection.png | 600px | frameless]]

----

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

[[File:Vscode_sshconfig.png | 600px | frameless]]

----

====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.

[[File:Vscode_chooseconnection.png | 600px | frameless]]
[[File:Vscode_password.png | 600px | frameless]]
[[File:Vscode_duo.png | 600px | frameless]]

----

====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.

[[File:Vscode_explorer.png | 600px | frameless]]

----

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.

[[File:Vscode_opendir.png |700x700px| frameless]]

----

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.

[[File:Vscode_homedir.png |700x700px| frameless]]

----

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.

[[File:Vscode_add_dir.png |700x700px| frameless]]

----

====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.

[[File:Vscode_terminal.png |714x714px| frameless ]]

== 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 ====
<syntaxhighlight lang="shell">
interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2
</syntaxhighlight>
----

==== 2. Clean Previous VSCode State (Recommended. Note that all VSCode extensions you downloaded will be removed) ====
<syntaxhighlight lang="shell">
rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel
</syntaxhighlight>
----

==== 3. Prepare Working Directory ====
<syntaxhighlight lang="shell">
cd /scratch/$USER/VSCode_tunnel/
</syntaxhighlight>
----

==== 4. Load VSCode Module ====
<syntaxhighlight lang="shell">
ml VSCode/1.88.1
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
code-tunnel tunnel user login --provider github
</syntaxhighlight>Follow the instructions in your local browser:

* Open <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code, for example, 15C1-6D7C
* Authorize access[[File:Vscode-tunnel-1.png|thumb|Open <nowiki>https://github.com/login/device</nowiki>|none|600x600px]][[File:Vscode-tunnel-2.png|none|thumb|600x600px|Enter the code]][[File:Vscode-tunnel-3.png|none|thumb|Authorize access|513x513px]][[File:Vscode-tunnel-4.png|none|thumb|600x600px|Authorization successful]]
----

==== 6. Start the Tunnel ====
<syntaxhighlight lang="shell">
code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.
[[File:Vscode-tunnel-5.png|none|thumb|1189x1189px|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 <nowiki>https://github.com/login/device</nowiki> , 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 was not fully completed.
* Complete authorization using the latest code shown in the log (for example: <code>E1F9-D7E8</code>).
* Once authorization is successful, the VSCode link will appear in the log and can be used directly.

The VSCode tunnel is now active. Open the provided link in your browser to connect <nowiki>https://vscode.dev/tunnel/</nowiki><tunnel-name>/<full>/<path>/<to>/<your>/<working folder where you started tunnel>

For example:

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

==== 8. Trust Workspace ====
VSCode is now connected through the tunnel (cloud relay).
[[File:Vscode-tunnel-6.png|none|thumb|910x910px|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 (<code>vscode-server-linux-x64.tar.gz</code>) and temporarily store it in <code>/tmp</code>.
* 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:
[[File:Vscode-tunnel-7.png|none|thumb|908x908px|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 (<code>sub.sh</code>) as shown below:<syntaxhighlight lang="shell">
#!/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

</syntaxhighlight>'''Note:''' You can load additional compatible central modules in your batch job submission script. Any modules loaded there 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:<syntaxhighlight lang="shell">
sbatch sub.sh
</syntaxhighlight>

==== 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 <code>cat</code>to 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 ====
<syntaxhighlight lang="shell">
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 ---
</syntaxhighlight>
=== 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>code-tunnel</code>
* <code>code-server</code>
* <code>node (server-main.js)</code>
* <code>extensionHost</code>
* <code>fileWatcher</code>
* <code>ptyHost</code>

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 [[OnDemand|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) (To be completed ZH.20260417 4:53PM) ===
Example on compute node:

Processes include:

* VSCode server
* Node.js services
* Extension hosts
* Terminal backend

Resource usage example:

* CPU: low but persistent
* Memory: non-trivial
* GPU: allocated but may be idle
* Processes: <code>code-tunnel</code>, multiple <code>node</code>

----

Across all login nodes (<code>ss-sub1</code>–<code>ss-sub4</code>):

==== Result ====
* No VSCode backend processes present
* Only Slurm launcher processes visible
* No persistent services running

==== Interpretation ====
VSCode workload is fully isolated to compute node

Login nodes remain clean and responsive
----

=== Extension Behavior ===

==== Before Python Extension ====
User extensions:

* Minimal (e.g., Copilot)

Server extensions:

* Built-in only

----

==== After Python Extension Installation ====
New extension appears:

==== Key Points ====
* User extensions → <code>~/.vscode-server/extensions/</code>
* Built-in extensions → server directory
* Server directory remains unchanged

----

==== Storage ====
* Extensions stored in home directory
* Can grow over time

==== Performance ====
Installing extensions (e.g., Python) adds:

* Language servers
* Background indexing
* Additional CPU/memory usage

----

=== Best Practices ===
* Always run inside a Slurm allocation
* Never run VSCode directly on login nodes
* Install only necessary extensions
* Clean unused extensions periodically

=== Key Takeaway ===
VSCode is a distributed, multi-process system.

It must be treated like a compute workload—not a simple SSH tool.

=== Final Note ===
This workflow is strongly recommended for:

* AI / LLM workloads
* GPU-based development
* Heavy interactive coding sessions

Visual Studio Code SSH

2026-04-20T15:41:57Z

Moses: /* 5. Example of steps */

==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 ([[OnDemand|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 [https://code.visualstudio.com/download 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.

[[File:Vscode_activity_bar.png | frameless]]

----

====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 [https://code.visualstudio.com/docs/editor/intellisense#:~:text=IntelliSense%20is%20a%20general%20term,%2C%20and%20%22code%20hinting.%22 IntelliSense] for Python.

[[File:Vscode_extensions.png | 400px | frameless]]

----

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.

[[File:Vscode_ssh_extension.png | 600px | frameless]]

----

====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.

[[File:Vscode_installed.png |700x700px| frameless]]

----

==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.

[[File:Vscode_sshbutton.png | frameless]]

----

====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...".

[[File:Vscode_connection_options.png | 600px | frameless]]

----

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

[[File:Vscode_add_new_ssh_host.png | 600px | frameless]]
[[File:Vscode_connection.png | 600px | frameless]]

----

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

[[File:Vscode_sshconfig.png | 600px | frameless]]

----

====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.

[[File:Vscode_chooseconnection.png | 600px | frameless]]
[[File:Vscode_password.png | 600px | frameless]]
[[File:Vscode_duo.png | 600px | frameless]]

----

====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.

[[File:Vscode_explorer.png | 600px | frameless]]

----

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.

[[File:Vscode_opendir.png |700x700px| frameless]]

----

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.

[[File:Vscode_homedir.png |700x700px| frameless]]

----

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.

[[File:Vscode_add_dir.png |700x700px| frameless]]

----

====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.

[[File:Vscode_terminal.png |714x714px| frameless ]]

== 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 ====
<syntaxhighlight lang="shell">
interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2
</syntaxhighlight>
----

==== 2. Clean Previous VSCode State (Recommended. Note that all VSCode extensions you downloaded will be removed) ====
<syntaxhighlight lang="shell">
rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel
</syntaxhighlight>
----

==== 3. Prepare Working Directory ====
<syntaxhighlight lang="shell">
cd /scratch/$USER/VSCode_tunnel/
</syntaxhighlight>
----

==== 4. Load VSCode Module ====
<syntaxhighlight lang="shell">
ml VSCode/1.88.1
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
code-tunnel tunnel user login --provider github
</syntaxhighlight>Follow the instructions in your local browser:

* Open <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code, for example, 15C1-6D7C
* Authorize access[[File:Vscode-tunnel-1.png|thumb|Open <nowiki>https://github.com/login/device</nowiki>|none|600x600px]][[File:Vscode-tunnel-2.png|none|thumb|600x600px|Enter the code]][[File:Vscode-tunnel-3.png|none|thumb|Authorize access|513x513px]][[File:Vscode-tunnel-4.png|none|thumb|600x600px|Authorization successful]]
----

==== 6. Start the Tunnel ====
<syntaxhighlight lang="shell">
code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.
[[File:Vscode-tunnel-5.png|none|thumb|1189x1189px|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 <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code generated at this step, for example, E1F9-D7E8
* Authorize access

The VSCode tunnel is now active. Open the provided link in your browser to connect <nowiki>https://vscode.dev/tunnel/</nowiki><tunnel-name>/<full>/<path>/<to>/<your>/<working folder where you started tunnel>

For example:

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

==== 8. Trust Workspace ====
VSCode is now connected through the tunnel (cloud relay).
[[File:Vscode-tunnel-6.png|none|thumb|910x910px|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 (<code>vscode-server-linux-x64.tar.gz</code>) and temporarily store it in <code>/tmp</code>.
* 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:
[[File:Vscode-tunnel-7.png|none|thumb|908x908px|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 (<code>sub.sh</code>) as shown below:<syntaxhighlight lang="shell">
#!/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

</syntaxhighlight>'''Note:''' You can load additional compatible central modules in your batch job submission script. Any modules loaded there 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:<syntaxhighlight lang="shell">
sbatch sub.sh
</syntaxhighlight>

==== 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 <code>cat</code>to 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 ====
<syntaxhighlight lang="shell">
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 ---
</syntaxhighlight>
=== 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>code-tunnel</code>
* <code>code-server</code>
* <code>node (server-main.js)</code>
* <code>extensionHost</code>
* <code>fileWatcher</code>
* <code>ptyHost</code>

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 [[OnDemand|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) (To be completed ZH.20260417 4:53PM) ===
Example on compute node:

Processes include:

* VSCode server
* Node.js services
* Extension hosts
* Terminal backend

Resource usage example:

* CPU: low but persistent
* Memory: non-trivial
* GPU: allocated but may be idle
* Processes: <code>code-tunnel</code>, multiple <code>node</code>

----

Across all login nodes (<code>ss-sub1</code>–<code>ss-sub4</code>):

==== Result ====
* No VSCode backend processes present
* Only Slurm launcher processes visible
* No persistent services running

==== Interpretation ====
VSCode workload is fully isolated to compute node

Login nodes remain clean and responsive
----

=== Extension Behavior ===

==== Before Python Extension ====
User extensions:

* Minimal (e.g., Copilot)

Server extensions:

* Built-in only

----

==== After Python Extension Installation ====
New extension appears:

==== Key Points ====
* User extensions → <code>~/.vscode-server/extensions/</code>
* Built-in extensions → server directory
* Server directory remains unchanged

----

==== Storage ====
* Extensions stored in home directory
* Can grow over time

==== Performance ====
Installing extensions (e.g., Python) adds:

* Language servers
* Background indexing
* Additional CPU/memory usage

----

=== Best Practices ===
* Always run inside a Slurm allocation
* Never run VSCode directly on login nodes
* Install only necessary extensions
* Clean unused extensions periodically

=== Key Takeaway ===
VSCode is a distributed, multi-process system.

It must be treated like a compute workload—not a simple SSH tool.

=== Final Note ===
This workflow is strongly recommended for:

* AI / LLM workloads
* GPU-based development
* Heavy interactive coding sessions

Visual Studio Code SSH

2026-04-20T15:26:57Z

Moses: /* 5. Example of steps */

==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 ([[OnDemand|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 [https://code.visualstudio.com/download 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.

[[File:Vscode_activity_bar.png | frameless]]

----

====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 [https://code.visualstudio.com/docs/editor/intellisense#:~:text=IntelliSense%20is%20a%20general%20term,%2C%20and%20%22code%20hinting.%22 IntelliSense] for Python.

[[File:Vscode_extensions.png | 400px | frameless]]

----

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.

[[File:Vscode_ssh_extension.png | 600px | frameless]]

----

====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.

[[File:Vscode_installed.png |700x700px| frameless]]

----

==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.

[[File:Vscode_sshbutton.png | frameless]]

----

====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...".

[[File:Vscode_connection_options.png | 600px | frameless]]

----

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

[[File:Vscode_add_new_ssh_host.png | 600px | frameless]]
[[File:Vscode_connection.png | 600px | frameless]]

----

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

[[File:Vscode_sshconfig.png | 600px | frameless]]

----

====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.

[[File:Vscode_chooseconnection.png | 600px | frameless]]
[[File:Vscode_password.png | 600px | frameless]]
[[File:Vscode_duo.png | 600px | frameless]]

----

====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.

[[File:Vscode_explorer.png | 600px | frameless]]

----

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.

[[File:Vscode_opendir.png |700x700px| frameless]]

----

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.

[[File:Vscode_homedir.png |700x700px| frameless]]

----

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.

[[File:Vscode_add_dir.png |700x700px| frameless]]

----

====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.

[[File:Vscode_terminal.png |714x714px| frameless ]]

== 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 ====
<syntaxhighlight lang="shell">
interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2
</syntaxhighlight>
----

==== 2. Clean Previous VSCode State (Recommended. Note that all VSCode extensions you downloaded will be removed) ====
<syntaxhighlight lang="shell">
rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel
</syntaxhighlight>
----

==== 3. Prepare Working Directory ====
<syntaxhighlight lang="shell">
cd /scratch/$USER/VSCode_tunnel/
</syntaxhighlight>
----

==== 4. Load VSCode Module ====
<syntaxhighlight lang="shell">
ml VSCode/1.88.1
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
code-tunnel tunnel user login --provider github
</syntaxhighlight>Follow the instructions in your local browser:

* Open <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code, for example, 15C1-6D7C
* Authorize access[[File:Vscode-tunnel-1.png|thumb|Open <nowiki>https://github.com/login/device</nowiki>|none|600x600px]][[File:Vscode-tunnel-2.png|none|thumb|600x600px|Enter the code]][[File:Vscode-tunnel-3.png|none|thumb|Authorize access|513x513px]][[File:Vscode-tunnel-4.png|none|thumb|600x600px|Authorization successful]]
----

==== 6. Start the Tunnel ====
<syntaxhighlight lang="shell">
code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.
[[File:Vscode-tunnel-5.png|none|thumb|1189x1189px|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 <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code generated at this step, for example, E1F9-D7E8
* Authorize access

The VSCode tunnel is now active. Open the provided link in your browser to connect <nowiki>https://vscode.dev/tunnel/</nowiki><tunnel-name>/<full>/<path>/<to>/<your>/<working folder where you started tunnel>

For example:

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

==== 8. Trust Workspace ====
VSCode is now connected through the tunnel (cloud relay).
[[File:Vscode-tunnel-6.png|none|thumb|910x910px|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 (<code>vscode-server-linux-x64.tar.gz</code>) and temporarily store it in <code>/tmp</code>.
* 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:
[[File:Vscode-tunnel-7.png|none|thumb|908x908px|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 (<code>sub.sh</code>) as shown below:<syntaxhighlight lang="shell">
#!/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

</syntaxhighlight>'''Note:''' You can load additional compatible central modules in your batch job submission script. Any modules loaded there 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:<syntaxhighlight lang="shell">
sbatch sub.sh
</syntaxhighlight>

==== 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 <code>cat</code>to 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 of steps ====
<syntaxhighlight lang="shell">
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
</syntaxhighlight><syntaxhighlight lang="shell">
# --- IMPORTANT WORKFLOW ---
# --- 1. Run `cat log` ---
# --- 2. Follow the instructions shown (usually in browser) ---
# --- 3. Return and run `cat log` again ---
# --- 4. Repeat until tunnel is fully ready ---

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

# --- VSCode tunnel requests GitHub device authentication ---
# --- ACTION: Open browser and complete authorization ---
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 prompted again, complete authorization in browser before continuing ---
# --- If already authorized, proceed to next step ---

*
* 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 on your local machine ---
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 (normal behavior) ---
# --- No action needed if 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 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 (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 browser ---
</syntaxhighlight>

=== 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>code-tunnel</code>
* <code>code-server</code>
* <code>node (server-main.js)</code>
* <code>extensionHost</code>
* <code>fileWatcher</code>
* <code>ptyHost</code>

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 [[OnDemand|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) (To be completed ZH.20260417 4:53PM) ===
Example on compute node:

Processes include:

* VSCode server
* Node.js services
* Extension hosts
* Terminal backend

Resource usage example:

* CPU: low but persistent
* Memory: non-trivial
* GPU: allocated but may be idle
* Processes: <code>code-tunnel</code>, multiple <code>node</code>

----

Across all login nodes (<code>ss-sub1</code>–<code>ss-sub4</code>):

==== Result ====
* No VSCode backend processes present
* Only Slurm launcher processes visible
* No persistent services running

==== Interpretation ====
VSCode workload is fully isolated to compute node

Login nodes remain clean and responsive
----

=== Extension Behavior ===

==== Before Python Extension ====
User extensions:

* Minimal (e.g., Copilot)

Server extensions:

* Built-in only

----

==== After Python Extension Installation ====
New extension appears:

==== Key Points ====
* User extensions → <code>~/.vscode-server/extensions/</code>
* Built-in extensions → server directory
* Server directory remains unchanged

----

==== Storage ====
* Extensions stored in home directory
* Can grow over time

==== Performance ====
Installing extensions (e.g., Python) adds:

* Language servers
* Background indexing
* Additional CPU/memory usage

----

=== Best Practices ===
* Always run inside a Slurm allocation
* Never run VSCode directly on login nodes
* Install only necessary extensions
* Clean unused extensions periodically

=== Key Takeaway ===
VSCode is a distributed, multi-process system.

It must be treated like a compute workload—not a simple SSH tool.

=== Final Note ===
This workflow is strongly recommended for:

* AI / LLM workloads
* GPU-based development
* Heavy interactive coding sessions

Visual Studio Code SSH

2026-04-20T14:11:40Z

Moses:

==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 ([[OnDemand|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 [https://code.visualstudio.com/download 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.

[[File:Vscode_activity_bar.png | frameless]]

----

====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 [https://code.visualstudio.com/docs/editor/intellisense#:~:text=IntelliSense%20is%20a%20general%20term,%2C%20and%20%22code%20hinting.%22 IntelliSense] for Python.

[[File:Vscode_extensions.png | 400px | frameless]]

----

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.

[[File:Vscode_ssh_extension.png | 600px | frameless]]

----

====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.

[[File:Vscode_installed.png |700x700px| frameless]]

----

==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.

[[File:Vscode_sshbutton.png | frameless]]

----

====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...".

[[File:Vscode_connection_options.png | 600px | frameless]]

----

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

[[File:Vscode_add_new_ssh_host.png | 600px | frameless]]
[[File:Vscode_connection.png | 600px | frameless]]

----

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

[[File:Vscode_sshconfig.png | 600px | frameless]]

----

====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.

[[File:Vscode_chooseconnection.png | 600px | frameless]]
[[File:Vscode_password.png | 600px | frameless]]
[[File:Vscode_duo.png | 600px | frameless]]

----

====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.

[[File:Vscode_explorer.png | 600px | frameless]]

----

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.

[[File:Vscode_opendir.png |700x700px| frameless]]

----

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.

[[File:Vscode_homedir.png |700x700px| frameless]]

----

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.

[[File:Vscode_add_dir.png |700x700px| frameless]]

----

====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.

[[File:Vscode_terminal.png |714x714px| frameless ]]

== 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 ====
<syntaxhighlight lang="shell">
interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2
</syntaxhighlight>
----

==== 2. Clean Previous VSCode State (Recommended. Note that all VSCode extensions you downloaded will be removed) ====
<syntaxhighlight lang="shell">
rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel
</syntaxhighlight>
----

==== 3. Prepare Working Directory ====
<syntaxhighlight lang="shell">
cd /scratch/$USER/VSCode_tunnel/
</syntaxhighlight>
----

==== 4. Load VSCode Module ====
<syntaxhighlight lang="shell">
ml VSCode/1.88.1
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
code-tunnel tunnel user login --provider github
</syntaxhighlight>Follow the instructions in your local browser:

* Open <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code, for example, 15C1-6D7C
* Authorize access[[File:Vscode-tunnel-1.png|thumb|Open <nowiki>https://github.com/login/device</nowiki>|none|600x600px]][[File:Vscode-tunnel-2.png|none|thumb|600x600px|Enter the code]][[File:Vscode-tunnel-3.png|none|thumb|Authorize access|513x513px]][[File:Vscode-tunnel-4.png|none|thumb|600x600px|Authorization successful]]
----

==== 6. Start the Tunnel ====
<syntaxhighlight lang="shell">
code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.
[[File:Vscode-tunnel-5.png|none|thumb|1189x1189px|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 <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code generated at this step, for example, E1F9-D7E8
* Authorize access

The VSCode tunnel is now active. Open the provided link in your browser to connect <nowiki>https://vscode.dev/tunnel/</nowiki><tunnel-name>/<full>/<path>/<to>/<your>/<working folder where you started tunnel>

For example:

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

==== 8. Trust Workspace ====
VSCode is now connected through the tunnel (cloud relay).
[[File:Vscode-tunnel-6.png|none|thumb|910x910px|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 (<code>vscode-server-linux-x64.tar.gz</code>) and temporarily store it in <code>/tmp</code>.
* 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:
[[File:Vscode-tunnel-7.png|none|thumb|908x908px|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 (<code>sub.sh</code>) as shown below:<syntaxhighlight lang="shell">
#!/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

</syntaxhighlight>'''Note:''' You can load additional compatible central modules in your batch job submission script. Any modules loaded there 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:<syntaxhighlight lang="shell">
sbatch sub.sh
</syntaxhighlight>

==== 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 <code>cat</code>to 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 of steps ====
<syntaxhighlight lang="shell">
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 44572045

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

zhuofei@ss-sub1 VSCode_tunnel$ ls
log.44588780.out sub.sh
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file first time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- VSCode tunnel is requesting GitHub device authentication ---
# --- User must open the URL and enter the code to authorize ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file second time
cat log.44572045.out
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62
*
* 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).
*
[2026-04-20 09:50:11] info Using GitHub for authentication, run `code tunnel user login --provider <provider>` option to change this.
To grant access to the server, please log into https://github.com/login/device and use code 2DDE-E787
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file third time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication prompt may still appear until completed ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

# --- VS Code Server initialization message ---
*
* 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 is ready and provides a browser access link ---
Open this link in your browser https://vscode.dev/tunnel/vscode-tunnel-0416/scratch/zhuofei/VSCode_tunnel
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file fourth time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication message may still be shown in log ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

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

# --- Browser access link (use this on local machine) ---
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-17 16:13:13] info [tunnels::connections::relay_tunnel_host] Opened new client on channel 2

# --- Internal SSH handshake between tunnel components ---
[2026-04-17 16:13:13] info [russh::server] wrote id
[2026-04-17 16:13:13] info [russh::server] read other id

# --- Tunnel session is now active ---
[2026-04-17 16:13:13] info [russh::server] session is running

# --- VS Code checks for existing server instance ---
[2026-04-17 16:13:15] info [rpc.0] Checking /home/zhuofei/.code_tunnel/servers/.../log.txt and pid.txt for a running server...

# --- No running server found, starting a new one ---
[2026-04-17 16:13:15] info [rpc.0] Starting server...

# --- VS Code Server successfully started ---
[2026-04-17 16:13:15] info [rpc.0] Server started

# --- Job script finished, tunnel continues running in background ---
zhuofei@ss-sub4 VSCode_tunnel$
</syntaxhighlight>

=== 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>code-tunnel</code>
* <code>code-server</code>
* <code>node (server-main.js)</code>
* <code>extensionHost</code>
* <code>fileWatcher</code>
* <code>ptyHost</code>

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 [[OnDemand|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) (To be completed ZH.20260417 4:53PM) ===
Example on compute node:

Processes include:

* VSCode server
* Node.js services
* Extension hosts
* Terminal backend

Resource usage example:

* CPU: low but persistent
* Memory: non-trivial
* GPU: allocated but may be idle
* Processes: <code>code-tunnel</code>, multiple <code>node</code>

----

Across all login nodes (<code>ss-sub1</code>–<code>ss-sub4</code>):

==== Result ====
* No VSCode backend processes present
* Only Slurm launcher processes visible
* No persistent services running

==== Interpretation ====
VSCode workload is fully isolated to compute node

Login nodes remain clean and responsive
----

=== Extension Behavior ===

==== Before Python Extension ====
User extensions:

* Minimal (e.g., Copilot)

Server extensions:

* Built-in only

----

==== After Python Extension Installation ====
New extension appears:

==== Key Points ====
* User extensions → <code>~/.vscode-server/extensions/</code>
* Built-in extensions → server directory
* Server directory remains unchanged

----

==== Storage ====
* Extensions stored in home directory
* Can grow over time

==== Performance ====
Installing extensions (e.g., Python) adds:

* Language servers
* Background indexing
* Additional CPU/memory usage

----

=== Best Practices ===
* Always run inside a Slurm allocation
* Never run VSCode directly on login nodes
* Install only necessary extensions
* Clean unused extensions periodically

=== Key Takeaway ===
VSCode is a distributed, multi-process system.

It must be treated like a compute workload—not a simple SSH tool.

=== Final Note ===
This workflow is strongly recommended for:

* AI / LLM workloads
* GPU-based development
* Heavy interactive coding sessions

Visual Studio Code SSH

2026-04-20T14:02:52Z

Moses: /* 3. How to complete Steps 5–7 from the interactive workflow described above. */

==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 ([[OnDemand|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 [https://code.visualstudio.com/download 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.

[[File:Vscode_activity_bar.png | frameless]]

----

====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 [https://code.visualstudio.com/docs/editor/intellisense#:~:text=IntelliSense%20is%20a%20general%20term,%2C%20and%20%22code%20hinting.%22 IntelliSense] for Python.

[[File:Vscode_extensions.png | 400px | frameless]]

----

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.

[[File:Vscode_ssh_extension.png | 600px | frameless]]

----

====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.

[[File:Vscode_installed.png |700x700px| frameless]]

----

==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.

[[File:Vscode_sshbutton.png | frameless]]

----

====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...".

[[File:Vscode_connection_options.png | 600px | frameless]]

----

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

[[File:Vscode_add_new_ssh_host.png | 600px | frameless]]
[[File:Vscode_connection.png | 600px | frameless]]

----

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

[[File:Vscode_sshconfig.png | 600px | frameless]]

----

====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.

[[File:Vscode_chooseconnection.png | 600px | frameless]]
[[File:Vscode_password.png | 600px | frameless]]
[[File:Vscode_duo.png | 600px | frameless]]

----

====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.

[[File:Vscode_explorer.png | 600px | frameless]]

----

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.

[[File:Vscode_opendir.png |700x700px| frameless]]

----

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.

[[File:Vscode_homedir.png |700x700px| frameless]]

----

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.

[[File:Vscode_add_dir.png |700x700px| frameless]]

----

====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.

[[File:Vscode_terminal.png |714x714px| frameless ]]

== 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 ====
<syntaxhighlight lang="shell">
interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2
</syntaxhighlight>
----

==== 2. Clean Previous VSCode State (Recommended. Note that all VSCode extensions you downloaded will be removed) ====
<syntaxhighlight lang="shell">
rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel
</syntaxhighlight>
----

==== 3. Prepare Working Directory ====
<syntaxhighlight lang="shell">
cd /scratch/$USER/VSCode_tunnel/
</syntaxhighlight>
----

==== 4. Load VSCode Module ====
<syntaxhighlight lang="shell">
ml VSCode/1.88.1
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
code-tunnel tunnel user login --provider github
</syntaxhighlight>Follow the instructions in your local browser:

* Open <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code, for example, 15C1-6D7C
* Authorize access[[File:Vscode-tunnel-1.png|thumb|Open <nowiki>https://github.com/login/device</nowiki>|none|600x600px]][[File:Vscode-tunnel-2.png|none|thumb|600x600px|Enter the code]][[File:Vscode-tunnel-3.png|none|thumb|Authorize access|513x513px]][[File:Vscode-tunnel-4.png|none|thumb|600x600px|Authorization successful]]
----

==== 6. Start the Tunnel ====
<syntaxhighlight lang="shell">
code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.
[[File:Vscode-tunnel-5.png|none|thumb|1189x1189px|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 <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code generated at this step, for example, E1F9-D7E8
* Authorize access

The VSCode tunnel is now active. Open the provided link in your browser to connect <nowiki>https://vscode.dev/tunnel/</nowiki><tunnel-name>/<full>/<path>/<to>/<your>/<working folder where you started tunnel>

For example:

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

==== 8. Trust Workspace ====
VSCode is now connected through the tunnel (cloud relay).
[[File:Vscode-tunnel-6.png|none|thumb|910x910px|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 (<code>vscode-server-linux-x64.tar.gz</code>) and temporarily store it in <code>/tmp</code>.
* 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:
[[File:Vscode-tunnel-7.png|none|thumb|908x908px|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 (<code>sub.sh</code>) as shown below:<syntaxhighlight lang="shell">
#!/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

</syntaxhighlight>'''Note:''' You can load additional compatible central modules in your batch job submission script. Any modules loaded there 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:<syntaxhighlight lang="shell">
sbatch sub.sh
</syntaxhighlight>

==== 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 <code>cat</code>to 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 of steps ====
<syntaxhighlight lang="shell">
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 44572045

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

zhuofei@ss-sub1 VSCode_tunnel$ ls
log.44588780.out sub.sh
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file first time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- VSCode tunnel is requesting GitHub device authentication ---
# --- User must open the URL and enter the code to authorize ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62
</syntaxhighlight><syntaxhighlight lang="shell">
cat log.44572045.out
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62
*
* 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).
*
[2026-04-20 09:50:11] info Using GitHub for authentication, run `code tunnel user login --provider <provider>` option to change this.
To grant access to the server, please log into https://github.com/login/device and use code 2DDE-E787
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file second time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication prompt may still appear until completed ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

# --- VS Code Server initialization message ---
*
* 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 is ready and provides a browser access link ---
Open this link in your browser https://vscode.dev/tunnel/vscode-tunnel-0416/scratch/zhuofei/VSCode_tunnel
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file third time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication message may still be shown in log ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

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

# --- Browser access link (use this on local machine) ---
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-17 16:13:13] info [tunnels::connections::relay_tunnel_host] Opened new client on channel 2

# --- Internal SSH handshake between tunnel components ---
[2026-04-17 16:13:13] info [russh::server] wrote id
[2026-04-17 16:13:13] info [russh::server] read other id

# --- Tunnel session is now active ---
[2026-04-17 16:13:13] info [russh::server] session is running

# --- VS Code checks for existing server instance ---
[2026-04-17 16:13:15] info [rpc.0] Checking /home/zhuofei/.code_tunnel/servers/.../log.txt and pid.txt for a running server...

# --- No running server found, starting a new one ---
[2026-04-17 16:13:15] info [rpc.0] Starting server...

# --- VS Code Server successfully started ---
[2026-04-17 16:13:15] info [rpc.0] Server started

# --- Job script finished, tunnel continues running in background ---
zhuofei@ss-sub4 VSCode_tunnel$
</syntaxhighlight>

=== 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>code-tunnel</code>
* <code>code-server</code>
* <code>node (server-main.js)</code>
* <code>extensionHost</code>
* <code>fileWatcher</code>
* <code>ptyHost</code>

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 [[OnDemand|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) (To be completed ZH.20260417 4:53PM) ===
Example on compute node:

Processes include:

* VSCode server
* Node.js services
* Extension hosts
* Terminal backend

Resource usage example:

* CPU: low but persistent
* Memory: non-trivial
* GPU: allocated but may be idle
* Processes: <code>code-tunnel</code>, multiple <code>node</code>

----

Across all login nodes (<code>ss-sub1</code>–<code>ss-sub4</code>):

==== Result ====
* No VSCode backend processes present
* Only Slurm launcher processes visible
* No persistent services running

==== Interpretation ====
VSCode workload is fully isolated to compute node

Login nodes remain clean and responsive
----

=== Extension Behavior ===

==== Before Python Extension ====
User extensions:

* Minimal (e.g., Copilot)

Server extensions:

* Built-in only

----

==== After Python Extension Installation ====
New extension appears:

==== Key Points ====
* User extensions → <code>~/.vscode-server/extensions/</code>
* Built-in extensions → server directory
* Server directory remains unchanged

----

==== Storage ====
* Extensions stored in home directory
* Can grow over time

==== Performance ====
Installing extensions (e.g., Python) adds:

* Language servers
* Background indexing
* Additional CPU/memory usage

----

=== Best Practices ===
* Always run inside a Slurm allocation
* Never run VSCode directly on login nodes
* Install only necessary extensions
* Clean unused extensions periodically

=== Key Takeaway ===
VSCode is a distributed, multi-process system.

It must be treated like a compute workload—not a simple SSH tool.

=== Final Note ===
This workflow is strongly recommended for:

* AI / LLM workloads
* GPU-based development
* Heavy interactive coding sessions

Visual Studio Code SSH

2026-04-17T20:55:08Z

Moses: /* Compute Node and Login Node Behavior (Observed) (To be completed ZH.20260416 4:49PM) */

==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 ([[OnDemand|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 [https://code.visualstudio.com/download 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.

[[File:Vscode_activity_bar.png | frameless]]

----

====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 [https://code.visualstudio.com/docs/editor/intellisense#:~:text=IntelliSense%20is%20a%20general%20term,%2C%20and%20%22code%20hinting.%22 IntelliSense] for Python.

[[File:Vscode_extensions.png | 400px | frameless]]

----

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.

[[File:Vscode_ssh_extension.png | 600px | frameless]]

----

====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.

[[File:Vscode_installed.png |700x700px| frameless]]

----

==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.

[[File:Vscode_sshbutton.png | frameless]]

----

====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...".

[[File:Vscode_connection_options.png | 600px | frameless]]

----

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

[[File:Vscode_add_new_ssh_host.png | 600px | frameless]]
[[File:Vscode_connection.png | 600px | frameless]]

----

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

[[File:Vscode_sshconfig.png | 600px | frameless]]

----

====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.

[[File:Vscode_chooseconnection.png | 600px | frameless]]
[[File:Vscode_password.png | 600px | frameless]]
[[File:Vscode_duo.png | 600px | frameless]]

----

====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.

[[File:Vscode_explorer.png | 600px | frameless]]

----

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.

[[File:Vscode_opendir.png |700x700px| frameless]]

----

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.

[[File:Vscode_homedir.png |700x700px| frameless]]

----

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.

[[File:Vscode_add_dir.png |700x700px| frameless]]

----

====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.

[[File:Vscode_terminal.png |714x714px| frameless ]]

== 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 ====
<syntaxhighlight lang="shell">
interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2
</syntaxhighlight>
----

==== 2. Clean Previous VSCode State (Recommended. Note that all VSCode extensions you downloaded will be removed) ====
<syntaxhighlight lang="shell">
rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel
</syntaxhighlight>
----

==== 3. Prepare Working Directory ====
<syntaxhighlight lang="shell">
cd /scratch/$USER/VSCode_tunnel/
</syntaxhighlight>
----

==== 4. Load VSCode Module ====
<syntaxhighlight lang="shell">
ml VSCode/1.88.1
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
code-tunnel tunnel user login --provider github
</syntaxhighlight>Follow the instructions in your local browser:

* Open <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code, for example, 15C1-6D7C
* Authorize access[[File:Vscode-tunnel-1.png|thumb|Open <nowiki>https://github.com/login/device</nowiki>|none|600x600px]][[File:Vscode-tunnel-2.png|none|thumb|600x600px|Enter the code]][[File:Vscode-tunnel-3.png|none|thumb|Authorize access|513x513px]][[File:Vscode-tunnel-4.png|none|thumb|600x600px|Authorization successful]]
----

==== 6. Start the Tunnel ====
<syntaxhighlight lang="shell">
code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.
[[File:Vscode-tunnel-5.png|none|thumb|1189x1189px|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 <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code generated at this step, for example, E1F9-D7E8
* Authorize access

The VSCode tunnel is now active. Open the provided link in your browser to connect <nowiki>https://vscode.dev/tunnel/</nowiki><tunnel-name>/<full>/<path>/<to>/<your>/<working folder where you started tunnel>

For example:

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

==== 8. Trust Workspace ====
VSCode is now connected through the tunnel (cloud relay).
[[File:Vscode-tunnel-6.png|none|thumb|910x910px|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 (<code>vscode-server-linux-x64.tar.gz</code>) and temporarily store it in <code>/tmp</code>.
* 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:
[[File:Vscode-tunnel-7.png|none|thumb|908x908px|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 (<code>sub.sh</code>) as shown below:<syntaxhighlight lang="shell">
#!/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

</syntaxhighlight>'''Note:''' You can load additional compatible central modules in your batch job submission script. Any modules loaded there 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:<syntaxhighlight lang="shell">
sbatch sub.sh
</syntaxhighlight>

==== 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., <code>log.44568857.out</code>). You can use commands such as <code>cat</code>to 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 of steps ====
<syntaxhighlight lang="shell">
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 44572045

zhuofei@ss-sub4 VSCode_tunnel$ sq --me
JOBID NAME PARTITION USER NODES CPUS MIN_MEMORY PRIORITY TIME TIME_LIMIT STATE NODELIST(REASON)
44572045 code_tunnel gpu_p zhuofei 1 4 32G 996 0:02 4:00:00 RUNNING ra8-8
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file first time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- VSCode tunnel is requesting GitHub device authentication ---
# --- User must open the URL and enter the code to authorize ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file second time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication prompt may still appear until completed ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

# --- VS Code Server initialization message ---
*
* 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 is ready and provides a browser access link ---
Open this link in your browser https://vscode.dev/tunnel/vscode-tunnel-0416/scratch/zhuofei/VSCode_tunnel
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file third time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication message may still be shown in log ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

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

# --- Browser access link (use this on local machine) ---
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-17 16:13:13] info [tunnels::connections::relay_tunnel_host] Opened new client on channel 2

# --- Internal SSH handshake between tunnel components ---
[2026-04-17 16:13:13] info [russh::server] wrote id
[2026-04-17 16:13:13] info [russh::server] read other id

# --- Tunnel session is now active ---
[2026-04-17 16:13:13] info [russh::server] session is running

# --- VS Code checks for existing server instance ---
[2026-04-17 16:13:15] info [rpc.0] Checking /home/zhuofei/.code_tunnel/servers/.../log.txt and pid.txt for a running server...

# --- No running server found, starting a new one ---
[2026-04-17 16:13:15] info [rpc.0] Starting server...

# --- VS Code Server successfully started ---
[2026-04-17 16:13:15] info [rpc.0] Server started

# --- Job script finished, tunnel continues running in background ---
zhuofei@ss-sub4 VSCode_tunnel$
</syntaxhighlight>

=== 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>code-tunnel</code>
* <code>code-server</code>
* <code>node (server-main.js)</code>
* <code>extensionHost</code>
* <code>fileWatcher</code>
* <code>ptyHost</code>

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 [[OnDemand|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) (To be completed ZH.20260417 4:53PM) ===
Example on compute node:

Processes include:

* VSCode server
* Node.js services
* Extension hosts
* Terminal backend

Resource usage example:

* CPU: low but persistent
* Memory: non-trivial
* GPU: allocated but may be idle
* Processes: <code>code-tunnel</code>, multiple <code>node</code>

----

Across all login nodes (<code>ss-sub1</code>–<code>ss-sub4</code>):

==== Result ====
* No VSCode backend processes present
* Only Slurm launcher processes visible
* No persistent services running

==== Interpretation ====
VSCode workload is fully isolated to compute node

Login nodes remain clean and responsive
----

=== Extension Behavior ===

==== Before Python Extension ====
User extensions:

* Minimal (e.g., Copilot)

Server extensions:

* Built-in only

----

==== After Python Extension Installation ====
New extension appears:

==== Key Points ====
* User extensions → <code>~/.vscode-server/extensions/</code>
* Built-in extensions → server directory
* Server directory remains unchanged

----

==== Storage ====
* Extensions stored in home directory
* Can grow over time

==== Performance ====
Installing extensions (e.g., Python) adds:

* Language servers
* Background indexing
* Additional CPU/memory usage

----

=== Best Practices ===
* Always run inside a Slurm allocation
* Never run VSCode directly on login nodes
* Install only necessary extensions
* Clean unused extensions periodically

=== Key Takeaway ===
VSCode is a distributed, multi-process system.

It must be treated like a compute workload—not a simple SSH tool.

=== Final Note ===
This workflow is strongly recommended for:

* AI / LLM workloads
* GPU-based development
* Heavy interactive coding sessions

Visual Studio Code SSH

2026-04-17T20:52:26Z

Moses: /* 4. What happens if you cancel the interactive job or the job reaches its time limit on the cluster? */

==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 ([[OnDemand|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 [https://code.visualstudio.com/download 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.

[[File:Vscode_activity_bar.png | frameless]]

----

====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 [https://code.visualstudio.com/docs/editor/intellisense#:~:text=IntelliSense%20is%20a%20general%20term,%2C%20and%20%22code%20hinting.%22 IntelliSense] for Python.

[[File:Vscode_extensions.png | 400px | frameless]]

----

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.

[[File:Vscode_ssh_extension.png | 600px | frameless]]

----

====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.

[[File:Vscode_installed.png |700x700px| frameless]]

----

==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.

[[File:Vscode_sshbutton.png | frameless]]

----

====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...".

[[File:Vscode_connection_options.png | 600px | frameless]]

----

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

[[File:Vscode_add_new_ssh_host.png | 600px | frameless]]
[[File:Vscode_connection.png | 600px | frameless]]

----

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

[[File:Vscode_sshconfig.png | 600px | frameless]]

----

====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.

[[File:Vscode_chooseconnection.png | 600px | frameless]]
[[File:Vscode_password.png | 600px | frameless]]
[[File:Vscode_duo.png | 600px | frameless]]

----

====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.

[[File:Vscode_explorer.png | 600px | frameless]]

----

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.

[[File:Vscode_opendir.png |700x700px| frameless]]

----

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.

[[File:Vscode_homedir.png |700x700px| frameless]]

----

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.

[[File:Vscode_add_dir.png |700x700px| frameless]]

----

====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.

[[File:Vscode_terminal.png |714x714px| frameless ]]

== 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
----

=== Step-by-Step Workflow in an Interactive GPU Job ===

==== 1. Allocate a GPU Interactive Job ====
<syntaxhighlight lang="shell">
interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2
</syntaxhighlight>
----

==== 2. Clean Previous VSCode State (Recommended. Note that all VSCode extensions you downloaded will be removed) ====
<syntaxhighlight lang="shell">
rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel
</syntaxhighlight>
----

==== 3. Prepare Working Directory ====
<syntaxhighlight lang="shell">
cd /scratch/$USER/VSCode_tunnel/
</syntaxhighlight>
----

==== 4. Load VSCode Module ====
<syntaxhighlight lang="shell">
ml VSCode/1.88.1
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
code-tunnel tunnel user login --provider github
</syntaxhighlight>Follow the instructions in your local browser:

* Open <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code, for example, 15C1-6D7C
* Authorize access[[File:Vscode-tunnel-1.png|thumb|Open <nowiki>https://github.com/login/device</nowiki>|none|600x600px]][[File:Vscode-tunnel-2.png|none|thumb|600x600px|Enter the code]][[File:Vscode-tunnel-3.png|none|thumb|Authorize access|513x513px]][[File:Vscode-tunnel-4.png|none|thumb|600x600px|Authorization successful]]
----

==== 6. Start the Tunnel ====
<syntaxhighlight lang="shell">
code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.
[[File:Vscode-tunnel-5.png|none|thumb|1189x1189px|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 <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code generated at this step, for example, E1F9-D7E8
* Authorize access

The VSCode tunnel is now active. Open the provided link in your browser to connect <nowiki>https://vscode.dev/tunnel/</nowiki><tunnel-name>/<full>/<path>/<to>/<your>/<working folder where you started tunnel>

For example:

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

==== 8. Trust Workspace ====
VSCode is now connected through the tunnel (cloud relay).
[[File:Vscode-tunnel-6.png|none|thumb|910x910px|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 (<code>vscode-server-linux-x64.tar.gz</code>) and temporarily store it in <code>/tmp</code>.
* 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:
[[File:Vscode-tunnel-7.png|none|thumb|908x908px|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 (<code>sub.sh</code>) as shown below:<syntaxhighlight lang="shell">
#!/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

</syntaxhighlight>'''Note:''' You can load additional compatible central modules in your batch job submission script. Any modules loaded there 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:<syntaxhighlight lang="shell">
sbatch sub.sh
</syntaxhighlight>

==== 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., <code>log.44568857.out</code>). You can use commands such as <code>cat</code>to 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 of steps ====
<syntaxhighlight lang="shell">
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 44572045

zhuofei@ss-sub4 VSCode_tunnel$ sq --me
JOBID NAME PARTITION USER NODES CPUS MIN_MEMORY PRIORITY TIME TIME_LIMIT STATE NODELIST(REASON)
44572045 code_tunnel gpu_p zhuofei 1 4 32G 996 0:02 4:00:00 RUNNING ra8-8
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file first time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- VSCode tunnel is requesting GitHub device authentication ---
# --- User must open the URL and enter the code to authorize ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file second time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication prompt may still appear until completed ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

# --- VS Code Server initialization message ---
*
* 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 is ready and provides a browser access link ---
Open this link in your browser https://vscode.dev/tunnel/vscode-tunnel-0416/scratch/zhuofei/VSCode_tunnel
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file third time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication message may still be shown in log ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

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

# --- Browser access link (use this on local machine) ---
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-17 16:13:13] info [tunnels::connections::relay_tunnel_host] Opened new client on channel 2

# --- Internal SSH handshake between tunnel components ---
[2026-04-17 16:13:13] info [russh::server] wrote id
[2026-04-17 16:13:13] info [russh::server] read other id

# --- Tunnel session is now active ---
[2026-04-17 16:13:13] info [russh::server] session is running

# --- VS Code checks for existing server instance ---
[2026-04-17 16:13:15] info [rpc.0] Checking /home/zhuofei/.code_tunnel/servers/.../log.txt and pid.txt for a running server...

# --- No running server found, starting a new one ---
[2026-04-17 16:13:15] info [rpc.0] Starting server...

# --- VS Code Server successfully started ---
[2026-04-17 16:13:15] info [rpc.0] Server started

# --- Job script finished, tunnel continues running in background ---
zhuofei@ss-sub4 VSCode_tunnel$
</syntaxhighlight>

=== 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>code-tunnel</code>
* <code>code-server</code>
* <code>node (server-main.js)</code>
* <code>extensionHost</code>
* <code>fileWatcher</code>
* <code>ptyHost</code>

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 [[OnDemand|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) (To be completed ZH.20260416 4:49PM) ===
Example on compute node:

Processes include:

* VSCode server
* Node.js services
* Extension hosts
* Terminal backend

Resource usage example:

* CPU: low but persistent
* Memory: non-trivial
* GPU: allocated but may be idle
* Processes: <code>code-tunnel</code>, multiple <code>node</code>

----

Across all login nodes (<code>ss-sub1</code>–<code>ss-sub4</code>):

==== Result ====
* No VSCode backend processes present
* Only Slurm launcher processes visible
* No persistent services running

==== Interpretation ====
VSCode workload is fully isolated to compute node

Login nodes remain clean and responsive
----

=== Extension Behavior ===

==== Before Python Extension ====
User extensions:

* Minimal (e.g., Copilot)

Server extensions:

* Built-in only

----

==== After Python Extension Installation ====
New extension appears:

==== Key Points ====
* User extensions → <code>~/.vscode-server/extensions/</code>
* Built-in extensions → server directory
* Server directory remains unchanged

----

==== Storage ====
* Extensions stored in home directory
* Can grow over time

==== Performance ====
Installing extensions (e.g., Python) adds:

* Language servers
* Background indexing
* Additional CPU/memory usage

----

=== Advantages of This Workflow ===
* Prevents login node overload
* Enables GPU-based development
* Supports AI/LLM workflows
* Works entirely in browser
* Scales cleanly across users

----

=== Best Practices ===
* Always run inside a Slurm allocation
* Never run VSCode directly on login nodes
* Install only necessary extensions
* Clean unused extensions periodically

=== Key Takeaway ===
VSCode is a distributed, multi-process system.

It must be treated like a compute workload—not a simple SSH tool.

=== Final Note ===
This workflow is strongly recommended for:

* AI / LLM workloads
* GPU-based development
* Heavy interactive coding sessions

Visual Studio Code SSH

2026-04-17T20:50:29Z

Moses: /* 4, Example of steps: */

==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 ([[OnDemand|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 [https://code.visualstudio.com/download 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.

[[File:Vscode_activity_bar.png | frameless]]

----

====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 [https://code.visualstudio.com/docs/editor/intellisense#:~:text=IntelliSense%20is%20a%20general%20term,%2C%20and%20%22code%20hinting.%22 IntelliSense] for Python.

[[File:Vscode_extensions.png | 400px | frameless]]

----

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.

[[File:Vscode_ssh_extension.png | 600px | frameless]]

----

====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.

[[File:Vscode_installed.png |700x700px| frameless]]

----

==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.

[[File:Vscode_sshbutton.png | frameless]]

----

====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...".

[[File:Vscode_connection_options.png | 600px | frameless]]

----

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

[[File:Vscode_add_new_ssh_host.png | 600px | frameless]]
[[File:Vscode_connection.png | 600px | frameless]]

----

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

[[File:Vscode_sshconfig.png | 600px | frameless]]

----

====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.

[[File:Vscode_chooseconnection.png | 600px | frameless]]
[[File:Vscode_password.png | 600px | frameless]]
[[File:Vscode_duo.png | 600px | frameless]]

----

====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.

[[File:Vscode_explorer.png | 600px | frameless]]

----

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.

[[File:Vscode_opendir.png |700x700px| frameless]]

----

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.

[[File:Vscode_homedir.png |700x700px| frameless]]

----

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.

[[File:Vscode_add_dir.png |700x700px| frameless]]

----

====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.

[[File:Vscode_terminal.png |714x714px| frameless ]]

== 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
----

=== Step-by-Step Workflow in an Interactive GPU Job ===

==== 1. Allocate a GPU Interactive Job ====
<syntaxhighlight lang="shell">
interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2
</syntaxhighlight>
----

==== 2. Clean Previous VSCode State (Recommended. Note that all VSCode extensions you downloaded will be removed) ====
<syntaxhighlight lang="shell">
rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel
</syntaxhighlight>
----

==== 3. Prepare Working Directory ====
<syntaxhighlight lang="shell">
cd /scratch/$USER/VSCode_tunnel/
</syntaxhighlight>
----

==== 4. Load VSCode Module ====
<syntaxhighlight lang="shell">
ml VSCode/1.88.1
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
code-tunnel tunnel user login --provider github
</syntaxhighlight>Follow the instructions in your local browser:

* Open <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code, for example, 15C1-6D7C
* Authorize access[[File:Vscode-tunnel-1.png|thumb|Open <nowiki>https://github.com/login/device</nowiki>|none|600x600px]][[File:Vscode-tunnel-2.png|none|thumb|600x600px|Enter the code]][[File:Vscode-tunnel-3.png|none|thumb|Authorize access|513x513px]][[File:Vscode-tunnel-4.png|none|thumb|600x600px|Authorization successful]]
----

==== 6. Start the Tunnel ====
<syntaxhighlight lang="shell">
code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.
[[File:Vscode-tunnel-5.png|none|thumb|1189x1189px|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 <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code generated at this step, for example, E1F9-D7E8
* Authorize access

The VSCode tunnel is now active. Open the provided link in your browser to connect <nowiki>https://vscode.dev/tunnel/</nowiki><tunnel-name>/<full>/<path>/<to>/<your>/<working folder where you started tunnel>

For example:

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

==== 8. Trust Workspace ====
VSCode is now connected through the tunnel (cloud relay).
[[File:Vscode-tunnel-6.png|none|thumb|910x910px|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 (<code>vscode-server-linux-x64.tar.gz</code>) and temporarily store it in <code>/tmp</code>.
* 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:
[[File:Vscode-tunnel-7.png|none|thumb|908x908px|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 (<code>sub.sh</code>) as shown below:<syntaxhighlight lang="shell">
#!/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

</syntaxhighlight>'''Note:''' You can load additional compatible central modules in your batch job submission script. Any modules loaded there 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:<syntaxhighlight lang="shell">
sbatch sub.sh
</syntaxhighlight>

==== 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., <code>log.44568857.out</code>). You can use commands such as <code>cat</code>to 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 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.

==== 5. Example of steps ====
<syntaxhighlight lang="shell">
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 44572045

zhuofei@ss-sub4 VSCode_tunnel$ sq --me
JOBID NAME PARTITION USER NODES CPUS MIN_MEMORY PRIORITY TIME TIME_LIMIT STATE NODELIST(REASON)
44572045 code_tunnel gpu_p zhuofei 1 4 32G 996 0:02 4:00:00 RUNNING ra8-8
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file first time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- VSCode tunnel is requesting GitHub device authentication ---
# --- User must open the URL and enter the code to authorize ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file second time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication prompt may still appear until completed ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

# --- VS Code Server initialization message ---
*
* 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 is ready and provides a browser access link ---
Open this link in your browser https://vscode.dev/tunnel/vscode-tunnel-0416/scratch/zhuofei/VSCode_tunnel
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file third time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication message may still be shown in log ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

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

# --- Browser access link (use this on local machine) ---
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-17 16:13:13] info [tunnels::connections::relay_tunnel_host] Opened new client on channel 2

# --- Internal SSH handshake between tunnel components ---
[2026-04-17 16:13:13] info [russh::server] wrote id
[2026-04-17 16:13:13] info [russh::server] read other id

# --- Tunnel session is now active ---
[2026-04-17 16:13:13] info [russh::server] session is running

# --- VS Code checks for existing server instance ---
[2026-04-17 16:13:15] info [rpc.0] Checking /home/zhuofei/.code_tunnel/servers/.../log.txt and pid.txt for a running server...

# --- No running server found, starting a new one ---
[2026-04-17 16:13:15] info [rpc.0] Starting server...

# --- VS Code Server successfully started ---
[2026-04-17 16:13:15] info [rpc.0] Server started

# --- Job script finished, tunnel continues running in background ---
zhuofei@ss-sub4 VSCode_tunnel$
</syntaxhighlight>

=== 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>code-tunnel</code>
* <code>code-server</code>
* <code>node (server-main.js)</code>
* <code>extensionHost</code>
* <code>fileWatcher</code>
* <code>ptyHost</code>

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 [[OnDemand|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) (To be completed ZH.20260416 4:49PM) ===
Example on compute node:

Processes include:

* VSCode server
* Node.js services
* Extension hosts
* Terminal backend

Resource usage example:

* CPU: low but persistent
* Memory: non-trivial
* GPU: allocated but may be idle
* Processes: <code>code-tunnel</code>, multiple <code>node</code>

----

Across all login nodes (<code>ss-sub1</code>–<code>ss-sub4</code>):

==== Result ====
* No VSCode backend processes present
* Only Slurm launcher processes visible
* No persistent services running

==== Interpretation ====
VSCode workload is fully isolated to compute node

Login nodes remain clean and responsive
----

=== Extension Behavior ===

==== Before Python Extension ====
User extensions:

* Minimal (e.g., Copilot)

Server extensions:

* Built-in only

----

==== After Python Extension Installation ====
New extension appears:

==== Key Points ====
* User extensions → <code>~/.vscode-server/extensions/</code>
* Built-in extensions → server directory
* Server directory remains unchanged

----

==== Storage ====
* Extensions stored in home directory
* Can grow over time

==== Performance ====
Installing extensions (e.g., Python) adds:

* Language servers
* Background indexing
* Additional CPU/memory usage

----

=== Advantages of This Workflow ===
* Prevents login node overload
* Enables GPU-based development
* Supports AI/LLM workflows
* Works entirely in browser
* Scales cleanly across users

----

=== Best Practices ===
* Always run inside a Slurm allocation
* Never run VSCode directly on login nodes
* Install only necessary extensions
* Clean unused extensions periodically

=== Key Takeaway ===
VSCode is a distributed, multi-process system.

It must be treated like a compute workload—not a simple SSH tool.

=== Final Note ===
This workflow is strongly recommended for:

* AI / LLM workloads
* GPU-based development
* Heavy interactive coding sessions

Visual Studio Code SSH

2026-04-17T20:48:56Z

Moses: /* Step-by-Step Workflow in a batch GPU Job */

==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 ([[OnDemand|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 [https://code.visualstudio.com/download 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.

[[File:Vscode_activity_bar.png | frameless]]

----

====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 [https://code.visualstudio.com/docs/editor/intellisense#:~:text=IntelliSense%20is%20a%20general%20term,%2C%20and%20%22code%20hinting.%22 IntelliSense] for Python.

[[File:Vscode_extensions.png | 400px | frameless]]

----

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.

[[File:Vscode_ssh_extension.png | 600px | frameless]]

----

====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.

[[File:Vscode_installed.png |700x700px| frameless]]

----

==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.

[[File:Vscode_sshbutton.png | frameless]]

----

====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...".

[[File:Vscode_connection_options.png | 600px | frameless]]

----

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

[[File:Vscode_add_new_ssh_host.png | 600px | frameless]]
[[File:Vscode_connection.png | 600px | frameless]]

----

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

[[File:Vscode_sshconfig.png | 600px | frameless]]

----

====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.

[[File:Vscode_chooseconnection.png | 600px | frameless]]
[[File:Vscode_password.png | 600px | frameless]]
[[File:Vscode_duo.png | 600px | frameless]]

----

====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.

[[File:Vscode_explorer.png | 600px | frameless]]

----

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.

[[File:Vscode_opendir.png |700x700px| frameless]]

----

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.

[[File:Vscode_homedir.png |700x700px| frameless]]

----

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.

[[File:Vscode_add_dir.png |700x700px| frameless]]

----

====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.

[[File:Vscode_terminal.png |714x714px| frameless ]]

== 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
----

=== Step-by-Step Workflow in an Interactive GPU Job ===

==== 1. Allocate a GPU Interactive Job ====
<syntaxhighlight lang="shell">
interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2
</syntaxhighlight>
----

==== 2. Clean Previous VSCode State (Recommended. Note that all VSCode extensions you downloaded will be removed) ====
<syntaxhighlight lang="shell">
rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel
</syntaxhighlight>
----

==== 3. Prepare Working Directory ====
<syntaxhighlight lang="shell">
cd /scratch/$USER/VSCode_tunnel/
</syntaxhighlight>
----

==== 4. Load VSCode Module ====
<syntaxhighlight lang="shell">
ml VSCode/1.88.1
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
code-tunnel tunnel user login --provider github
</syntaxhighlight>Follow the instructions in your local browser:

* Open <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code, for example, 15C1-6D7C
* Authorize access[[File:Vscode-tunnel-1.png|thumb|Open <nowiki>https://github.com/login/device</nowiki>|none|600x600px]][[File:Vscode-tunnel-2.png|none|thumb|600x600px|Enter the code]][[File:Vscode-tunnel-3.png|none|thumb|Authorize access|513x513px]][[File:Vscode-tunnel-4.png|none|thumb|600x600px|Authorization successful]]
----

==== 6. Start the Tunnel ====
<syntaxhighlight lang="shell">
code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.
[[File:Vscode-tunnel-5.png|none|thumb|1189x1189px|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 <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code generated at this step, for example, E1F9-D7E8
* Authorize access

The VSCode tunnel is now active. Open the provided link in your browser to connect <nowiki>https://vscode.dev/tunnel/</nowiki><tunnel-name>/<full>/<path>/<to>/<your>/<working folder where you started tunnel>

For example:

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

==== 8. Trust Workspace ====
VSCode is now connected through the tunnel (cloud relay).
[[File:Vscode-tunnel-6.png|none|thumb|910x910px|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 (<code>vscode-server-linux-x64.tar.gz</code>) and temporarily store it in <code>/tmp</code>.
* 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:
[[File:Vscode-tunnel-7.png|none|thumb|908x908px|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 (<code>sub.sh</code>) as shown below:<syntaxhighlight lang="shell">
#!/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

</syntaxhighlight>'''Note:''' You can load additional compatible central modules in your batch job submission script. Any modules loaded there 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:<syntaxhighlight lang="shell">
sbatch sub.sh
</syntaxhighlight>

==== 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., <code>log.44568857.out</code>). You can use commands such as <code>cat</code>to 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, Example of steps: ====
<syntaxhighlight lang="shell">
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 44572045

zhuofei@ss-sub4 VSCode_tunnel$ sq --me
JOBID NAME PARTITION USER NODES CPUS MIN_MEMORY PRIORITY TIME TIME_LIMIT STATE NODELIST(REASON)
44572045 code_tunnel gpu_p zhuofei 1 4 32G 996 0:02 4:00:00 RUNNING ra8-8
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file first time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- VSCode tunnel is requesting GitHub device authentication ---
# --- User must open the URL and enter the code to authorize ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file second time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication prompt may still appear until completed ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

# --- VS Code Server initialization message ---
*
* 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 is ready and provides a browser access link ---
Open this link in your browser https://vscode.dev/tunnel/vscode-tunnel-0416/scratch/zhuofei/VSCode_tunnel
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file third time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication message may still be shown in log ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

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

# --- Browser access link (use this on local machine) ---
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-17 16:13:13] info [tunnels::connections::relay_tunnel_host] Opened new client on channel 2

# --- Internal SSH handshake between tunnel components ---
[2026-04-17 16:13:13] info [russh::server] wrote id
[2026-04-17 16:13:13] info [russh::server] read other id

# --- Tunnel session is now active ---
[2026-04-17 16:13:13] info [russh::server] session is running

# --- VS Code checks for existing server instance ---
[2026-04-17 16:13:15] info [rpc.0] Checking /home/zhuofei/.code_tunnel/servers/.../log.txt and pid.txt for a running server...

# --- No running server found, starting a new one ---
[2026-04-17 16:13:15] info [rpc.0] Starting server...

# --- VS Code Server successfully started ---
[2026-04-17 16:13:15] info [rpc.0] Server started

# --- Job script finished, tunnel continues running in background ---
zhuofei@ss-sub4 VSCode_tunnel$
</syntaxhighlight>

=== 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>code-tunnel</code>
* <code>code-server</code>
* <code>node (server-main.js)</code>
* <code>extensionHost</code>
* <code>fileWatcher</code>
* <code>ptyHost</code>

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 [[OnDemand|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) (To be completed ZH.20260416 4:49PM) ===
Example on compute node:

Processes include:

* VSCode server
* Node.js services
* Extension hosts
* Terminal backend

Resource usage example:

* CPU: low but persistent
* Memory: non-trivial
* GPU: allocated but may be idle
* Processes: <code>code-tunnel</code>, multiple <code>node</code>

----

Across all login nodes (<code>ss-sub1</code>–<code>ss-sub4</code>):

==== Result ====
* No VSCode backend processes present
* Only Slurm launcher processes visible
* No persistent services running

==== Interpretation ====
VSCode workload is fully isolated to compute node

Login nodes remain clean and responsive
----

=== Extension Behavior ===

==== Before Python Extension ====
User extensions:

* Minimal (e.g., Copilot)

Server extensions:

* Built-in only

----

==== After Python Extension Installation ====
New extension appears:

==== Key Points ====
* User extensions → <code>~/.vscode-server/extensions/</code>
* Built-in extensions → server directory
* Server directory remains unchanged

----

==== Storage ====
* Extensions stored in home directory
* Can grow over time

==== Performance ====
Installing extensions (e.g., Python) adds:

* Language servers
* Background indexing
* Additional CPU/memory usage

----

=== Advantages of This Workflow ===
* Prevents login node overload
* Enables GPU-based development
* Supports AI/LLM workflows
* Works entirely in browser
* Scales cleanly across users

----

=== Best Practices ===
* Always run inside a Slurm allocation
* Never run VSCode directly on login nodes
* Install only necessary extensions
* Clean unused extensions periodically

=== Key Takeaway ===
VSCode is a distributed, multi-process system.

It must be treated like a compute workload—not a simple SSH tool.

=== Final Note ===
This workflow is strongly recommended for:

* AI / LLM workloads
* GPU-based development
* Heavy interactive coding sessions

Visual Studio Code SSH

2026-04-17T20:36:32Z

Moses: /* What Happens Under the Hood When Using VSCode */

==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 ([[OnDemand|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 [https://code.visualstudio.com/download 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.

[[File:Vscode_activity_bar.png | frameless]]

----

====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 [https://code.visualstudio.com/docs/editor/intellisense#:~:text=IntelliSense%20is%20a%20general%20term,%2C%20and%20%22code%20hinting.%22 IntelliSense] for Python.

[[File:Vscode_extensions.png | 400px | frameless]]

----

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.

[[File:Vscode_ssh_extension.png | 600px | frameless]]

----

====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.

[[File:Vscode_installed.png |700x700px| frameless]]

----

==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.

[[File:Vscode_sshbutton.png | frameless]]

----

====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...".

[[File:Vscode_connection_options.png | 600px | frameless]]

----

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

[[File:Vscode_add_new_ssh_host.png | 600px | frameless]]
[[File:Vscode_connection.png | 600px | frameless]]

----

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

[[File:Vscode_sshconfig.png | 600px | frameless]]

----

====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.

[[File:Vscode_chooseconnection.png | 600px | frameless]]
[[File:Vscode_password.png | 600px | frameless]]
[[File:Vscode_duo.png | 600px | frameless]]

----

====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.

[[File:Vscode_explorer.png | 600px | frameless]]

----

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.

[[File:Vscode_opendir.png |700x700px| frameless]]

----

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.

[[File:Vscode_homedir.png |700x700px| frameless]]

----

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.

[[File:Vscode_add_dir.png |700x700px| frameless]]

----

====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.

[[File:Vscode_terminal.png |714x714px| frameless ]]

== 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
----

=== Step-by-Step Workflow in an Interactive GPU Job ===

==== 1. Allocate a GPU Interactive Job ====
<syntaxhighlight lang="shell">
interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2
</syntaxhighlight>
----

==== 2. Clean Previous VSCode State (Recommended. Note that all VSCode extensions you downloaded will be removed) ====
<syntaxhighlight lang="shell">
rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel
</syntaxhighlight>
----

==== 3. Prepare Working Directory ====
<syntaxhighlight lang="shell">
cd /scratch/$USER/VSCode_tunnel/
</syntaxhighlight>
----

==== 4. Load VSCode Module ====
<syntaxhighlight lang="shell">
ml VSCode/1.88.1
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
code-tunnel tunnel user login --provider github
</syntaxhighlight>Follow the instructions in your local browser:

* Open <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code, for example, 15C1-6D7C
* Authorize access[[File:Vscode-tunnel-1.png|thumb|Open <nowiki>https://github.com/login/device</nowiki>|none|600x600px]][[File:Vscode-tunnel-2.png|none|thumb|600x600px|Enter the code]][[File:Vscode-tunnel-3.png|none|thumb|Authorize access|513x513px]][[File:Vscode-tunnel-4.png|none|thumb|600x600px|Authorization successful]]
----

==== 6. Start the Tunnel ====
<syntaxhighlight lang="shell">
code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.
[[File:Vscode-tunnel-5.png|none|thumb|1189x1189px|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 <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code generated at this step, for example, E1F9-D7E8
* Authorize access

The VSCode tunnel is now active. Open the provided link in your browser to connect <nowiki>https://vscode.dev/tunnel/</nowiki><tunnel-name>/<full>/<path>/<to>/<your>/<working folder where you started tunnel>

For example:

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

==== 8. Trust Workspace ====
VSCode is now connected through the tunnel (cloud relay).
[[File:Vscode-tunnel-6.png|none|thumb|910x910px|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 (<code>vscode-server-linux-x64.tar.gz</code>) and temporarily store it in <code>/tmp</code>.
* 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:
[[File:Vscode-tunnel-7.png|none|thumb|908x908px|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 ===

Within the working directory of the interactive job described above, you can use a batch job submission script (<code>sub.sh</code>) as shown below:<syntaxhighlight lang="shell">
#!/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

</syntaxhighlight>'''Note:''' You can load additional compatible central modules in your batch job submission script. Any modules loaded there will be configured and available within your VSCode tunnel working environment.

You can then submit the job to the cluster using:<syntaxhighlight lang="shell">
sbatch sub.sh
</syntaxhighlight>Once the job starts running, monitor the job’s standard output log file (e.g., <code>log.44568857.out</code>). You can use commands such as <code>cat</code>to 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.

Below is an example of steps described above: <syntaxhighlight lang="shell">
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 44572045

zhuofei@ss-sub4 VSCode_tunnel$ sq --me
JOBID NAME PARTITION USER NODES CPUS MIN_MEMORY PRIORITY TIME TIME_LIMIT STATE NODELIST(REASON)
44572045 code_tunnel gpu_p zhuofei 1 4 32G 996 0:02 4:00:00 RUNNING ra8-8
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file first time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- VSCode tunnel is requesting GitHub device authentication ---
# --- User must open the URL and enter the code to authorize ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file second time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication prompt may still appear until completed ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

# --- VS Code Server initialization message ---
*
* 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 is ready and provides a browser access link ---
Open this link in your browser https://vscode.dev/tunnel/vscode-tunnel-0416/scratch/zhuofei/VSCode_tunnel
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file third time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication message may still be shown in log ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

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

# --- Browser access link (use this on local machine) ---
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-17 16:13:13] info [tunnels::connections::relay_tunnel_host] Opened new client on channel 2

# --- Internal SSH handshake between tunnel components ---
[2026-04-17 16:13:13] info [russh::server] wrote id
[2026-04-17 16:13:13] info [russh::server] read other id

# --- Tunnel session is now active ---
[2026-04-17 16:13:13] info [russh::server] session is running

# --- VS Code checks for existing server instance ---
[2026-04-17 16:13:15] info [rpc.0] Checking /home/zhuofei/.code_tunnel/servers/.../log.txt and pid.txt for a running server...

# --- No running server found, starting a new one ---
[2026-04-17 16:13:15] info [rpc.0] Starting server...

# --- VS Code Server successfully started ---
[2026-04-17 16:13:15] info [rpc.0] Server started

# --- Job script finished, tunnel continues running in background ---
zhuofei@ss-sub4 VSCode_tunnel$
</syntaxhighlight>

=== 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>code-tunnel</code>
* <code>code-server</code>
* <code>node (server-main.js)</code>
* <code>extensionHost</code>
* <code>fileWatcher</code>
* <code>ptyHost</code>

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 [[OnDemand|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) (To be completed ZH.20260416 4:49PM) ===
Example on compute node:

Processes include:

* VSCode server
* Node.js services
* Extension hosts
* Terminal backend

Resource usage example:

* CPU: low but persistent
* Memory: non-trivial
* GPU: allocated but may be idle
* Processes: <code>code-tunnel</code>, multiple <code>node</code>

----

Across all login nodes (<code>ss-sub1</code>–<code>ss-sub4</code>):

==== Result ====
* No VSCode backend processes present
* Only Slurm launcher processes visible
* No persistent services running

==== Interpretation ====
VSCode workload is fully isolated to compute node

Login nodes remain clean and responsive
----

=== Extension Behavior ===

==== Before Python Extension ====
User extensions:

* Minimal (e.g., Copilot)

Server extensions:

* Built-in only

----

==== After Python Extension Installation ====
New extension appears:

==== Key Points ====
* User extensions → <code>~/.vscode-server/extensions/</code>
* Built-in extensions → server directory
* Server directory remains unchanged

----

==== Storage ====
* Extensions stored in home directory
* Can grow over time

==== Performance ====
Installing extensions (e.g., Python) adds:

* Language servers
* Background indexing
* Additional CPU/memory usage

----

=== Advantages of This Workflow ===
* Prevents login node overload
* Enables GPU-based development
* Supports AI/LLM workflows
* Works entirely in browser
* Scales cleanly across users

----

=== Best Practices ===
* Always run inside a Slurm allocation
* Never run VSCode directly on login nodes
* Install only necessary extensions
* Clean unused extensions periodically

=== Key Takeaway ===
VSCode is a distributed, multi-process system.

It must be treated like a compute workload—not a simple SSH tool.

=== Final Note ===
This workflow is strongly recommended for:

* AI / LLM workloads
* GPU-based development
* Heavy interactive coding sessions

Visual Studio Code SSH

2026-04-17T20:29:14Z

Moses: /* 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 connect */

==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 ([[OnDemand|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 [https://code.visualstudio.com/download 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.

[[File:Vscode_activity_bar.png | frameless]]

----

====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 [https://code.visualstudio.com/docs/editor/intellisense#:~:text=IntelliSense%20is%20a%20general%20term,%2C%20and%20%22code%20hinting.%22 IntelliSense] for Python.

[[File:Vscode_extensions.png | 400px | frameless]]

----

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.

[[File:Vscode_ssh_extension.png | 600px | frameless]]

----

====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.

[[File:Vscode_installed.png |700x700px| frameless]]

----

==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.

[[File:Vscode_sshbutton.png | frameless]]

----

====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...".

[[File:Vscode_connection_options.png | 600px | frameless]]

----

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

[[File:Vscode_add_new_ssh_host.png | 600px | frameless]]
[[File:Vscode_connection.png | 600px | frameless]]

----

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

[[File:Vscode_sshconfig.png | 600px | frameless]]

----

====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.

[[File:Vscode_chooseconnection.png | 600px | frameless]]
[[File:Vscode_password.png | 600px | frameless]]
[[File:Vscode_duo.png | 600px | frameless]]

----

====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.

[[File:Vscode_explorer.png | 600px | frameless]]

----

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.

[[File:Vscode_opendir.png |700x700px| frameless]]

----

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.

[[File:Vscode_homedir.png |700x700px| frameless]]

----

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.

[[File:Vscode_add_dir.png |700x700px| frameless]]

----

====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.

[[File:Vscode_terminal.png |714x714px| frameless ]]

== 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
----

=== Step-by-Step Workflow in an Interactive GPU Job ===

==== 1. Allocate a GPU Interactive Job ====
<syntaxhighlight lang="shell">
interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2
</syntaxhighlight>
----

==== 2. Clean Previous VSCode State (Recommended. Note that all VSCode extensions you downloaded will be removed) ====
<syntaxhighlight lang="shell">
rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel
</syntaxhighlight>
----

==== 3. Prepare Working Directory ====
<syntaxhighlight lang="shell">
cd /scratch/$USER/VSCode_tunnel/
</syntaxhighlight>
----

==== 4. Load VSCode Module ====
<syntaxhighlight lang="shell">
ml VSCode/1.88.1
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
code-tunnel tunnel user login --provider github
</syntaxhighlight>Follow the instructions in your local browser:

* Open <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code, for example, 15C1-6D7C
* Authorize access[[File:Vscode-tunnel-1.png|thumb|Open <nowiki>https://github.com/login/device</nowiki>|none|600x600px]][[File:Vscode-tunnel-2.png|none|thumb|600x600px|Enter the code]][[File:Vscode-tunnel-3.png|none|thumb|Authorize access|513x513px]][[File:Vscode-tunnel-4.png|none|thumb|600x600px|Authorization successful]]
----

==== 6. Start the Tunnel ====
<syntaxhighlight lang="shell">
code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.
[[File:Vscode-tunnel-5.png|none|thumb|1189x1189px|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 <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code generated at this step, for example, E1F9-D7E8
* Authorize access

The VSCode tunnel is now active. Open the provided link in your browser to connect <nowiki>https://vscode.dev/tunnel/</nowiki><tunnel-name>/<full>/<path>/<to>/<your>/<working folder where you started tunnel>

For example:

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

==== 8. Trust Workspace ====
VSCode is now connected through the tunnel (cloud relay).
[[File:Vscode-tunnel-6.png|none|thumb|910x910px|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 (<code>vscode-server-linux-x64.tar.gz</code>) and temporarily store it in <code>/tmp</code>.
* 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:
[[File:Vscode-tunnel-7.png|none|thumb|908x908px|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 ===

Within the working directory of the interactive job described above, you can use a batch job submission script (<code>sub.sh</code>) as shown below:<syntaxhighlight lang="shell">
#!/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

</syntaxhighlight>'''Note:''' You can load additional compatible central modules in your batch job submission script. Any modules loaded there will be configured and available within your VSCode tunnel working environment.

You can then submit the job to the cluster using:<syntaxhighlight lang="shell">
sbatch sub.sh
</syntaxhighlight>Once the job starts running, monitor the job’s standard output log file (e.g., <code>log.44568857.out</code>). You can use commands such as <code>cat</code>to 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.

Below is an example of steps described above: <syntaxhighlight lang="shell">
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 44572045

zhuofei@ss-sub4 VSCode_tunnel$ sq --me
JOBID NAME PARTITION USER NODES CPUS MIN_MEMORY PRIORITY TIME TIME_LIMIT STATE NODELIST(REASON)
44572045 code_tunnel gpu_p zhuofei 1 4 32G 996 0:02 4:00:00 RUNNING ra8-8
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file first time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- VSCode tunnel is requesting GitHub device authentication ---
# --- User must open the URL and enter the code to authorize ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file second time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication prompt may still appear until completed ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

# --- VS Code Server initialization message ---
*
* 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 is ready and provides a browser access link ---
Open this link in your browser https://vscode.dev/tunnel/vscode-tunnel-0416/scratch/zhuofei/VSCode_tunnel
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file third time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication message may still be shown in log ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

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

# --- Browser access link (use this on local machine) ---
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-17 16:13:13] info [tunnels::connections::relay_tunnel_host] Opened new client on channel 2

# --- Internal SSH handshake between tunnel components ---
[2026-04-17 16:13:13] info [russh::server] wrote id
[2026-04-17 16:13:13] info [russh::server] read other id

# --- Tunnel session is now active ---
[2026-04-17 16:13:13] info [russh::server] session is running

# --- VS Code checks for existing server instance ---
[2026-04-17 16:13:15] info [rpc.0] Checking /home/zhuofei/.code_tunnel/servers/.../log.txt and pid.txt for a running server...

# --- No running server found, starting a new one ---
[2026-04-17 16:13:15] info [rpc.0] Starting server...

# --- VS Code Server successfully started ---
[2026-04-17 16:13:15] info [rpc.0] Server started

# --- Job script finished, tunnel continues running in background ---
zhuofei@ss-sub4 VSCode_tunnel$
</syntaxhighlight>

== 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>code-tunnel</code>
* <code>code-server</code>
* <code>node (server-main.js)</code>
* <code>extensionHost</code>
* <code>fileWatcher</code>
* <code>ptyHost</code>

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 [[OnDemand|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) (To be completed ZH.20260416 4:49PM) ===
Example on compute node:

Processes include:

* VSCode server
* Node.js services
* Extension hosts
* Terminal backend

Resource usage example:

* CPU: low but persistent
* Memory: non-trivial
* GPU: allocated but may be idle
* Processes: <code>code-tunnel</code>, multiple <code>node</code>

----

Across all login nodes (<code>ss-sub1</code>–<code>ss-sub4</code>):

==== Result ====
* No VSCode backend processes present
* Only Slurm launcher processes visible
* No persistent services running

==== Interpretation ====
VSCode workload is fully isolated to compute node

Login nodes remain clean and responsive
----

*

----

== Extension Behavior ==

==== Before Python Extension ====
User extensions:

* Minimal (e.g., Copilot)

Server extensions:

* Built-in only

----

==== After Python Extension Installation ====
New extension appears:

==== Key Points ====
* User extensions → <code>~/.vscode-server/extensions/</code>
* Built-in extensions → server directory
* Server directory remains unchanged

----

=== HPC Implications ===

==== Storage ====
* Extensions stored in home directory
* Can grow over time

==== Performance ====
Installing extensions (e.g., Python) adds:

* Language servers
* Background indexing
* Additional CPU/memory usage

----

== Best Practices ==
* Always run inside a Slurm allocation
* Never run VSCode on login nodes
* Use <code>/scratch</code> for active work
* Install only necessary extensions
* Clean unused extensions periodically

----

== Advantages of This Workflow ==
* Prevents login node overload
* Enables GPU-based development
* Supports AI/LLM workflows
* Works entirely in browser
* Scales cleanly across users

----

== Key Takeaway ==
<blockquote>VSCode is a distributed, multi-process system.

It must be treated like a compute workload—not a simple SSH tool.</blockquote>
----

== Final Note ==
This workflow is strongly recommended for:

* AI / LLM workloads
* GPU-based development
* Heavy interactive coding sessions

Visual Studio Code SSH

2026-04-17T20:28:25Z

Moses: /* Step-by-Step Workflow in a batch GPU Job */

==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 ([[OnDemand|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 [https://code.visualstudio.com/download 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.

[[File:Vscode_activity_bar.png | frameless]]

----

====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 [https://code.visualstudio.com/docs/editor/intellisense#:~:text=IntelliSense%20is%20a%20general%20term,%2C%20and%20%22code%20hinting.%22 IntelliSense] for Python.

[[File:Vscode_extensions.png | 400px | frameless]]

----

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.

[[File:Vscode_ssh_extension.png | 600px | frameless]]

----

====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.

[[File:Vscode_installed.png |700x700px| frameless]]

----

==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.

[[File:Vscode_sshbutton.png | frameless]]

----

====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...".

[[File:Vscode_connection_options.png | 600px | frameless]]

----

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

[[File:Vscode_add_new_ssh_host.png | 600px | frameless]]
[[File:Vscode_connection.png | 600px | frameless]]

----

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

[[File:Vscode_sshconfig.png | 600px | frameless]]

----

====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.

[[File:Vscode_chooseconnection.png | 600px | frameless]]
[[File:Vscode_password.png | 600px | frameless]]
[[File:Vscode_duo.png | 600px | frameless]]

----

====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.

[[File:Vscode_explorer.png | 600px | frameless]]

----

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.

[[File:Vscode_opendir.png |700x700px| frameless]]

----

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.

[[File:Vscode_homedir.png |700x700px| frameless]]

----

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.

[[File:Vscode_add_dir.png |700x700px| frameless]]

----

====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.

[[File:Vscode_terminal.png |714x714px| frameless ]]

== 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
----

=== Step-by-Step Workflow in an Interactive GPU Job ===

==== 1. Allocate a GPU Interactive Job ====
<syntaxhighlight lang="shell">
interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2
</syntaxhighlight>
----

==== 2. Clean Previous VSCode State (Recommended. Note that all VSCode extensions you downloaded will be removed) ====
<syntaxhighlight lang="shell">
rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel
</syntaxhighlight>
----

==== 3. Prepare Working Directory ====
<syntaxhighlight lang="shell">
cd /scratch/$USER/VSCode_tunnel/
</syntaxhighlight>
----

==== 4. Load VSCode Module ====
<syntaxhighlight lang="shell">
ml VSCode/1.88.1
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
code-tunnel tunnel user login --provider github
</syntaxhighlight>Follow the instructions in your local browser:

* Open <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code, for example, 15C1-6D7C
* Authorize access[[File:Vscode-tunnel-1.png|thumb|Open <nowiki>https://github.com/login/device</nowiki>|none|600x600px]][[File:Vscode-tunnel-2.png|none|thumb|600x600px|Enter the code]][[File:Vscode-tunnel-3.png|none|thumb|Authorize access|513x513px]][[File:Vscode-tunnel-4.png|none|thumb|600x600px|Authorization successful]]
----

==== 6. Start the Tunnel ====
<syntaxhighlight lang="shell">
code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.
[[File:Vscode-tunnel-5.png|none|thumb|1189x1189px|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 <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code generated at this step, for example, E1F9-D7E8
* Authorize access

The VSCode tunnel is now active. Open the provided link in your browser to connect <nowiki>https://vscode.dev/tunnel/</nowiki><tunnel-name>/<full>/<path>/<to>/<your>/<working folder where you started tunnel>

For example:

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

==== 8. Trust Workspace ====
VSCode is now connected through the tunnel (cloud relay).
[[File:Vscode-tunnel-6.png|none|thumb|910x910px|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 (<code>vscode-server-linux-x64.tar.gz</code>) and temporarily store it in <code>/tmp</code>.
* 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:
[[File:Vscode-tunnel-7.png|none|thumb|908x908px|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 ===

Within the working directory of the interactive job described above, you can use a batch job submission script (<code>sub.sh</code>) as shown below:<syntaxhighlight lang="shell">
#!/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

</syntaxhighlight>'''Note:''' You can load additional compatible central modules in your batch job submission script. Any modules loaded there will be configured and available within your VSCode tunnel working environment.

You can then submit the job to the cluster using:<syntaxhighlight lang="shell">
sbatch sub.sh
</syntaxhighlight>Once the job starts running, monitor the job’s standard output log file (e.g., <code>log.44568857.out</code>). You can use commands such as <code>cat</code>to 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.

Below is an example of steps described above: <syntaxhighlight lang="shell">
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 44572045

zhuofei@ss-sub4 VSCode_tunnel$ sq --me
JOBID NAME PARTITION USER NODES CPUS MIN_MEMORY PRIORITY TIME TIME_LIMIT STATE NODELIST(REASON)
44572045 code_tunnel gpu_p zhuofei 1 4 32G 996 0:02 4:00:00 RUNNING ra8-8
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file first time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- VSCode tunnel is requesting GitHub device authentication ---
# --- User must open the URL and enter the code to authorize ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file second time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication prompt may still appear until completed ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

# --- VS Code Server initialization message ---
*
* 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 is ready and provides a browser access link ---
Open this link in your browser https://vscode.dev/tunnel/vscode-tunnel-0416/scratch/zhuofei/VSCode_tunnel
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file third time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication message may still be shown in log ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

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

# --- Browser access link (use this on local machine) ---
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-17 16:13:13] info [tunnels::connections::relay_tunnel_host] Opened new client on channel 2

# --- Internal SSH handshake between tunnel components ---
[2026-04-17 16:13:13] info [russh::server] wrote id
[2026-04-17 16:13:13] info [russh::server] read other id

# --- Tunnel session is now active ---
[2026-04-17 16:13:13] info [russh::server] session is running

# --- VS Code checks for existing server instance ---
[2026-04-17 16:13:15] info [rpc.0] Checking /home/zhuofei/.code_tunnel/servers/.../log.txt and pid.txt for a running server...

# --- No running server found, starting a new one ---
[2026-04-17 16:13:15] info [rpc.0] Starting server...

# --- VS Code Server successfully started ---
[2026-04-17 16:13:15] info [rpc.0] Server started

# --- Job script finished, tunnel continues running in background ---
zhuofei@ss-sub4 VSCode_tunnel$
</syntaxhighlight>

== 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>code-tunnel</code>
* <code>code-server</code>
* <code>node (server-main.js)</code>
* <code>extensionHost</code>
* <code>fileWatcher</code>
* <code>ptyHost</code>

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 [[OnDemand|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) (To be completed ZH.20260416 4:49PM) ===
Example on compute node:

Processes include:

* VSCode server
* Node.js services
* Extension hosts
* Terminal backend

Resource usage example:

* CPU: low but persistent
* Memory: non-trivial
* GPU: allocated but may be idle
* Processes: <code>code-tunnel</code>, multiple <code>node</code>

----

Across all login nodes (<code>ss-sub1</code>–<code>ss-sub4</code>):

==== Result ====
* No VSCode backend processes present
* Only Slurm launcher processes visible
* No persistent services running

==== Interpretation ====
VSCode workload is fully isolated to compute node

Login nodes remain clean and responsive
----

*

----

== Extension Behavior ==

==== Before Python Extension ====
User extensions:

* Minimal (e.g., Copilot)

Server extensions:

* Built-in only

----

==== After Python Extension Installation ====
New extension appears:

==== Key Points ====
* User extensions → <code>~/.vscode-server/extensions/</code>
* Built-in extensions → server directory
* Server directory remains unchanged

----

=== HPC Implications ===

==== Storage ====
* Extensions stored in home directory
* Can grow over time

==== Performance ====
Installing extensions (e.g., Python) adds:

* Language servers
* Background indexing
* Additional CPU/memory usage

----

== Best Practices ==
* Always run inside a Slurm allocation
* Never run VSCode on login nodes
* Use <code>/scratch</code> for active work
* Install only necessary extensions
* Clean unused extensions periodically

----

== Advantages of This Workflow ==
* Prevents login node overload
* Enables GPU-based development
* Supports AI/LLM workflows
* Works entirely in browser
* Scales cleanly across users

----

== Key Takeaway ==
<blockquote>VSCode is a distributed, multi-process system.

It must be treated like a compute workload—not a simple SSH tool.</blockquote>
----

== Final Note ==
This workflow is strongly recommended for:

* AI / LLM workloads
* GPU-based development
* Heavy interactive coding sessions

Visual Studio Code SSH

2026-04-17T20:26:15Z

Moses: /* Step-by-Step Workflow in a batch GPU Job */

==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 ([[OnDemand|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 [https://code.visualstudio.com/download 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.

[[File:Vscode_activity_bar.png | frameless]]

----

====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 [https://code.visualstudio.com/docs/editor/intellisense#:~:text=IntelliSense%20is%20a%20general%20term,%2C%20and%20%22code%20hinting.%22 IntelliSense] for Python.

[[File:Vscode_extensions.png | 400px | frameless]]

----

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.

[[File:Vscode_ssh_extension.png | 600px | frameless]]

----

====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.

[[File:Vscode_installed.png |700x700px| frameless]]

----

==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.

[[File:Vscode_sshbutton.png | frameless]]

----

====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...".

[[File:Vscode_connection_options.png | 600px | frameless]]

----

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

[[File:Vscode_add_new_ssh_host.png | 600px | frameless]]
[[File:Vscode_connection.png | 600px | frameless]]

----

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

[[File:Vscode_sshconfig.png | 600px | frameless]]

----

====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.

[[File:Vscode_chooseconnection.png | 600px | frameless]]
[[File:Vscode_password.png | 600px | frameless]]
[[File:Vscode_duo.png | 600px | frameless]]

----

====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.

[[File:Vscode_explorer.png | 600px | frameless]]

----

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.

[[File:Vscode_opendir.png |700x700px| frameless]]

----

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.

[[File:Vscode_homedir.png |700x700px| frameless]]

----

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.

[[File:Vscode_add_dir.png |700x700px| frameless]]

----

====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.

[[File:Vscode_terminal.png |714x714px| frameless ]]

== 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
----

=== Step-by-Step Workflow in an Interactive GPU Job ===

==== 1. Allocate a GPU Interactive Job ====
<syntaxhighlight lang="shell">
interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2
</syntaxhighlight>
----

==== 2. Clean Previous VSCode State (Recommended. Note that all VSCode extensions you downloaded will be removed) ====
<syntaxhighlight lang="shell">
rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel
</syntaxhighlight>
----

==== 3. Prepare Working Directory ====
<syntaxhighlight lang="shell">
cd /scratch/$USER/VSCode_tunnel/
</syntaxhighlight>
----

==== 4. Load VSCode Module ====
<syntaxhighlight lang="shell">
ml VSCode/1.88.1
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
code-tunnel tunnel user login --provider github
</syntaxhighlight>Follow the instructions in your local browser:

* Open <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code, for example, 15C1-6D7C
* Authorize access[[File:Vscode-tunnel-1.png|thumb|Open <nowiki>https://github.com/login/device</nowiki>|none|600x600px]][[File:Vscode-tunnel-2.png|none|thumb|600x600px|Enter the code]][[File:Vscode-tunnel-3.png|none|thumb|Authorize access|513x513px]][[File:Vscode-tunnel-4.png|none|thumb|600x600px|Authorization successful]]
----

==== 6. Start the Tunnel ====
<syntaxhighlight lang="shell">
code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.
[[File:Vscode-tunnel-5.png|none|thumb|1189x1189px|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 <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code generated at this step, for example, E1F9-D7E8
* Authorize access

The VSCode tunnel is now active. Open the provided link in your browser to connect <nowiki>https://vscode.dev/tunnel/</nowiki><tunnel-name>/<full>/<path>/<to>/<your>/<working folder where you started tunnel>

For example:

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

==== 8. Trust Workspace ====
VSCode is now connected through the tunnel (cloud relay).
[[File:Vscode-tunnel-6.png|none|thumb|910x910px|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 (<code>vscode-server-linux-x64.tar.gz</code>) and temporarily store it in <code>/tmp</code>.
* 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:
[[File:Vscode-tunnel-7.png|none|thumb|908x908px|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 ==
Within the working directory of the interactive job described above, you can use a batch job submission script (<code>sub.sh</code>) as shown below:<syntaxhighlight lang="shell">
#!/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

</syntaxhighlight>'''Note:''' You can load additional compatible central modules in your batch job submission script. Any modules loaded there will be configured and available within your VSCode tunnel working environment.

You can then submit the job to the cluster using:<syntaxhighlight lang="shell">
sbatch sub.sh
</syntaxhighlight>Once the job starts running, monitor the job’s standard output log file (e.g., <code>log.44568857.out</code>). You can use commands such as <code>cat</code>to 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.

Below is an example of steps described above: <syntaxhighlight lang="shell">
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 44572045

zhuofei@ss-sub4 VSCode_tunnel$ sq --me
JOBID NAME PARTITION USER NODES CPUS MIN_MEMORY PRIORITY TIME TIME_LIMIT STATE NODELIST(REASON)
44572045 code_tunnel gpu_p zhuofei 1 4 32G 996 0:02 4:00:00 RUNNING ra8-8
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file first time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- VSCode tunnel is requesting GitHub device authentication ---
# --- User must open the URL and enter the code to authorize ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file second time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication prompt may still appear until completed ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

# --- VS Code Server initialization message ---
*
* 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 is ready and provides a browser access link ---
Open this link in your browser https://vscode.dev/tunnel/vscode-tunnel-0416/scratch/zhuofei/VSCode_tunnel
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file third time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication message may still be shown in log ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

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

# --- Browser access link (use this on local machine) ---
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-17 16:13:13] info [tunnels::connections::relay_tunnel_host] Opened new client on channel 2

# --- Internal SSH handshake between tunnel components ---
[2026-04-17 16:13:13] info [russh::server] wrote id
[2026-04-17 16:13:13] info [russh::server] read other id

# --- Tunnel session is now active ---
[2026-04-17 16:13:13] info [russh::server] session is running

# --- VS Code checks for existing server instance ---
[2026-04-17 16:13:15] info [rpc.0] Checking /home/zhuofei/.code_tunnel/servers/.../log.txt and pid.txt for a running server...

# --- No running server found, starting a new one ---
[2026-04-17 16:13:15] info [rpc.0] Starting server...

# --- VS Code Server successfully started ---
[2026-04-17 16:13:15] info [rpc.0] Server started

# --- Job script finished, tunnel continues running in background ---
zhuofei@ss-sub4 VSCode_tunnel$
</syntaxhighlight>

== 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>code-tunnel</code>
* <code>code-server</code>
* <code>node (server-main.js)</code>
* <code>extensionHost</code>
* <code>fileWatcher</code>
* <code>ptyHost</code>

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 [[OnDemand|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) (To be completed ZH.20260416 4:49PM) ===
Example on compute node:

Processes include:

* VSCode server
* Node.js services
* Extension hosts
* Terminal backend

Resource usage example:

* CPU: low but persistent
* Memory: non-trivial
* GPU: allocated but may be idle
* Processes: <code>code-tunnel</code>, multiple <code>node</code>

----

Across all login nodes (<code>ss-sub1</code>–<code>ss-sub4</code>):

==== Result ====
* No VSCode backend processes present
* Only Slurm launcher processes visible
* No persistent services running

==== Interpretation ====
VSCode workload is fully isolated to compute node

Login nodes remain clean and responsive
----

*

----

== Extension Behavior ==

==== Before Python Extension ====
User extensions:

* Minimal (e.g., Copilot)

Server extensions:

* Built-in only

----

==== After Python Extension Installation ====
New extension appears:

==== Key Points ====
* User extensions → <code>~/.vscode-server/extensions/</code>
* Built-in extensions → server directory
* Server directory remains unchanged

----

=== HPC Implications ===

==== Storage ====
* Extensions stored in home directory
* Can grow over time

==== Performance ====
Installing extensions (e.g., Python) adds:

* Language servers
* Background indexing
* Additional CPU/memory usage

----

== Best Practices ==
* Always run inside a Slurm allocation
* Never run VSCode on login nodes
* Use <code>/scratch</code> for active work
* Install only necessary extensions
* Clean unused extensions periodically

----

== Advantages of This Workflow ==
* Prevents login node overload
* Enables GPU-based development
* Supports AI/LLM workflows
* Works entirely in browser
* Scales cleanly across users

----

== Key Takeaway ==
<blockquote>VSCode is a distributed, multi-process system.

It must be treated like a compute workload—not a simple SSH tool.</blockquote>
----

== Final Note ==
This workflow is strongly recommended for:

* AI / LLM workloads
* GPU-based development
* Heavy interactive coding sessions

Visual Studio Code SSH

2026-04-17T20:24:57Z

Moses: /* Step-by-Step Workflow in a batch GPU Job */

==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 ([[OnDemand|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 [https://code.visualstudio.com/download 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.

[[File:Vscode_activity_bar.png | frameless]]

----

====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 [https://code.visualstudio.com/docs/editor/intellisense#:~:text=IntelliSense%20is%20a%20general%20term,%2C%20and%20%22code%20hinting.%22 IntelliSense] for Python.

[[File:Vscode_extensions.png | 400px | frameless]]

----

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.

[[File:Vscode_ssh_extension.png | 600px | frameless]]

----

====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.

[[File:Vscode_installed.png |700x700px| frameless]]

----

==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.

[[File:Vscode_sshbutton.png | frameless]]

----

====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...".

[[File:Vscode_connection_options.png | 600px | frameless]]

----

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

[[File:Vscode_add_new_ssh_host.png | 600px | frameless]]
[[File:Vscode_connection.png | 600px | frameless]]

----

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

[[File:Vscode_sshconfig.png | 600px | frameless]]

----

====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.

[[File:Vscode_chooseconnection.png | 600px | frameless]]
[[File:Vscode_password.png | 600px | frameless]]
[[File:Vscode_duo.png | 600px | frameless]]

----

====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.

[[File:Vscode_explorer.png | 600px | frameless]]

----

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.

[[File:Vscode_opendir.png |700x700px| frameless]]

----

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.

[[File:Vscode_homedir.png |700x700px| frameless]]

----

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.

[[File:Vscode_add_dir.png |700x700px| frameless]]

----

====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.

[[File:Vscode_terminal.png |714x714px| frameless ]]

== 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
----

=== Step-by-Step Workflow in an Interactive GPU Job ===

==== 1. Allocate a GPU Interactive Job ====
<syntaxhighlight lang="shell">
interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2
</syntaxhighlight>
----

==== 2. Clean Previous VSCode State (Recommended. Note that all VSCode extensions you downloaded will be removed) ====
<syntaxhighlight lang="shell">
rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel
</syntaxhighlight>
----

==== 3. Prepare Working Directory ====
<syntaxhighlight lang="shell">
cd /scratch/$USER/VSCode_tunnel/
</syntaxhighlight>
----

==== 4. Load VSCode Module ====
<syntaxhighlight lang="shell">
ml VSCode/1.88.1
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
code-tunnel tunnel user login --provider github
</syntaxhighlight>Follow the instructions in your local browser:

* Open <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code, for example, 15C1-6D7C
* Authorize access[[File:Vscode-tunnel-1.png|thumb|Open <nowiki>https://github.com/login/device</nowiki>|none|600x600px]][[File:Vscode-tunnel-2.png|none|thumb|600x600px|Enter the code]][[File:Vscode-tunnel-3.png|none|thumb|Authorize access|513x513px]][[File:Vscode-tunnel-4.png|none|thumb|600x600px|Authorization successful]]
----

==== 6. Start the Tunnel ====
<syntaxhighlight lang="shell">
code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.
[[File:Vscode-tunnel-5.png|none|thumb|1189x1189px|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 <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code generated at this step, for example, E1F9-D7E8
* Authorize access

The VSCode tunnel is now active. Open the provided link in your browser to connect <nowiki>https://vscode.dev/tunnel/</nowiki><tunnel-name>/<full>/<path>/<to>/<your>/<working folder where you started tunnel>

For example:

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

==== 8. Trust Workspace ====
VSCode is now connected through the tunnel (cloud relay).
[[File:Vscode-tunnel-6.png|none|thumb|910x910px|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 (<code>vscode-server-linux-x64.tar.gz</code>) and temporarily store it in <code>/tmp</code>.
* 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:
[[File:Vscode-tunnel-7.png|none|thumb|908x908px|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 ==
Within the working directory of the interactive job described above, you can use a batch job submission script (<code>sub.sh</code>) as shown below:<syntaxhighlight lang="shell">
#!/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

</syntaxhighlight>'''Note:''' You can load additional compatible central modules in your batch job submission script. Any modules loaded there will be configured and available within your VSCode tunnel working environment.

You can then submit the job to the cluster using:<syntaxhighlight lang="shell">
sbatch sub.sh
</syntaxhighlight>Once the job starts running, monitor the job’s standard output log file (e.g., <code>log.44568857.out</code>). You can use commands such as <code>cat</code>to 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.

Below is an example of steps described above: <syntaxhighlight lang="shell">
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 44572045

zhuofei@ss-sub4 VSCode_tunnel$ sq --me
JOBID NAME PARTITION USER NODES CPUS MIN_MEMORY PRIORITY TIME TIME_LIMIT STATE NODELIST(REASON)
44572045 code_tunnel gpu_p zhuofei 1 4 32G 996 0:02 4:00:00 RUNNING ra8-8
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file first time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- VSCode tunnel is requesting GitHub device authentication ---
# --- User must open the URL and enter the code to authorize ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file second time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication prompt may still appear until completed ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

# --- VS Code Server initialization message ---
*
* 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 is ready and provides a browser access link ---
Open this link in your browser https://vscode.dev/tunnel/vscode-tunnel-0416/scratch/zhuofei/VSCode_tunnel
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file third time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication message may still be shown in log ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

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

# --- Browser access link (use this on local machine) ---
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-17 16:13:13] info [tunnels::connections::relay_tunnel_host] Opened new client on channel 2

# --- Internal SSH handshake between tunnel components ---
[2026-04-17 16:13:13] info [russh::server] wrote id
[2026-04-17 16:13:13] info [russh::server] read other id

# --- Tunnel session is now active ---
[2026-04-17 16:13:13] info [russh::server] session is running

# --- VS Code checks for existing server instance ---
[2026-04-17 16:13:15] info [rpc.0] Checking /home/zhuofei/.code_tunnel/servers/.../log.txt and pid.txt for a running server...

# --- No running server found, starting a new one ---
[2026-04-17 16:13:15] info [rpc.0] Starting server...

# --- VS Code Server successfully started ---
[2026-04-17 16:13:15] info [rpc.0] Server started

# --- Job script finished, tunnel continues running in background ---
zhuofei@ss-sub4 VSCode_tunnel$
</syntaxhighlight>

== 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>code-tunnel</code>
* <code>code-server</code>
* <code>node (server-main.js)</code>
* <code>extensionHost</code>
* <code>fileWatcher</code>
* <code>ptyHost</code>

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 [[OnDemand|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) (To be completed ZH.20260416 4:49PM) ===
Example on compute node:

Processes include:

* VSCode server
* Node.js services
* Extension hosts
* Terminal backend

Resource usage example:

* CPU: low but persistent
* Memory: non-trivial
* GPU: allocated but may be idle
* Processes: <code>code-tunnel</code>, multiple <code>node</code>

----

Across all login nodes (<code>ss-sub1</code>–<code>ss-sub4</code>):

==== Result ====
* No VSCode backend processes present
* Only Slurm launcher processes visible
* No persistent services running

==== Interpretation ====
VSCode workload is fully isolated to compute node

Login nodes remain clean and responsive
----

*

----

== Extension Behavior ==

==== Before Python Extension ====
User extensions:

* Minimal (e.g., Copilot)

Server extensions:

* Built-in only

----

==== After Python Extension Installation ====
New extension appears:

==== Key Points ====
* User extensions → <code>~/.vscode-server/extensions/</code>
* Built-in extensions → server directory
* Server directory remains unchanged

----

=== HPC Implications ===

==== Storage ====
* Extensions stored in home directory
* Can grow over time

==== Performance ====
Installing extensions (e.g., Python) adds:

* Language servers
* Background indexing
* Additional CPU/memory usage

----

== Best Practices ==
* Always run inside a Slurm allocation
* Never run VSCode on login nodes
* Use <code>/scratch</code> for active work
* Install only necessary extensions
* Clean unused extensions periodically

----

== Advantages of This Workflow ==
* Prevents login node overload
* Enables GPU-based development
* Supports AI/LLM workflows
* Works entirely in browser
* Scales cleanly across users

----

== Key Takeaway ==
<blockquote>VSCode is a distributed, multi-process system.

It must be treated like a compute workload—not a simple SSH tool.</blockquote>
----

== Final Note ==
This workflow is strongly recommended for:

* AI / LLM workloads
* GPU-based development
* Heavy interactive coding sessions

Visual Studio Code SSH

2026-04-17T20:23:56Z

Moses:

==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 ([[OnDemand|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 [https://code.visualstudio.com/download 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.

[[File:Vscode_activity_bar.png | frameless]]

----

====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 [https://code.visualstudio.com/docs/editor/intellisense#:~:text=IntelliSense%20is%20a%20general%20term,%2C%20and%20%22code%20hinting.%22 IntelliSense] for Python.

[[File:Vscode_extensions.png | 400px | frameless]]

----

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.

[[File:Vscode_ssh_extension.png | 600px | frameless]]

----

====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.

[[File:Vscode_installed.png |700x700px| frameless]]

----

==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.

[[File:Vscode_sshbutton.png | frameless]]

----

====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...".

[[File:Vscode_connection_options.png | 600px | frameless]]

----

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

[[File:Vscode_add_new_ssh_host.png | 600px | frameless]]
[[File:Vscode_connection.png | 600px | frameless]]

----

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

[[File:Vscode_sshconfig.png | 600px | frameless]]

----

====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.

[[File:Vscode_chooseconnection.png | 600px | frameless]]
[[File:Vscode_password.png | 600px | frameless]]
[[File:Vscode_duo.png | 600px | frameless]]

----

====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.

[[File:Vscode_explorer.png | 600px | frameless]]

----

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.

[[File:Vscode_opendir.png |700x700px| frameless]]

----

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.

[[File:Vscode_homedir.png |700x700px| frameless]]

----

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.

[[File:Vscode_add_dir.png |700x700px| frameless]]

----

====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.

[[File:Vscode_terminal.png |714x714px| frameless ]]

== 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
----

=== Step-by-Step Workflow in an Interactive GPU Job ===

==== 1. Allocate a GPU Interactive Job ====
<syntaxhighlight lang="shell">
interact -c 20 --mem 80gb -p gpu_p --gres gpu:L4:2
</syntaxhighlight>
----

==== 2. Clean Previous VSCode State (Recommended. Note that all VSCode extensions you downloaded will be removed) ====
<syntaxhighlight lang="shell">
rm -rf ~/.vscode
rm -rf ~/.vscode-server
rm -rf ~/.code_tunnel
</syntaxhighlight>
----

==== 3. Prepare Working Directory ====
<syntaxhighlight lang="shell">
cd /scratch/$USER/VSCode_tunnel/
</syntaxhighlight>
----

==== 4. Load VSCode Module ====
<syntaxhighlight lang="shell">
ml VSCode/1.88.1
</syntaxhighlight>'''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) ====
<syntaxhighlight lang="shell">
code-tunnel tunnel user login --provider github
</syntaxhighlight>Follow the instructions in your local browser:

* Open <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code, for example, 15C1-6D7C
* Authorize access[[File:Vscode-tunnel-1.png|thumb|Open <nowiki>https://github.com/login/device</nowiki>|none|600x600px]][[File:Vscode-tunnel-2.png|none|thumb|600x600px|Enter the code]][[File:Vscode-tunnel-3.png|none|thumb|Authorize access|513x513px]][[File:Vscode-tunnel-4.png|none|thumb|600x600px|Authorization successful]]
----

==== 6. Start the Tunnel ====
<syntaxhighlight lang="shell">
code-tunnel tunnel --name <your vscode tunnel name> --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
code-tunnel tunnel --name vscode-tunnel-0416 --cli-data-dir ~/.code_tunnel --accept-server-license-terms
</syntaxhighlight>You will be asked how would you like to log in to VSCode (cloud relay). Choose GitHub Account.
[[File:Vscode-tunnel-5.png|none|thumb|1189x1189px|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 <nowiki>https://github.com/login/device</nowiki> , choose to use your personal GitHub account.
* Enter the code generated at this step, for example, E1F9-D7E8
* Authorize access

The VSCode tunnel is now active. Open the provided link in your browser to connect <nowiki>https://vscode.dev/tunnel/</nowiki><tunnel-name>/<full>/<path>/<to>/<your>/<working folder where you started tunnel>

For example:

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

==== 8. Trust Workspace ====
VSCode is now connected through the tunnel (cloud relay).
[[File:Vscode-tunnel-6.png|none|thumb|910x910px|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 (<code>vscode-server-linux-x64.tar.gz</code>) and temporarily store it in <code>/tmp</code>.
* 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:
[[File:Vscode-tunnel-7.png|none|thumb|908x908px|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 ==
Within the working directory of the interactive job described above, you can use a batch job submission script (<code>sub.sh</code>) as shown below:<syntaxhighlight lang="shell">
#!/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

</syntaxhighlight>'''Note:''' You can load additional compatible central modules in your batch job submission script. Any modules loaded there will be configured and available within your VSCode tunnel working environment.

You can then submit the job to the cluster using:<syntaxhighlight lang="shell">
sbatch sub.sh
</syntaxhighlight>Once the job starts running, monitor the job’s standard output log file (e.g., <code>log.44568857.out</code>). You can use commands such as <code>cat</code>to 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.

Below is an example of steps described above: <syntaxhighlight lang="shell">
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 44572045

zhuofei@ss-sub4 VSCode_tunnel$ sq --me
JOBID NAME PARTITION USER NODES CPUS MIN_MEMORY PRIORITY TIME TIME_LIMIT STATE NODELIST(REASON)
44572045 code_tunnel gpu_p zhuofei 1 4 32G 996 0:02 4:00:00 RUNNING ra8-8
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file first time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- VSCode tunnel is requesting GitHub device authentication ---
# --- User must open the URL and enter the code to authorize ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file second time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication prompt may still appear until completed ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

# --- VS Code Server initialization message ---
*
* 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 is ready and provides a browser access link ---
Open this link in your browser https://vscode.dev/tunnel/vscode-tunnel-0416/scratch/zhuofei/VSCode_tunnel
</syntaxhighlight><syntaxhighlight lang="shell">
# Open the log file third time
zhuofei@ss-sub4 VSCode_tunnel$ cat log.44572045.out

# --- Authentication message may still be shown in log ---
To grant access to the server, please log into https://github.com/login/device and use code B578-CB62

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

# --- Browser access link (use this on local machine) ---
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-17 16:13:13] info [tunnels::connections::relay_tunnel_host] Opened new client on channel 2

# --- Internal SSH handshake between tunnel components ---
[2026-04-17 16:13:13] info [russh::server] wrote id
[2026-04-17 16:13:13] info [russh::server] read other id

# --- Tunnel session is now active ---
[2026-04-17 16:13:13] info [russh::server] session is running

# --- VS Code checks for existing server instance ---
[2026-04-17 16:13:15] info [rpc.0] Checking /home/zhuofei/.code_tunnel/servers/.../log.txt and pid.txt for a running server...

# --- No running server found, starting a new one ---
[2026-04-17 16:13:15] info [rpc.0] Starting server...

# --- VS Code Server successfully started ---
[2026-04-17 16:13:15] info [rpc.0] Server started

# --- Job script finished, tunnel continues running in background ---
zhuofei@ss-sub4 VSCode_tunnel$
</syntaxhighlight>

== 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>code-tunnel</code>
* <code>code-server</code>
* <code>node (server-main.js)</code>
* <code>extensionHost</code>
* <code>fileWatcher</code>
* <code>ptyHost</code>

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 [[OnDemand|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) (To be completed ZH.20260416 4:49PM) ===
Example on compute node:

Processes include:

* VSCode server
* Node.js services
* Extension hosts
* Terminal backend

Resource usage example:

* CPU: low but persistent
* Memory: non-trivial
* GPU: allocated but may be idle
* Processes: <code>code-tunnel</code>, multiple <code>node</code>

----

Across all login nodes (<code>ss-sub1</code>–<code>ss-sub4</code>):

==== Result ====
* No VSCode backend processes present
* Only Slurm launcher processes visible
* No persistent services running

==== Interpretation ====
VSCode workload is fully isolated to compute node

Login nodes remain clean and responsive
----

*

----

== Extension Behavior ==

==== Before Python Extension ====
User extensions:

* Minimal (e.g., Copilot)

Server extensions:

* Built-in only

----

==== After Python Extension Installation ====
New extension appears:

==== Key Points ====
* User extensions → <code>~/.vscode-server/extensions/</code>
* Built-in extensions → server directory
* Server directory remains unchanged

----

=== HPC Implications ===

==== Storage ====
* Extensions stored in home directory
* Can grow over time

==== Performance ====
Installing extensions (e.g., Python) adds:

* Language servers
* Background indexing
* Additional CPU/memory usage

----

== Best Practices ==
* Always run inside a Slurm allocation
* Never run VSCode on login nodes
* Use <code>/scratch</code> for active work
* Install only necessary extensions
* Clean unused extensions periodically

----

== Advantages of This Workflow ==
* Prevents login node overload
* Enables GPU-based development
* Supports AI/LLM workflows
* Works entirely in browser
* Scales cleanly across users

----

== Key Takeaway ==
<blockquote>VSCode is a distributed, multi-process system.

It must be treated like a compute workload—not a simple SSH tool.</blockquote>
----

== Final Note ==
This workflow is strongly recommended for:

* AI / LLM workloads
* GPU-based development
* Heavy interactive coding sessions

Visual Studio Code SSH

2026-04-17T18:38:30Z

Moses: /* Step-by-Step Workflow in a batch GPU Job */

Visual Studio Code SSH

2026-04-17T18:31:50Z

Moses: /* Step-by-Step Workflow in a batch GPU Job */

Visual Studio Code SSH

2026-04-17T13:47:53Z

Moses: /* Step-by-Step Workflow in a batch GPU Job */

Visual Studio Code SSH

2026-04-17T13:45:45Z

Moses: /* Step-by-Step Workflow in a batch GPU Job */

Visual Studio Code SSH

2026-04-17T13:44:05Z

Moses: /* Step-by-Step Workflow in a batch GPU Job */

Visual Studio Code SSH

2026-04-17T13:42:20Z

Moses: /* Step-by-Step Workflow in a batch GPU Job */

Visual Studio Code SSH

2026-04-17T13:41:26Z

Moses: /* Step-by-Step Workflow in a batch GPU Job */

Visual Studio Code SSH

2026-04-17T13:36:20Z

Moses: /* Interpretation */

Visual Studio Code SSH

2026-04-17T13:35:54Z

Moses: /* What Happens Under the Hood When Using VSCode */