VS Code Remote-SSH

Connect to HPC using VS Code Remote-SSH extension

Use VS Code on your local machine to connect to the HPC via the Remote-SSH extension. This approach runs VS Code locally while editing files and running terminals on the HPC.

For a browser-based VS Code experience running directly on a compute node, see VS Code Server on HPC instead.

Installation

  1. Install VS Code on your local machine
  2. Install the Remote - SSH extension from the marketplace

Optional useful extensions: Jupyter, Python, R, Markdown All in One, Rainbow CSV.

Connect to Head Node

Configure SSH

Press Ctrl+Shift+P on PC (or Cmd+Shift+P on Mac), type in “Remote-SSH: Open SSH Configuration File” and click on it as soon as the complete line appears; then add:

Host hpc
    HostName <hpc_ip>
    User <username>

Replace <hpc_ip> and <username> with your actual HPC IP address and username, see CU_Neurology_HPC_Info_2026.md.

Connect

  1. Press Ctrl+Shift+P on PC (or Cmd+Shift+P on Mac), type in and select “Remote-SSH: Connect to Host”
  2. Select your HPC entry hpc, enter password, wait for connection to establish
  3. Browse files via “Remote Explorer” or File > Open Folder

The status bar at the bottom of VS Code shows your connection status.

Usage Tips

  • Open terminal: Ctrl+`
  • For R language support: pixi global install --environment r-base r-languageserver

Caveats

  • The head node has limited resources. Do not run intensive computations here.
  • Even just for text editing it can take can eat up a lot of resources on the login node If it’s initiated under a directory with lots of sub folder and files; so you should try to open a specific small folder if possible.

Connect to Compute Node

For computations, connect VS Code to a Jupyter server running on a compute node.

Step 1: Request Compute Node

In VS Code terminal (connected to head node):

srun --constraint="cpu2mem16a|cpu2mem16b" --mem=15G --pty bash

Step 2: Start Jupyter

Create ~/start_jupyter.sh once:

cat > ~/start_jupyter.sh << 'SCRIPT'
#!/bin/bash
PORT=$(shuf -i8888-8988 -n1)
rm -rf ~/.local/share/jupyter/runtime/kernel-*.json 2>/dev/null
echo "=========================================="
echo "Jupyter Lab on port $PORT"
echo "=========================================="
jupyter lab --no-browser --ip=0.0.0.0 --port=$PORT \
    --ServerApp.allow_origin='*' \
    --ServerApp.allow_remote_access=True \
    --ServerApp.disable_check_xsrf=True
SCRIPT
chmod +x ~/start_jupyter.sh

Then run:

./start_jupyter.sh

You should see output like:

==========================================
Starting Jupyter Lab on port 8891
==========================================
[I 2026-01-28 11:30:45.123 ServerApp] Jupyter Server 2.x.x is running at:
[I 2026-01-28 11:30:45.123 ServerApp] http://127.0.0.1:8891/lab?token=abc123def456ghi789jkl...

Copy the URL with token from the output.

Step 3: Forward Port

  1. In VS Code, open the PORTS tab (bottom panel, next to TERMINAL)
  2. The port should auto-forward, or click “Forward a Port”
  3. Enter the port number shown in Jupyter output (e.g., 8891)
  4. Verify the port appears in the PORTS list

Step 4: Connect Notebook

  1. Open your .ipynb file in VS Code
  2. Click “Select Kernel” in the top-right corner
  3. Choose “Existing Jupyter Server”
  4. Select “Enter the URL of the running Jupyter server”
  5. Paste the URL, replacing 127.0.0.1 with localhost: 
    http://localhost:8891/lab?token=abc123def456ghi789jkl...
  6. Press Enter

VS Code will save the connection - you won’t need to re-enter the token for this session!

Troubleshooting

“Kernel does not exist” Error

Symptom: Error when running cells about kernel not existing

Solution:

  1. Click the kernel name in top-right corner
  2. Select “Select Another Kernel”
  3. Choose your Python environment again (creates fresh kernel)

Prevention: The script automatically cleans old kernel state on startup

403 Forbidden Errors

Symptom: 403 GET /api/kernelspecs errors in Jupyter output

Solutions:

  1. Verify you’re using the full URL with token
  2. Check the script includes --ServerApp.disable_check_xsrf=True
  3. Ensure --ip=0.0.0.0 is set (not 127.0.0.1)
  4. Try restarting Jupyter with the updated script

Connection Timeout

Symptom: VS Code can’t connect to Jupyter server

Solutions:

  1. Verify your srun job is still running: 
    squeue -u $USER
  2. Check you’re on the correct compute node: 
    hostname
  3. Verify port forwarding in VS Code PORTS tab
  4. Try manually forwarding the port if auto-forward didn’t work

Port Already in Use

Symptom: “Address already in use” error

Solution: The script should automatically finds an available port so this should not happen but if it does:

  1. Kill any existing Jupyter processes: 
    pkill -u $USER jupyter
  2. Run the script again

Job Time Limit Exceeded

Symptom: Jupyter suddenly stops, kernel disconnects

Solution: Request more time when starting:

srun --pty -t 8:00:00 ...  # 8 hours

Notes

  • Cost: Clean up when done: scancel <job_id>
  • Simpler alternative: VS Code Server runs entirely in browser with less setup