Skip to content

VSCode Remote Tunnels

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 overview, 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 VSCode page, but note that there are some important differences for use on HiPerGator.

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).
  • HiPerGator provides a powerful compute environment with thousands of cores, petabytes of storage, and powerful GPUs.
  • Things to consider:
    • The use of VS Code remote ssh extension is discouraged as you can accidentally end up running scripts on the login servers and have your account suspended.
    • 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 vscode environment module updates can lag behind the rapid vscode release schedule.
  • With VS Code Remote Development, 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/. 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

  • Do not use the VSCode Remote SSH extension!
  • All remote access for VSCode should be done to scheduled jobs running on HiPerGator using the Remote Tunnels extension. This ensures your job stays within the resources requested from the SLURM scheduler.

Install VSCode in your ~/bin folder

While UFIT Research Computing does maintain a module for VSCode, the application is updated on a rapid cycle and our 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/

First Run: Launch a development session and start VSCode tunnel

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

  1. Get a development session: srundev
  2. Start VSCode Server: code tunnel
  3. You can select either GitHub or Microsoft accounts to authenticate your sessions.
  4. You will 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.
  5. If you want to test the connection, you can (though the development session is only 10 minutes unless you specify more time).
  6. Use the "Ctrl-C" key combination to stop the code tunnel process.
  7. Exit the development session: exit

For Daily Use

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

  • Log into HiPerGator
  • Submit a tunnel job in one of several ways
    • Submit a preset script using one of the examples below.
    • Submit an interactive development session.

Sample 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=gpu
#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 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

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

For an Interactive Method

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

  1. Start a development 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, an A100 GPU for 1 hour: srun -c 4 --mem 15gb -p gpu --gres gpu:a100:1 -t 60 --pty bash -i
  2. For Jupyter notebooks, it is important to:
    • 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

Connect to the Tunnel

  • 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).

An example output is below, showing the URL and code to use to authenticate the session. Once that is done, the code tunnel session will provide the connection URL to connect in your browser, or be ready for connection from within your desktop VSCode application using the Remote Tunnel extension.

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
  1. Go either to the link shown in the above example or go to https://vscode.dev/ and click on the 'Connect to tunnel' button.
  2. Authenticate with your GitHub account using the above code.
  3. Connect to the URL provided in your browser.
  4. Once you open VS Code in the browser, open the command palette (ctrl+shift+p) and select the appropriate Jupyter Interpreter.
  5. Code away!

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 of the value of LOADEDMODULES

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

module load tensorflow/2.7.0

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