VS Code Remote-SSH for HPC

Welcome!

This workshop teaches you how to use Microsoft VS Code with the Remote-SSH extension to develop and run code on the Pomona College Sagehen HPC cluster. VS Code Remote-SSH provides a full integrated development environment (IDE) experience while working on remote systems, combining the power of a modern editor with direct access to your HPC cluster.

Why take this workshop?

After this workshop, you will be able to:

  • Install and configure VS Code with the Remote-SSH extension
  • Connect securely to the Sagehen HPC cluster using DUO MFA
  • Edit remote files using VS Code’s powerful editor features
  • Use VS Code’s integrated terminal to run SLURM commands and monitor jobs
  • Install and use extensions for Python, R, Jupyter, and Git workflows
  • Understand when VS Code Remote-SSH is the right tool for HPC work

What you’ll need

  • Your own laptop (Windows, Mac, or Linux)
  • A Pomona College HPC account on Sagehen HPC cluster
  • VS Code installed on your local machine
  • SSH access credentials for the cluster
  • DUO MFA enabled on your account (required by Sagehen HPC)
  • 30-45 minutes for the full workshop

Workshop structure

This workshop is organized as follows:

Episode Time Topic
1 15 min + 5 ex Why VS Code Remote-SSH? Comparison with alternatives
2 20 min + 10 ex Installation and configuration on all platforms
3 25 min + 15 ex Connecting to Sagehen with DUO authentication
4 20 min + 10 ex Editing files, creating projects, file management
5 20 min + 15 ex Using the integrated terminal and SLURM commands
6 25 min + 10 ex Adding extensions and customizing your environment

Total teaching time: ~2 hours (plus exercises)

Getting help

If you encounter issues during the workshop:

  • Email:
  • Slack: #hpc-help (Pomona CS Slack)
  • Office hours: See ITS-HPC website for Andrew Wilson’s availability
  • Known issues: See the reference section for common problems and solutions

Before you begin

Please complete the following:

  1. Ensure you have an HPC account: Log into Sagehen HPC cluster documentation to verify your account status
  2. Enable DUO MFA: If you haven’t already, register your device at duo.pomona.edu
  3. Test SSH access: From your terminal, try: ssh <myusername>@sagehen.hpc.pomona.edu (this will confirm your access works)
  4. Download VS Code: From code.visualstudio.com

Ready to get started? Let’s dive into why VS Code is such a powerful tool for HPC work!

Questions or suggestions? Please contact or open an issue on our GitHub repository.

Acknowledgments

Developed by Andrew Wilson, Director of Research Computing and Digital Scholarship at Pomona College, with Andrei Motchenko, who tested, edited and produced screenshots for the workshop series.

Pre-Workshop Requirements

Before attending the workshop, please complete the following steps to ensure everything is working properly.

1. Install VS Code

VS Code is the IDE we’ll use to connect to Sagehen.

  1. Visit code.visualstudio.com
  2. Click “Download for Windows”
  3. Run the installer
  4. Follow the installation wizard (default options are fine)
  5. Launch VS Code when installation completes
  1. Visit code.visualstudio.com
  2. Click “Download for Mac”
  3. Extract the downloaded zip file
  4. Drag “Visual Studio Code.app” to your Applications folder
  5. Open Applications and double-click VS Code to launch it

BASH 

# Install using apt (easiest)
sudo apt update
sudo apt install code

# Or download from VS Code website
# Visit https://code.visualstudio.com and download the .deb file
# Then: sudo dpkg -i code_*.deb

2. Install the Remote-SSH Extension

Once VS Code is installed, add the Remote-SSH extension to enable HPC cluster connections.

  1. Open VS Code
  2. Click the Extensions icon (left sidebar, looks like four squares)
  3. Search for “Remote - SSH”
  4. Find the extension by Microsoft (should be first result)
  5. Click “Install”
  6. Wait for installation to complete

This extension allows VS Code to connect to remote machines via SSH.

3. Generate or Verify SSH Key Pair

SSH keys enable secure passwordless authentication (though DUO MFA is still required).

On Windows (PowerShell):

POWERSHELL 

ssh-keygen -t ed25519 -f $ENV:USERPROFILE\.ssh\id_sagehen
# When prompted for passphrase, press Enter (or set one if desired)

On macOS/Linux:

BASH 

ssh-keygen -t ed25519 -f ~/.ssh/id_sagehen
# When prompted for passphrase, press Enter (or set one if desired)

