Skip to content

VSCode Remote Tunnels

Introduction

Why might you want to do this?

  • VS Code is a nice IDE with many great features, including GitHub Copilot (which most UF users should be able to access for free--via either student or faculty/staff GitHub Education plans).
  • With a remote tunnel you can access HiPerGator's powerful compute environment with thousands of cores, petabytes of storage, and powerful GPUs.
  • With VS Code Remote - Tunnel, you can startup the server within an interactive job with whatever resources you have requested and connect to it in your web browser from https://vscode.dev/ or your own local instance. There are no MFA issues, and you can install your desired extensions, connect to GitHub Copilot, and run and debug your code easily!
  • These videos may be helpful:

!!! warning Things to consider:

* Do not use the VSCode Remote - SSH extension!

* The use of [VS Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) Remote - SSH extension is discouraged as you can accidentally end up running scripts on the login servers and have your account suspended (see warning below).

* Even if you tunnel into the server running your job, your VSCode session is outside of the resources assigned to your job, and your account may be 
suspended.

* Running VS Code on HiPerGator through OOD is kind of slow and limiting as there have been reports of clipboard behavior being inconsistent and the vscode environment module updates may be behind the rapid vscode release schedule.

* All remote access for VSCode should be done to scheduled jobs running on HiPerGator using the [Remote Tunnels](https://marketplace.visualstudio.com/items?itemName=ms-vscode.remote-server) extension. This ensures your job stays within the resources requested from the SLURM scheduler.
From the Developing with Remote Tunnels page:

The Visual Studio Code Remote - Tunnels extension lets you connect to a remote machine, like a desktop PC or virtual machine (VM) [or a session running on HiPerGator], via a secure tunnel. You can connect to that machine from a VS Code client anywhere, without the requirement of SSH.

Tunneling securely transmits data from one network to another via Microsoft dev tunnels.

This can eliminate the need for source code to be on your VS Code client machine since the extension runs commands and other extensions directly on the remote machine.

Remote Tunnels architecture diagram, from https://code.visualstudio.com/docs/remote/tunnels

VS Code can provide a local-quality development experience - including full IntelliSense (completions), code navigation, and debugging - regardless of where your code is hosted.

You are encouraged to continue reading about VSCode Remote Tunnels on the VS Code page, but note that there are some important differences for use on HiPerGator.

Getting Started

Install VSCode

While UFIT Research Computing does maintain a module for VSCode ($ module load vscode), the application is updated on a rapid cycle and HPG version often falls behind the latest version, sometimes causing issues. For this reason, we recommend installing your own version and allowing it to update periodically.

If you don't have a bin directory in your home folder on HiPerGator, create it with mkdir ~/bin

  1. Download the x64 CLI for Linux package from the VSCode Downloads Site. You can use this command to download it on HiPerGator:

    curl -Lk 'https://code.visualstudio.com/sha/download?build=stable&os=cli-alpine-x64' --output vscode_cli.tar.gz

  2. Extract the tar.gz file and move the binary to ~/bin: 

        tar -xvf vscode_cli.tar.gz
    mv code ~/bin/

Launch a Compute/Development Session and Start VSCode Tunnel

See this page for information on development sessions, but something like this should work:

The easiest way to get a quick HPG shell is through OOD: HPG Shell Access

  1. Get a compute session: example: srun -c 4 --mem 15gb -p gpu --gres gpu:1 -t 60 --pty bash -i, hpg-dev partition, or one of the sample scripts below.
  2. From the compute node (not the login node), start VSCode Server: code tunnel
  3. You can select either GitHub or Microsoft accounts to authenticate your sessions.
  4. You may be asked to name your tunnel. The default name is the name of the current server, which is not too helpful. Name the tunnel something like "hipergator". Names will display in all lowercase. Feel free to rename your sessions with code tunnel rename new-tunnel-name.

Connect to Your Tunnel

Now that VSCode is setup, it should be relatively easy to use daily. For the most part, the process is:

  1. Start a HiPerGator Shell.
  2. Submit a tunnel job in one of several ways (if no tunnels are currently running).
    • Submit a preset script using one of the examples below.
    • Submit an interactive compute session.
    • Once your job starts, look in the job log for authentication and connection information. For example: cat slurm-JOBID.out (replacing the JOBID with the number for your job). Run squeuemine to find more information about your jobs.
Click to expand to see sample output from a job with the connection information 
[username@login10 ~]$ cat slurm-49810430.out 
c0709a-s12.ufhpc
Thu Nov 14 11:21:00 EST 2024
/home/username
*
* 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).
*
[2024-11-14 11:21:02] 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 F280-C346

