Skip to content

Connecting With VS Code#

Microsoft Visual Studio Code (VS Code) is a popular tool for development in many programming languages, and may be used on HPC systems. However, there are some caveats to be aware of when running it remotely.

Connecting with VS Code#

To connect to an HPC system with VS Code, install the "Remote - SSH" extension from the Extensions menu.

Press "F1" to open the command bar, and type or search for Remote-SSH: Connect to Host...

You may then enter your HPC username and the address of an HPC system to connect to.

  • To connect to Kestrel from the NREL VPN, enter username@kestrel.hpc.nrel.gov, replacing "username" with your HPC user name.

  • To connect to Kestrel as an external collaborator, enter username@kestrel.nrel.gov, replacing "username" with your HPC user name.

Enter your HPC password (or password and OTP code if external) and you will be connected to a login node. You may open a folder on the remote host to browse your home directory and select files to edit, and so on.

Windows SSH "Corrupted MAC on input" Error

Some people who use Windows 10/11 computers to ssh to Kestrel via Visual Studio Code's SSH extension might receive an error message about a "Corrupted MAC on input" or "message authentication code incorrect." To workaround this issue, you will need to create an ssh config file on your local computer, ~/.ssh/config, with a host entry for Kestrel that specifies a new message authentication code: 

Host kestrel
    HostName kestrel.hpc.nrel.gov
    MACs hmac-sha2-512
This Visual Studio Blog post has further instructions on how to create the ssh configuration file for Windows and VS Code.

Caution About VS Code Processes#

Please be aware that the Remote SSH extension runs processes on the remote host. This includes any extensions or helpers, include language parsers, code analyzers, AI code assistants, and so on. These extensions can take up a considerable amount of CPU and RAM on any remote host that VS Code connects to. Jupyter notebooks loaded through VS Code will also be executed on the remote host and can use excessive CPU and RAM, as well. When the remote host is a shared login node on an HPC system, this can be a considerable drain on the resources of the login node, and cause system slowdowns for all users of that login node.

This problem can be circumvented by using a compute node to run VS Code. This will cost AU, but will allow for full resource usage of CPU and/or RAM.

Kestrel#

Using VS Code on a compute node will require adding an ssh key.

SSH Key Setup#

You may use an existing key pair on your local computer/laptop, or create one with ssh-keygen (adding -t ed25519 is optional, but recommended.)

We recommend choosing a strong passphrase and storing it in a password manager. The passphrase on your key will allow you to log in via ssh, but it is not the same as your HPC account password.

SSH Key Pair Caution

Do not replace the key pair in your Kestrel home directory. These keys are generated when you log into the cluster, and are used by Slurm jobs to communicate between nodes. There is a corresponding public key entry in your cluster home directory ~/.ssh/authorized_keys that must also be left in place.

Reminder About Passwords

Using an SSH key with an SSH agent can remove the need to use a password to SSH to Kestrel. However, not all HPC services (including Lex) use SSH keys. An SSH key does NOT replace your HPC account password. You must maintain a regular HPC account password in accordance with our Appropriate Use Policy and User Account Password Guidelines. Ignoring password expiration date notices will lead to automatic account lockouts, and you will need to contact HPC Support to restore your account.

Once you have a key pair on your local computer, use the ssh-copy-id <username>@kestrel.hpc.nrel.gov command to copy the public portion to Kestrel. This will add your public key to the ~/.ssh/authorized_keys file in your Kestrel home directory. Alternatively, you may manually add the contents of your PUBLIC key file (for example, the contents of ~/.ssh/id_ed25519.pub or ~/.ssh/id_rsa.pub) onto the end of this file. Do not delete the existing entries in these files on Kestrel.

Editing the VS Code SSH Config File#

We will now create a host entry in your local ssh config file to make connecting to Kestrel compute nodes easier.

Use the remote-ssh command to edit your VS Code ssh config file (~/.ssh/config). Add the following:

Host x?00?c*
    ProxyJump <username>@kestrel.hpc.nrel.gov

This create a "wildcard" entry that should match Kestrel compute node names. Any time an ssh command is issued on your computer that matches the wildcard, the ssh connection will "jump" through a Kestrel login node and directly to the compute node.

If your allocation is finished on Kestrel (e.g. at the end of the FY and your allocation will not be continuing to the next) or you otherwise anticipate no further need to use VS Code with Kestrel in this fashion, you may delete this entry from your SSH config file.

Start a Job and Connect VS Code#

SSH to Kestrel as usual (outside of VS Code) and use sbatch or salloc to start a job. (An interactive job with salloc is suggested, using a --time limited to only the expected duration of your working session with VS Code.)

Wait until the job has started running, and take note of the node assigned to the job. Put the terminal aside, but leave the job running.

Now use the Remote-SSH extension in VS Code to Connect to Host... and use the hostname of the node that your job was assigned. For example, <username>@x1000c0s0b0n1.

This should open a new VS Code window that will connect to the compute node automatically. You may begin browsing your home directory and editing files in the VS Code window.