This creates two files: - id_sagehen (private key - keep secret!) - id_sagehen.pub (public key - copy to server)

If you already have an SSH key pair on your system, you can use it.

Check if you have keys:

On Windows (PowerShell):

POWERSHELL 

ls $ENV:USERPROFILE\.ssh\

On macOS/Linux:

BASH 

ls ~/.ssh/

Look for files like id_ed25519, id_rsa, or similar. If you find them, you can skip key generation.

4. Test SSH Connection to Sagehen HPC

Before the workshop, verify you can log in to the Sagehen HPC cluster.

BASH 

ssh <myusername>@sagehen.hpc.pomona.edu

You will be prompted for: 1. Your Pomona password 2. DUO MFA authentication (choose “send push” or enter code)

Once you connect, you should see the Sagehen prompt. Type exit to disconnect.

If you can’t connect: - Verify your username and password - Confirm your DUO is registered at https://duo.pomona.edu - Contact for help

5. Create or Update SSH Config File

An SSH config file simplifies connecting to Sagehen. Create one on your local machine.

Create the file (if it doesn’t exist):

POWERSHELL 

# Create .ssh directory if needed
New-Item -ItemType Directory -Force -Path $ENV:USERPROFILE\.ssh

# Open config in notepad
notepad $ENV:USERPROFILE\.ssh\config

Add this content (replace your_username with your Pomona username):

Host sagehen
    HostName sagehen.hpc.pomona.edu
    User your_username
    IdentityFile ~/.ssh/id_sagehen
    ServerAliveInterval 300
    ServerAliveCountMax 2

Save the file (Ctrl+S).

Open a terminal and create/edit the config:

BASH 

nano ~/.ssh/config

Add this content (replace your_username with your Pomona username):

Host sagehen
    HostName sagehen.hpc.pomona.edu
    User your_username
    IdentityFile ~/.ssh/id_sagehen
    ServerAliveInterval 300
    ServerAliveCountMax 2

Save: Ctrl+O, Enter, Ctrl+X

Set permissions:

BASH 

chmod 600 ~/.ssh/config
chmod 700 ~/.ssh

6. Test SSH Connection with Config

Now test connecting using the simplified alias:

BASH 

ssh sagehen

You should be able to connect with just one command. Complete the DUO authentication.

7. Optional: Copy SSH Public Key to Server

This step is optional but enables faster authentication (DUO MFA still required).

BASH 

ssh-copy-id -i ~/.ssh/id_sagehen.pub sagehen

On Windows, if ssh-copy-id doesn’t work, use PowerShell:

POWERSHELL 

type $ENV:USERPROFILE\.ssh\id_sagehen.pub | ssh sagehen "cat >> ~/.ssh/authorized_keys"

8. Copy Files to Sagehen HPC (Optional)

You may need to copy files between your computer and Sagehen. Test with a sample file:

BASH 

# Copy local file to Sagehen
scp myfile.txt sagehen:~/

# Copy from Sagehen to local
scp sagehen:~/myfile.txt ./

9. Verify OnDemand Access (Optional)

Sagehen also provides a web-based interface. You can optionally test this at:

https://ondemand.hpc.pomona.edu/

Log in with your Pomona credentials + DUO.

This is useful for file browsing and running interactive jobs, though we’ll focus on VS Code in this workshop.

Troubleshooting Pre-Workshop Issues

“SSH: Connection refused” - Verify hostname: sagehen.hpc.pomona.edu - Check firewall isn’t blocking port 22 - Ensure VPN is connected if required

“Authentication failed” - Double-check username and password - Verify DUO is registered and your phone is nearby - Try request a call instead of entering code

“Remote-SSH extension not appearing” - Restart VS Code (File → Exit, then reopen) - Try reinstalling the extension

“VS Code can’t find SSH key” - Verify key path in ~/.ssh/config is correct - Check key file exists: ls ~/.ssh/id_sagehen - Check file permissions: chmod 600 ~/.ssh/id_sagehen

Getting Help Before Workshop

If you have trouble with any step:

  • Email:
  • Subject line: “Help with VS Code + Sagehen setup”
  • Include:
    • Exact error message (copy-paste)
    • Your operating system
    • Which step you’re stuck on
    • What you’ve already tried

Summary: You’re Ready When…

  • VS Code is installed and launches
  • Remote-SSH extension is installed
  • You can SSH to Sagehen from terminal: ssh sagehen
  • SSH config file exists at ~/.ssh/config

Once you’ve confirmed all these items, you’re ready for the workshop!