HPC Connect for Positron

Seamlessly connect to any HPC cluster (including University of Idaho HPC) from Positron/VS Code. Submit jobs, browse files, and manage your HPC workflows without leaving your IDE.

Features

• 🔌 Easy Connection Management - Save multiple HPC clusters and connect with one click
• 📁 Remote File Browser - Browse, upload, and download files from your HPC
• 🚀 Simple Job Submission - User-friendly form to submit jobs (no need to write SLURM scripts!)
• 📊 Job Monitoring - Real-time view of your running, pending, and completed jobs
• 💻 Integrated Terminal - Open SSH terminal directly in Positron
• 🔐 Multiple Auth Methods - Password, SSH key, or SSH agent authentication

Installation

Step 1: Install Dependencies

First, make sure you have Node.js installed. Then navigate to the extension directory and install dependencies:

cd hpc-connect
npm install

Step 2: Compile the Extension

npm run compile

Step 3: Install in Positron/VS Code

1. Open Positron (or VS Code)
2. Press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
3. Type "Extensions: Install from VSIX"
4. Navigate to the hpc-connect folder
5. If you haven't packaged it yet, run: npx @vscode/vsce package
6. Select the generated .vsix file

OR for development/testing:

1. Open the hpc-connect folder in Positron/VS Code
2. Press F5 to launch a new window with the extension loaded

Quick Start Guide

1. Add Your HPC Cluster

1. Click the HPC icon in the activity bar (left sidebar)
2. Click the "+" button in the Clusters panel
3. Fill in your cluster information:
   • Name: "U of Idaho HPC" (or whatever you want to call it)
   • Host: Your HPC hostname (e.g., hpc.uidaho.edu)
   • Port: Usually 22
   • Username: Your HPC username
   • Auth Method: Choose SSH Key (most common) or Password
   • Scheduler: SLURM (most common)

2. Connect to HPC

1. Click the plug icon (🔌) next to your cluster name
2. Enter your password if prompted
3. You'll see "Connected" when successful

3. Browse Files

1. The "Remote Files" panel shows your HPC files
2. Click folders to expand them
3. Click files to download and view them
4. Use the upload button to send files to HPC

4. Submit a Job

1. Click "HPC: Submit Job" from the command palette (Ctrl+Shift+P)
2. Fill out the simple form:
   • Script Path: Path to your R/Python/shell script on the HPC
   • Job Name: A descriptive name
   • Resources: How many nodes, CPUs, memory you need
   • Time Limit: Maximum run time (HH:MM:SS)
   • Email: (Optional) Get notified when job finishes
3. Click "Submit Job"

5. Monitor Jobs

1. The "Jobs" panel shows all your running jobs
2. Jobs auto-refresh every 10 seconds
3. Click a job to view its output
4. Right-click to cancel a job

Example: Submitting an R Analysis

Let's say you have an R script analysis.R on the HPC that you want to run:

1. Upload your script (if not already on HPC):

   • Click the upload button in Remote Files
   • Select your analysis.R file
   • Choose destination: /home/yourusername/analysis.R

2. Submit the job:

   • Command Palette → "HPC: Submit Job"
   • Script Path: /home/yourusername/analysis.R
   • Job Name: my-analysis
   • Nodes: 1
   • CPUs per Task: 4
   • Memory: 8G
   • Time Limit: 02:00:00
   • Click Submit

3. Monitor progress:

   • Watch the Jobs panel for status updates
   • Click the job to see output when it completes

Tips & Tricks

SSH Key Setup (Recommended)

For password-less authentication:

1. Generate SSH key (if you don't have one):

   ssh-keygen -t rsa -b 4096
   

2. Copy to HPC:

   ssh-copy-id yourusername@hpc.uidaho.edu
   

3. In HPC Connect, choose "SSH Key" auth method and point to ~/.ssh/id_rsa

Resource Guidelines

Not sure what resources to request? Here are some starting points:

• Small job (quick tests): 1 node, 1 CPU, 4G RAM, 00:30:00
• Medium job (typical analysis): 1 node, 4 CPUs, 16G RAM, 02:00:00
• Large job (big datasets): 1 node, 16 CPUs, 64G RAM, 24:00:00

Common SLURM Commands

You can run these in the integrated terminal:

squeue -u $USER          # View your jobs
scancel <jobid>          # Cancel a job
sinfo                    # View cluster info
sacct                    # View job history

Supported Schedulers

• ✅ SLURM (fully supported)
• ⚠️ PBS/Torque (partial support)
• ⚠️ SGE (partial support)

Troubleshooting

Can't Connect

• Check hostname and port
• Verify your username
• Make sure SSH key permissions are correct (chmod 600 ~/.ssh/id_rsa)
• Try connecting manually first: ssh username@hostname

Jobs Not Showing

• Make sure you're connected to the cluster
• Jobs auto-refresh every 10 seconds
• Click the refresh button manually

File Upload Fails

• Check you have write permissions to the destination
• Verify the remote path exists
• Check disk space on HPC

Configuration

All cluster configurations are stored in VS Code settings. You can manually edit them:

1. Open Settings (Ctrl+,)
2. Search for "HPC Connect"
3. Edit the JSON directly if needed

Development

Want to contribute or modify the extension?

# Install dependencies
npm install

# Watch for changes
npm run watch

# Run extension in debug mode
# Press F5 in VS Code

Features Coming Soon

• [ ] Multiple file upload/download
• [ ] Job templates
• [ ] Resource usage visualization
• [ ] SSH key agent support
• [ ] Job array submission
• [ ] Interactive sessions (Jupyter, RStudio)

Support

Having issues? Here's how to get help:

1. Check the Output panel (View → Output → HPC Connect)
2. Check the troubleshooting section above
3. Open an issue on GitHub

License

MIT License - Copyright (c) 2024 Justice Amenyo Kessie

See LICENSE.txt for full details.

Made for researchers by researchers. No CS degree required! 🎓