Open this link in your browser [https://vscode.dev/tunnel/hipergator](https://vscode.dev/tunnel/hipergator)
  1. Connect to the Tunnel. Once you authenticate, you can connect to your tunnel from your browser using the link provided: https://vscode.dev/tunnel/hipergator.
    • You can also authenticate to your GitHub/MS account to tunnel from your local VS Code instance.
    • Alternatively, a VS Code Chrome browser app is available when using your Chrome browser window.
  2. Once you open VS Code, open the command palette (ctrl+shift+p) and select the appropriate Python interpreter, in case you're working on a custom environmnet hosted on HPG.
  3. Code away!

Shut Down When Done!

Remember that this session will continue to run, using your group's resources, until the job runs out of time or is canceled. If you are done before the time runs out, cancel the session using the JOBID number: scancel 12345678. Alternatively, if you're in the compute node interactively, use the "Ctrl-C" key combination to stop the code tunnel process and exit the development session: exit or "Ctrl-D".

Sample Slurm Scripts for Launching Code Tunnel

See below for how to add UFIT-RC managed kernels to your list of available environments in VSCode Tunnels.

Click to expand to see an example CPU-based job script 
#!/bin/bash
#SBATCH --job-name=vscode
#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=2
#SBATCH --mem=8gb
#SBATCH --time=02:00:00 # example 2 hrs

hostname;date;pwd
export XDG_RUNTIME_DIR=${SLURM_TMPDIR}

# Uncomment the module load line if you want to load the module
# for the UFIT-RC managed install of vscode. Generally not recommended
# module load vscode

# Load the module fo Jupyter.
# Comment out the next line with '#' if not using Jupyter Notebooks
module load jupyter

# For either the HPG or personal install of vscode
code tunnel
Click to expand to see an example GPU-based job script 
#!/bin/bash
#SBATCH --job-name=vscode
#SBATCH --partition=hpg-b200
#SBATCH --gpus=1
#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=2
#SBATCH --mem=8gb
#SBATCH --time=02:00:00 # example 2 hrs

hostname;date;pwd
export XDG_RUNTIME_DIR=${SLURM_TMPDIR}


# Uncomment the module load line if you want to load the module
# for the UFIT-RC managed install of vscode. Generally not recommended
# module load vscode

# Load the module for Jupyter.
# Comment out the next line with '#' if not using Jupyter Notebooks
module load jupyter

# For either the HPG or personal install of vscode
code tunnel

For easiest use, save one or both of these examples in your home directory naming them something like code_tunnel_2c_8g.sbatch to remind you the script asks for two cores and eight GB of RAM; and code_tunnel_GPU_2c_8g.sbatch for the GPU version. Obviously the details of the scripts and names are up to you and what works well for your use.

To submit the script, use the sbatch command: e.g. sbatch code_tunnel_2c_8g.sbatch

Note

Note that it is easy to override the parameters set in the script by passing the same parameter on the command line. So, for example, if you wanted 16GB RAM instead, rather than edit the script, you can use: sbatch --mem=16gb code_tunnel_2c_8g.sbatch

Interactive Slurm Session

Note: srun sessions will end if your network connection to HPG is broken or if you exit.

  1. Start a compute session, requesting GPUs if needed, and other resources for the time you want to work.
    • For example, for a session requesting 4 cores, 15GB of RAM, and a GPU for 1 hour: srun -c 4 --mem 15gb -p gpu --gres gpu:1 -t 60 --pty bash -i
  2. For Jupyter notebooks, it is important to:
    • In the compute node, load Jupyter and the module you need for the kernel you want to use, e.g. for Tensorflow: module load jupyter tensorflow/2.7.0
    • Export the XDG_RUNTIME_DIR to set temp directory (otherwise it tries to use /run/user/, which you can't be written to!): export XDG_RUNTIME_DIR=${SLURM_TMPDIR}
  3. Start VS Code tunnel: code tunnel
    • This can all be done with this line: module load jupyter tensorflow/2.7.0; export XDG_RUNTIME_DIR=${SLURM_TMPDIR}; code tunnel

Adding UFIT-RC Maintained Kernels to you VSCode Tunnel

To have the UFIT-RC maintained kernels be available as options within your VSCode tunnel, you will need to load the appropriate module. It may be easiest to get this information from a Jupyter session. Select the kernel you want. Run the code below in a cell of the notebook:

import os

os.getenv('LOADEDMODULES')

The output will list the loaded modules. In the screenshot below, using the Tensorflow-2.7.0 kernel, you can see that the module tensorflow/2.7.0 is loaded.

Screenshot displaying the input/output to display loaded modules in a JupyterNotebook

To use this kernel in a tunnel, add the following line to the sample scripts above:

module load tensorflow/2.7.0